flexmark java

Ce document fournit une présentation complète de flexmark-java, une implémentation Java hautes performances de l'analyseur CommonMark Markdown. Il détaille ses fonctionnalités, notamment la vitesse, l'extensibilité et le suivi détaillé de la position de la source, ainsi que des instructions pour un démarrage rapide, les extensions disponibles et la migration depuis le pegdown. Le document couvre également ses lignes directrices en matière de développement et de contribution en cours.

flexmark-java

flexmark-java est une implémentation Java de l'analyseur CommonMark (spécification 0.28) utilisant le

bloque d'abord, en ligne après l'architecture d'analyse Markdown.

Ses points forts sont la rapidité, la flexibilité, l'élément source Markdown basé sur l'AST avec des détails sur le

position de la source jusqu'aux caractères individuels des lexèmes qui composent l'élément et

extensibilité.

L'API permet un contrôle granulaire du processus d'analyse et est optimisée pour l'analyse avec un grand

nombre d'extensions installées. L'analyseur et les extensions sont livrés avec de nombreuses options pour l'analyseur

comportement et variations de rendu HTML. L'objectif final est que l'analyseur et le moteur de rendu soient capables

pour imiter d'autres analyseurs avec un grand degré de précision. Ceci est maintenant partiellement terminé avec le

implémentation de l'émulation du processeur Markdown

La motivation pour ce projet était la nécessité de remplacer l'analyseur pegdown dans mon Markdown Navigator.

plugin pour les IDE JetBrains. pegdown a un excellent ensemble de fonctionnalités mais sa vitesse en général est moindre

qu'idéal et pour une entrée pathologique, il se bloque ou se bloque pratiquement pendant l'analyse.

️La version 0.60.0 présente des modifications importantes dues à la réorganisation, au changement de nom, au nettoyage et

optimisation des classes d'implémentation. Les changements sont détaillés dans

Version-0.60.0-Modifications.

dernier

Exigences

Pour les versions 0.62.2 ou inférieures, Java 8 ou supérieure, compatible Java 9+. Pour les versions 0.64.0 ou

supérieur, Java 11 ou supérieur.

Le projet est sur Maven : com.vladsch.flexmark

Le noyau n'a aucune dépendance autre que org.jetbrains:annotations:24.0.1. Pour les extensions, voir

Description de l'extension ci-dessous.

L'API continue d'évoluer pour s'adapter à de nouvelles extensions et fonctionnalités.

Démarrage rapide

Pour Maven, ajoutez flexmark-all comme dépendance qui inclut le noyau et tous les modules au

exemple suivant :

Source:

BasicSample.java

Construire via Gradle

Construire avec Android Studio

Paramètres supplémentaires en raison de fichiers en double :

Plus d’informations peuvent être trouvées dans la documentation :

Exemples d'utilisation de la page d'accueil Wiki

Détails de l'extension

Écriture d'extensions

Aide à la migration Pegdown

La classe PegdownOptionsAdapter convertit les indicateurs pegdown Extensions.* en options flexmark et

liste des extensions. Pegdown Extensions.java est inclus pour plus de commodité et de nouvelles options sont introuvables

dans la version 1.6.0. Ceux-ci se trouvent dans le module flexmark-profile-pegdown mais vous pouvez récupérer le

source de ce dépôt : PegdownOptionsAdapter.java, Extensions.java et créez le vôtre

version, modifiée selon les besoins de votre projet.

Vous pouvez transmettre vos indicateurs d'extension à PegdownOptionsAdapter.flexmarkOptions(int) statique ou vous

peut instancier PegdownOptionsAdapter et utiliser des méthodes pratiques pour définir, ajouter et supprimer

drapeaux d'extension. PegdownOptionsAdapter.getFlexmarkOptions() renverra une nouvelle copie de

DataHolder à chaque fois avec les options reflétant les drapeaux d'extension pegdown.

L'émulation pegdown flexmark-java par défaut utilise une analyse de bloc HTML moins stricte qui interrompt un

Bloc HTML sur une ligne vierge. Pegdown n'interrompt un bloc HTML sur une ligne vide que si toutes les balises

le bloc HTML est fermé.

Pour vous rapprocher du comportement original d'analyse des blocs HTML pegdown, utilisez la méthode qui prend un

Argument booléen strictHtml :

Un exemple avec un résolveur de lien personnalisé est également disponible, qui inclut un résolveur de lien pour

modifier les URL ou les attributs des liens et un moteur de rendu de nœud personnalisé si vous devez remplacer le

lien généré HTML.

flexmark-java a beaucoup plus d'extensions et d'options de configuration que

pegdown en plus des extensions disponibles dans pegdown 1.6.0.

Extensions disponibles via PegdownOptionsAdapter

Derniers ajouts et modifications

Réorganisation majeure et nettoyage du code de l'implémentation dans la version 0.60.0, voir

Version-0.60.0-Modifications grâce à l'excellent travail de

Alex Karezin, vous pouvez avoir un aperçu des dépendances des modules

avec la possibilité d'accéder aux packages et aux classes.

API de fusion pour fusionner plusieurs documents markdown en un seul

document.

Extension du moteur de rendu Docx :

Gestion des nœuds d’attributs limités

Module de conversion HTML vers Markdown extensible :

convertisseur flexmark-html2md. Échantillon:

HtmlToMarkdownCustomizedSample.java

Compatibilité des modules Java9+

Références énumérées composées

Extension de références énumérées pour la création

numérotation légale des éléments et des titres.

Extension de macros pour permettre à du contenu de démarque arbitraire d'être

inséré en tant qu'éléments de bloc ou en ligne, permettant d'utiliser des éléments de bloc là où uniquement en ligne

les éléments sont autorisés par la syntaxe.

GitLab Flavored Markdown pour l'analyse et

rendu des extensions de démarque GitLab.

Module OSGi avec l'aimable autorisation de Dan Klco (GitHub @klcodanr)

Balises média Extension du transformateur Media Link avec l'aimable autorisation

Cornelia Schultz (GitHub @CorneliaXaos) transforme les liens

en utilisant des préfixes personnalisés pour les balises HTML5 Audio, Embed, Picture et Video.

API Translation Helper pour effectuer des démarques de traduction

documents plus facilement.

Admonition Pour créer du contenu secondaire de style bloc. Pour

documentation complète, veuillez consulter l'extension d'avertissement, le matériel pour MkDocs

documentation.

Référence énumérée pour créer une liste énumérée

références pour les figures, tableaux et autres éléments de démarque.

Attributs pour analyser les attributs de la forme {name name=value name='value' name="value" #id .class-name} attributs.

Transformateur de lien intégré YouTube

grâce à Vyacheslav N. Boyko (GitHub @bvn13) transforme de simples liens vers des vidéos youtube en

HTML iframe vidéo intégré.

Docx Converter utilisant la bibliothèque docx4j. Comment utiliser :

Exemple DocxConverter, comment personnaliser :

Personnalisation du rendu Docx

Le développement de ce module a été sponsorisé par

Johner Institut GmbH.

Mettre à jour la bibliothèque pour qu'elle soit conforme à CommonMark (spécification 0.28) et ajouter

ParserEmulationProfile.COMMONMARK027 et ParserEmulationProfile.COMMONMARK028 pour autoriser

en sélectionnant des options de version de spécification spécifiques.

API de rendu de nœud personnalisé avec possibilité d'invoquer le rendu standard pour un nœud remplacé,

permettre des rendus de nœuds personnalisés qui ne gèrent que des cas spéciaux et laisser le reste être rendu comme

habituel. résolveur de liens personnalisé

Problèmes Gfm et

Extensions Gfm-Users pour l'analyse et le rendu #123 et

@nom d'utilisateur respectivement.

Option d'analyse approfondie des blocs HTML pour une meilleure gestion des balises de texte brut qui suivent d'autres balises

et pour la compatibilité de l'analyse des blocs HTML pegdown.

Module flexmark-all qui comprend : le noyau, toutes les extensions, le formateur, JIRA et YouTrack

convertisseurs, module de profil pegdown et conversion HTML vers Markdown.

Module de sortie PDF

Sortie PDF à l'aide d'Open HTML To PDF

Typographie mise en œuvre

Extension de macros XWiki

Jekyll Tags

HTML vers démarque

Plugin générateur de pages Maven Markdown

Module Markdown Formatter pour générer AST sous forme de démarque avec

options de formatage.

Tableaux pour le formateur Markdown

avec largeur de colonne et alignement des tableaux de démarques :

Versions, corrections de bugs, améliorations et support

J'utilise flexmark-java comme analyseur pour le plugin Markdown Navigator pour les IDE JetBrains. J'ai tendance à

utilisez la dernière version inédite pour corriger des bugs ou obtenir des améliorations. Donc, si vous trouvez un bug

un obstacle pour votre projet ou si vous voyez un bug dans la page des problèmes de github marqué comme étant corrigé pour la prochaine version qui affecte votre projet, veuillez me le faire savoir et je pourrai peut-être le faire rapidement

créez une nouvelle version pour résoudre votre problème. Sinon, je laisserai les corrections de bugs et les améliorations

accumulez en pensant que personne n’est affecté par ce qui est déjà réglé.

Les points d'extension dans l'API sont nombreux et nombreux

Il existe de nombreuses options d'extension dans l'API avec leur utilisation prévue. Un bon démarrage en douceur est le

Module flexmark-java-samples qui contient des échantillons simples demandés

extensions. Le deuxième meilleur endroit est la source d'une extension existante qui a une syntaxe similaire

à ce que vous souhaitez ajouter.

Si votre extension correspond à la bonne API, la tâche est généralement très courte et simple. Si votre

l'extension utilise l'API de manière involontaire ou ne suit pas le nettoyage prévu

protocoles, vous trouverez peut-être une bataille difficile avec un nid de rats de gestion des conditions if/else et

corriger un bug ne conduisant qu'à en créer un autre.

Généralement, s'il faut plus de quelques dizaines de lignes pour ajouter une simple extension, alors soit vous

vous vous trompez ou il manque un point d'extension à l'API. Si vous regardez tous les

extensions implémentées, vous verrez que la plupart sont quelques lignes de code autres que la plaque passe-partout

dicté par l'API. C'est le but de cette bibliothèque : fournir un noyau extensible qui permet

écrire des extensions est un jeu d'enfant.

Les extensions les plus grandes sont flexmark-ext-tables et flexmark-ext-spec-example, la viande de

les deux représentent environ 200 lignes de code. Vous pouvez les utiliser comme guide pour estimer la taille de votre

extension.

Ma propre expérience en matière d'ajout d'extensions montre que parfois, un nouveau type d'extension est préférable.

résolu par une amélioration de l'API pour rendre sa mise en œuvre transparente, ou en corrigeant un bug qui

n'était pas visible avant que l'extension ne souligne l'API de la bonne manière. Votre intention

l’extension est peut-être simplement celle qui nécessite une telle approche.

N'hésitez pas à ouvrir un ticket si vous ne trouvez pas la réponse

Ce qu'il faut retenir : si vous souhaitez implémenter une extension ou une fonctionnalité, n'hésitez pas à

ouvrez un problème et je vous donnerai des indications sur la meilleure façon de procéder. Cela peut vous faire économiser beaucoup

de temps en me permettant d'améliorer l'API pour répondre aux besoins de votre extension avant de consacrer beaucoup de temps

efforts infructueux.

Je vous demande de réaliser que je suis le chef cuisinier et laveur de bouteilles sur ce projet, sans

iota de compétences Vulcan Mind Melding. Je vous demande de décrire ce que vous souhaitez mettre en œuvre

parce que je ne peux pas lire dans tes pensées. Veuillez effectuer un travail de reconnaissance autour de la source.

code et documentation car je ne peux pas vous transférer ce que je sais, sans votre volonté

effort.

Des consultations sont disponibles

Si vous avez une application commerciale et que vous ne souhaitez pas écrire la ou les extensions vous-même ou si vous souhaitez

pour réduire le temps et les efforts liés à la mise en œuvre d'extensions et à l'intégration de flexmark-java, ressentez

libre de me contacter. Je suis disponible sur une base de conseil/contrat.

Émulation du processeur Markdown

Malgré son nom, Commonmark n'est ni un sur-ensemble ni un sous-ensemble d'autres saveurs de démarque.

Il propose plutôt une spécification syntaxique standard et sans ambiguïté pour le "noyau" original.

Markdown, introduisant ainsi efficacement encore une autre saveur. Alors que flexmark est par défaut

Conforme aux marques communes, son analyseur peut être modifié de différentes manières. Les ensembles de réglages nécessaires pour

émuler les analyseurs de démarques les plus couramment utilisés sont disponibles dans flexmark comme

ParserEmulationProfiles.

Comme son nom ParserEmulationProfile l'indique, seul l'analyseur est ajusté au

saveur de démarque spécifique. L'application du profil n'ajoute pas de fonctionnalités au-delà de celles disponibles dans

marque commune. Si vous souhaitez utiliser flexmark pour émuler entièrement le comportement d'un autre processeur de démarque,

vous devez ajuster l'analyseur et configurer les extensions flexmark qui fournissent les fonctionnalités supplémentaires

fonctionnalités disponibles dans l’analyseur que vous souhaitez émuler.

Une réécriture de l'analyseur de liste pour mieux contrôler l'émulation d'autres processeurs de démarque selon

L'émulation des processeurs Markdown est terminée. Ajout de

les préréglages du processeur pour émuler le comportement de traitement de démarque spécifique de ces analyseurs sont sur un

courte liste de choses à faire.

Certaines familles d’émulation réussissent mieux que d’autres à émuler leur cible. La plupart de

l'effort visait à émuler la façon dont ces processeurs analysent le Markdown et la liste standard

analyse connexe spécifiquement. Pour les processeurs qui étendent le Markdown d'origine, vous devrez ajouter

les extensions déjà implémentées dans flexmark-java pour le générateur Parser/Renderer

choix.

Les extensions seront modifiées pour inclure leurs propres préréglages pour une émulation de processeur spécifique, si

ce processeur a une extension équivalente implémentée.

Si vous constatez une anomalie, veuillez ouvrir un problème afin qu'il puisse être résolu.

Les principales familles de processeurs sont implémentées et certains membres de la famille également :

profils pour encapsuler les détails de configuration des variantes dans le

La famille a été ajoutée dans la version 0.11.0 :

Histoire et motivation

flexmark-java est un fork du projet commonmark-java, modifié pour générer un AST qui

reflète tous les éléments de la source d'origine, suivi complet de la position de la source pour tous les éléments

dans l'AST et la génération PsiTree JetBrains Open API plus facile.

L'API a été modifiée pour permettre un contrôle plus granulaire du processus d'analyse et optimisée pour

analyse avec un grand nombre d'extensions installées. L'analyseur et les extensions sont livrés avec de nombreux

options de réglage du comportement de l'analyseur et des variations de rendu HTML. L'objectif final est d'avoir le

l'analyseur et le moteur de rendu soient capables d'imiter d'autres analyseurs avec un grand degré de précision.

La motivation pour cela était la nécessité de remplacer l'analyseur pegdown dans le plugin Markdown Navigator.

pegdown a un excellent ensemble de fonctionnalités mais sa vitesse en général est loin d'être idéale et pour

l'entrée pathologique se bloque ou se bloque pratiquement pendant l'analyse.

commonmark-java possède une excellente architecture d'analyse facile à comprendre et à étendre.

L'objectif était de garantir que l'ajout du suivi de la position de la source dans l'AST ne modifierait pas la facilité

d'analyser et de générer l'AST plus que nécessaire.

Les raisons du choix de commonmark-java comme analyseur sont : la rapidité, la facilité de compréhension, la facilité de

extension et vitesse. Maintenant que j'ai retravaillé le noyau et ajouté quelques extensions, je suis extrêmement

satisfait de mon choix.

Un autre objectif était d'améliorer la capacité des extensions à modifier le comportement de l'analyseur afin que tout

Un dialecte de démarque pourrait être implémenté via le mécanisme d'extension. Des options extensibles

L'API a été ajoutée pour permettre la configuration de toutes les options en un seul endroit. Utilisation de l'analyseur, du moteur de rendu et des extensions

ces options de configuration, y compris la désactivation de certains analyseurs de blocs principaux.

Il s'agit d'un travail en cours avec de nombreux changements d'API. Aucune tentative n'est faite pour conserver l'API en arrière

compatibilité avec le projet d'origine et jusqu'à ce que l'ensemble des fonctionnalités soit en grande partie complet, pas même pour

versions antérieures de ce projet.

Comparaison des fonctionnalités

(1)

entrée pathologique flexmark-java de 100 000 [analyses en 68 ms, 100 000] en 57 ms, 100 000

analyse [ ] imbriquée en 55 ms

(2)

entrée pathologique commonmark-java de 100 000 [analyses en 30 ms, 100 000] en 30 ms, 100 000

analyse [ ] imbriquée en 43 ms

(3)

entrée pathologique pegdown de 17 [ analyse en 650 ms, 18 [ en 1300 ms

Progrès

Je suis très satisfait de la décision de passer moi-même à un analyseur basé sur Commonmark-Java.

projets. Même si j'ai dû faire une opération chirurgicale majeure aux entrailles pour obtenir le poste de source complet

suivi et AST qui correspondent aux éléments sources, c'est un plaisir de travailler avec et c'est maintenant un

plaisir de prolonger. Si vous n'avez pas besoin de l'élément de niveau source AST ou du reste de ce que flexmark-java

ajouté et CommonMark est votre analyseur de démarque cible, alors je vous encourage à utiliser

commonmark-java car c'est un excellent choix pour vos besoins et ses performances ne le font pas

souffrir de la surcharge des fonctionnalités que vous n’utiliserez pas.

Repères

Dernière version, 28 janvier 2017, flexmark-java 0.13.1, intellij-markdown de CE EAP 2017, commonmark-java

0.8.0 :

Ratios ci-dessus :

Parce que ces deux fichiers représentent l'entrée pathologique du pegdown, je ne les exécute plus en tant que

partie intégrante du benchmark pour éviter de fausser les résultats. Les résultats sont là pour la postérité.

Ratios ci-dessus :

Contribuer

Les demandes de tirage, les problèmes et les commentaires sont les bienvenus ?. Pour les demandes de tirage :

Licence

Copyright (c) 2015-2016 Atlassian et autres.

Copyright (c) 2016-2023, Vladimir Schneider,

Licence BSD (2 clauses), voir le fichier LICENSE.txt.

exemple:

Moteur de rendu Mitsuba 3

Documentation	Vidéos tutorielles	Linux	Mac OS	Fenêtres	PyPI

️

Avertissement

️

Il existe actuellement un grand nombre de travaux non documentés et instables en cours dans

la branche master . Nous vous recommandons fortement d'utiliser notre

dernière version

jusqu'à nouvel ordre.

Si vous souhaitez déjà tester les modifications à venir, veuillez consulter

ce guide de portage.

Il devrait couvrir la plupart des nouvelles fonctionnalités et des modifications majeures à venir.

Introduction

Mitsuba 3 est un système de rendu orienté recherche pour la lumière directe et inverse

simulation de transport développée à l'EPFL en Suisse.

Il se compose d'une bibliothèque principale et d'un ensemble de plugins qui implémentent des fonctionnalités

allant des matériaux et sources de lumière aux algorithmes de rendu complets.

Mitsuba 3 est reciblable : cela signifie que les implémentations sous-jacentes et

les structures de données peuvent se transformer pour accomplir diverses tâches différentes. Pour

Par exemple, le même code peut simuler à la fois le transport RVB scalaire (classique un rayon à la fois)

ou transport spectral différentiel sur le GPU. Tout cela s'appuie sur

Dr.Jit, un compilateur spécialisé juste à temps (JIT) développé spécifiquement pour ce projet.

Principales caractéristiques

• Multiplateforme : Mitsuba 3 a été testé sur Linux ( x86_64 ), macOS

  ( aarch64 , x8664 ) et Windows ( x8664 ).

• Hautes performances : le compilateur Dr.Jit sous-jacent fusionne le code de rendu

  en noyaux qui atteignent des performances de pointe en utilisant

  un backend LLVM ciblant le CPU et un backend CUDA/OptiX

  ciblant les GPU NVIDIA avec l’accélération matérielle du lancer de rayons.

• Python d'abord : Mitsuba 3 est profondément intégré à Python. Matériels,

  des textures, et même des algorithmes de rendu complets peuvent être développés en Python,

  que le système compile JIT (et éventuellement différencie) à la volée.

  Cela permet l'expérimentation nécessaire à la recherche en infographie et

  d'autres disciplines.

• Différenciation : Mitsuba 3 est un moteur de rendu différenciable, ce qui signifie qu'il

  peut calculer les dérivées de l'ensemble de la simulation par rapport à l'entrée

  des paramètres tels que la pose de la caméra, la géométrie, les BSDF, les textures et les volumes. Il

  implémente des algorithmes de rendu différenciables récents développés à l'EPFL.

• Spectral & Polarisation : Mitsuba 3 peut être utilisé comme monochromatique

  rendu, un rendu basé sur RVB ou un rendu spectral. Chaque variante peut

  éventuellement tenir compte des effets de polarisation si vous le souhaitez.

Vidéos tutorielles, documentation

Nous avons enregistré plusieurs vidéos YouTube qui fournissent une introduction douce

Mitsuba 3 et Dr Jit. Au-delà de cela, vous pouvez trouver des cahiers Juypter complets

couvrant une variété d'applications, de guides pratiques et de documentation de référence

sur readthedocs.

Installation

Nous fournissons des roues binaires précompilées via PyPI. Installer Mitsuba de cette façon est aussi simple que d'exécuter

 pip installer mitsuba

sur la ligne de commande. Le package Python comprend treize variantes par défaut :

• scalar_rgb

• scalar_spectral

• scalarspectralpolarized

• llvmadrgb

• llvmadmono

• llvmadmono_polarized

• llvmadspectral

• llvmadspectral_polarized

• cudaadrgb

• cudaadmono

• cudaadmono_polarized

• cudaadspectral

• cudaadspectral_polarized

Les deux premiers effectuent une simulation classique d'un rayon à la fois en utilisant soit un RVB

ou représentation spectrale des couleurs, tandis que les deux derniers peuvent être utilisés pour l'inverse

rendu sur le CPU ou le GPU. Pour accéder à des variantes supplémentaires, vous devrez

compilez une version personnalisée de Dr.Jit à l'aide de CMake. Veuillez consulter le

documentation

pour plus de détails à ce sujet.

Exigences

• Python >= 3.8

• (facultatif) Pour le calcul sur le GPU : Nvidia driver >= 495.89

• (facultatif) Pour le calcul vectorisé/parallèle sur le CPU : LLVM >= 11.1

Usage

Voici un exemple simple de « Hello World » qui montre à quel point il est simple de restituer un

scène utilisant Mitsuba 3 de Python :

 # Importez la bibliothèque en utilisant l'alias "mi" import mitsuba as mi# Définir la variante du renderermi.setvariant('scalarrgb')# Charger une scènecene = mi.loaddict(mi.cornellbox())# Rendre la scèneimg = mi. render(scene)# Écrit l'image rendue dans un fichier EXR mi.Bitmap(img).write('cbox.exr')

Des didacticiels et des exemples de cahiers couvrant une variété d'applications peuvent être trouvés

dans la documentation.

À propos

Ce projet a été créé par Wenzel Jakob.

Des fonctionnalités et/ou améliorations importantes du code ont été apportées par

Sébastien Speierer,

Nicolas Roussel,

Merlin Nimier-David,

Délio Vicini,

Tizian Zeltner,

Baptiste Nicolet,

Miguel Crespo,

Vincent Leroy, et

Ziyi Zhang.

Lorsque vous utilisez Mitsuba 3 dans des projets académiques, veuillez citer :

 @software{Mitsuba3,title = {Mitsuba 3 renderer},author = {Wenzel Jakob et Sébastien Speierer et Nicolas Roussel et Merlin Nimier-David et Delio Vicini et Tizian Zeltner et Baptiste Nicolet et Miguel Crespo et Vincent Leroy et Ziyi Zhang},note = {https://mitsuba-renderer.org},version = {3.1.1},année = 2022}