Science hubs & hub Sciences: HUB text/PAO une syntaxe pour différentes cibles input et output (backends, targets ou writers), de manière à obtenir du HTML du LaTeX, page de man: pandoc

Thursday, July 20, 2017

HUB text/PAO une syntaxe pour différentes cibles input et output (backends, targets ou writers), de manière à obtenir du HTML du LaTeX, page de man: pandoc

hexadécimal

Au départ si on a que du texte sans mise en forme, on peut écrire en hexadécimal comme dans ma jeunesse des années 70 (en ASCII ou étendue pour les caractères français par exemple). Il suffisait de connaitre par coeur la table ASCII de 128 correspondances qui est une norme informatique de codage de caractères des années 60. Et tout cela avec un clavier de 0-9 et A-F soit 16 touches (même pas une touche carriage return car c'est le code #D ni même une touche espace car c'est #20)!
http://ascii.cl/
Et pour l'histoire:
https://fr.wikipedia.org/wiki/American_Standard_Code_for_Information_Interchange

C'était clair, il y avait celui qui tapait ses idées au kilomètre puis celui qui mettait en forme.

que du text mis en forme (et un peu de "PAO") et comparaison des softs

Si on a que text (par exemple ASCII ou UTF-8) c'est assez simple.
Avec du balisage léger et des transcodeurs, on a du Hub-text.
voir une liste partielle des output formats:
https://en.wikipedia.org/wiki/Lightweight_markup_language

https://en.wikipedia.org/wiki/Comparison_of_document_markup_languages

https://en.wikipedia.org/wiki/Comparison_of_documentation_generators
(and programming languages).
example: ROBODoc is a documentation tool similar to Javadoc and licensed under the GPL. It is used to extract API documentation from source code. It can be used with any language that supports comments and works by extracting specially formatted headers. These are then reformatted into HTML, DocBook, TROFF, ASCII, LaTeX, PDF, or RTF.
It can be used to document any programming artifact, such as: classes, functions, tests, makefile entries, etc.
ROBODoc works with C, C++, Fortran, Perl, shell scripts, Assembler, DCL, DB/C, Tcl/Tk, Forth, Lisp, COBOL, Occam, Basic, HTML, Clarion, and any other language that supports comments.
https://en.wikipedia.org/wiki/ROBODoc

Une analyse que je partage

Comparaison des langages de balisage (markup) léger (lightweight) : Txt2tags, Pandoc, Docutils, AsciiDoc, Deplate, Stx2any, AFT, Markdown et Textile:
http://fgallaire.flext.net/comparaison-langage-balisage-markup-lightweight-leger-txt2tags-pandoc-docutils-asciidoc-deplate-stx2any-aft-markdown-textile/

La bureautique est la principale utilisation de l’informatique depuis sa création. Pourtant, les outils majoritairement utilisés dans ce domaine, les logiciels de traitement de texte WYSIWYG comme LibreOffice ou MS word, laissent la majorité des informaticiens et des ergonomes totalement désespérés.
Ces logiciels ont en effet un nombre de défauts très important : ils font se concentrer sur la forme et non sur le fond, leur résultat final ne correspond souvent pas à ce qui est affiché, ils sont incompatibles entre eux, ce sont d’énormes usines à gaz, ils ne fonctionnent qu’en mode graphique, etc.

Il a donc fallu penser à une manière de donner ces instructions de mise en forme au sein du fichier texte lui-même, et c’est ainsi que sont apparus les langages de balisage (markup), dont les plus connus sont HTML (inventé en 1991 par Tim Berners-Lee) et LaTeX (créé en 1985, et basé sur TeX, inventé par le grand Donald Knuth en 1977), et dont la première grande figure fut Roff, un programme Unix historique développé à partir de 1961, et dont la version GNU, Groff, est installée par défaut sur toutes les distributions GNU/Linux, puisqu’on l’utilise encore pour les pages de man des logiciels.

Ces langages représentent une nette amélioration, mais ont tous un gros problème : ils sont gênants ! On ne retrouve plus aussi facilement son contenu au milieu de toutes ces balises supplémentaires, sans parler du fait que les syntaxes complexes ouvrent la voie à de nombreuses erreurs de compilation.

C’est en 1995 que l’on trouva la solution de ce problème, avec la création du premier langage Wiki, dont le but principal était de permettre l’édition facile de pages web par tout un chacun, et dont l’utilisateur actuel le plus célèbre est l’encyclopédie libre Wikipédia. S’il y a presque autant de syntaxes différentes que de logiciels Wiki, elles ont toutes la caractéristique d’utiliser des caractères textuels simples et intuitifs pour donner les indications de formatage du texte.
http://www.wikicreole.org/wiki/Reasoning

https://www.mediawiki.org/wiki/Help:Formatting
https://fr.wikipedia.org/wiki/Aide:Syntaxe_(wikicode)
https://fr.wikipedia.org/wiki/Aide:Ins%C3%A9rer_un_tableau_(wikicode,_avanc%C3%A9)
https://fr.wikipedia.org/wiki/Mod%C3%A8le:BUtilisateur
https://www.mediawiki.org/wiki/MediaWiki/fr

J'ai toujours aimé le principe du "folding editor".
le premier fut STET 'STructured Editing Tool' de 1977
https://en.wikipedia.org/wiki/STET_(text_editor)
A folding editor is a text editor which supports text folding or code folding, a mechanism allowing the user to hide and reveal blocks of text—usually named. Typically this is done to allow the user to better picture the overall structure of a document or program.
Folding is provided by many modern text editors, and syntax-based or semantics-based folding is now a component of many software development environments...
https://en.wikipedia.org/wiki/Folding_editor

Mais pourquoi limiter ces langages de balisage léger à la seule génération de HTML ? Pourquoi ne pas utiliser la même syntaxe pour différentes cibles (appelées backends, targets ou writers selon les logiciels), de manière à obtenir aussi bien une page web en HTML, qu’un document en LaTeX pour l’impression, ou qu’une page de man pour un logiciel ? Ce sont les logiciels qui poursuivent ce but qui m’intéressent, ils constituent pour moi l’avenir de la bureautique informatique, et j’ai été amené à les comparer pour en choisir un dans lequel m’investir comme développeur.

Trois d’entre eux, Docutils, Deplate et Pandoc, ont un design évolué, avec une machine à états finis pour laquelle on peut écrire de nouveaux readers et writers de manière parfaitement propre. Cependant, malgré leurs grandes qualités, Deplate est un projet trop confidentiel (ainsi il n’est incompréhensiblement pas présent parmi les pourtant si nombreux paquets Debian), et je ne me sentais pas à la hauteur pour m’investir dans un projet comme Pandoc, totalement écrit en Haskell, qui est un langage de programmation complexe que j’aimerais beaucoup utiliser.
Je détaillerai Pandoc ci-dessous.

Txt2tags

J’ai rajouté dans ce comparatif Markdown et Textile, puisqu’ils ont chacun une implémentation en Python, mais ne générant que du HTML, ils ne m’intéressaient pas vraiment. AsciiDoc et Txt2tags ont un peu la même architecture, avec un gros fichier principal faisant tout le travail, que l’on peut configurer, respectivement avec un fichier .conf et deux dictionnaires Python (un pour les Tags et l’autre pour les Rules), pour créer de nouvelles cibles. AsciiDoc et Txt2tags sont donc plus aisés à prendre en main et à modifier rapidement que Docutils, qui est une très belle et très bien architecturée machine à états objet, mais aussi plus difficile à appréhender.
De plus, comme je désapprouvais totalement la politique de licence domaine publique de Docutils, il ne me restait plus qu’à faire mon choix entre Txt2tags et AsciiDoc. C’est principalement l’orientation très DocBook (un format ne m’intéressant personnellement pas du tout) d’AsciiDoc, et d’autres détails, comme la localisation en de nombreuses langues de Txt2tags et sa plus grande simplicité, qui m’ont finalement fait choisir Txt2tags.

Ce choix est confirmé par une étude plus avancée des différentes syntaxes. Ainsi alors que la syntaxe reST de Docutils ne dispose que de :

*italique* et **gras**

Txt2tags est beaucoup plus riche :

//italique// **gras** __souligné__ et --barré--

Le codage visuel est bien meilleur, et le compréhension instantanée avec la syntaxe de Txt2tags, puisque les slashs donnent l’impression penchée de l’italique, les étoiles imitent la surcharge du gras, les underscores donnent l’impression de soulignement, et les moins apparaissent comme une barre. De plus, l’utilisation généralisée des caractères de balisage en doubles, permet de lever à peu de frais un maximum d’ambiguïtés syntaxiques.

insertion d'une image est beaucoup plus simple Txt2tags
[[picture.png] http://fgallaire.flext.net]

Leur implémentation en Python permet à Txt2tags, reST (par Docutils) et AsciiDoc d’être utilisables à la fois comme logiciels de bureautique multiplateforme (Linux, Mac OS X, Windows et *BSD) et pour le web côté serveur. Depuis 2012, une implémentation de txt2tags en PHP est disponible, développée par Petko Yotov (le mainteneur et principal développeur de PmWiki) et sponsorisée par Eric Forgeot. Grâce aux nombreux efforts de ce dernier, il existe maintenant plusieurs implémentations de la syntaxe Txt2tags en JavaScript, avec une démo parfaitement fonctionnelle des possibilités de rendu côté client en temps réel. Et Matthew Pickering a quant à lui écrit un reader Txt2tags pour Pandoc.

En face, Markdown est représenté par une armada d’implémentations dans tous les langages utilisés sur le web côté serveur, et aussi en JavaScript côté client pour des prévisualisations efficaces sans Ajax, mais seul Pandoc, qui n’est pas si facile à compiler sur toutes les plateformes, propose autre chose qu’un rendu en HTML.

Je vais bien sûr continuer à travailler sur le logiciel Txt2tags, mais une implémentation de la syntaxe Txt2tags dans un parser Docutils, pour toucher directement toute la communauté des développeurs Python qui documentent leurs projets, et pouvoir bénéficier ensuite du sublime Sphinx, est un projet qui me motive de plus en plus.

Enfin, je suis toujours un peu nostalgique devant ce screenshot, parce que c’est en le voyant, avec en haut à gauche le fichier avec les balises, et en bas à droite celui avec le résultat texte brut, que j’ai pris conscience que Txt2tags faisait bien ce que j’espérais, et que comme en plus il était en Python, ce serait probablement le logiciel auquel j’allais contribuer !

Pandoc

Pandoc is a command-line tool. There is no graphic user interface.

Pandoc is a Haskell library for converting from one markup format to another, and a command-line tool that uses this library. It can read Markdown, CommonMark, PHP Markdown Extra, GitHub-Flavored Markdown, MultiMarkdown, and (subsets of) Textile, reStructuredText, HTML, LaTeX, MediaWiki markup, TWiki markup, Haddock markup, OPML, Emacs Org mode, DocBook, Muse, txt2tags, Vimwiki, EPUB, ODT, and Word docx; and it can write plain text, Markdown, CommonMark, PHP Markdown Extra, GitHub-Flavored Markdown, MultiMarkdown, reStructuredText, XHTML, HTML5, LaTeX (including beamer slide shows), ConTeXt, RTF, OPML, DocBook, OpenDocument, ODT, Word docx, GNU Texinfo, MediaWiki markup, DokuWiki markup, ZimWiki markup, Haddock markup, EPUB (v2 or v3), FictionBook2, Textile, groff man, [groff ms], Emacs Org mode, AsciiDoc, InDesign ICML, TEI Simple, Muse and Slidy, Slideous, DZSlides, reveal.js or S5 HTML slide shows. It can also produce PDF output on systems where LaTeX, ConTeXt, pdfroff, or wkhtmltopdf is installed.

Pandoc's enhanced version of Markdown includes syntax for footnotes, tables, flexible ordered lists, definition lists, fenced code blocks, superscripts and subscripts, strikeout, metadata blocks, automatic tables of contents, embedded LaTeX math, citations, and [Markdown inside HTML block elements][Extension: markdown_in_html_blocks]. (These enhancements, described further under Pandoc's Markdown, can be disabled using the markdown_strict input or output format.)

In contrast to most existing tools for converting Markdown to HTML, which use regex substitutions, pandoc has a modular design: it consists of a set of readers, which parse text in a given format and produce a native representation of the document, and a set of writers, which convert this native representation into a target format. Thus, adding an input or output format requires only adding a reader or writer.

Because pandoc's intermediate representation of a document is less expressive than many of the formats it converts between, one should not expect perfect conversions between every format and every other. Pandoc attempts to preserve the structural elements of a document, but not formatting details such as margin size. And some document elements, such as complex tables, may not fit into pandoc's simple document model. While conversions from pandoc's Markdown to all formats aspire to be perfect, conversions from formats more expressive than pandoc's Markdown can be expected to be lossy.

This document is for people who are unfamiliar with command line tools. Command-line experts can go straight to the User’s Guide or the pandoc man page:

http://pandoc.org/getting-started.html

https://pandoc.org/MANUAL.html

Modules

In contrast to most existing tools for converting Markdown to HTML, pandoc has a modular design: it consists of a set of readers, which parse text in a given format and produce a native representation of the document, and a set of writers, which convert this native representation into a target format. Thus, adding an input or output format requires only adding a reader or writer.

Text
- Text.Pandoc

Ref.

https://hackage.haskell.org/package/pandoc

Pandoc’s enhanced version of Markdown

Pandoc’s enhanced version of Markdown includes syntax for footnotes, tables, flexible ordered lists, definition lists, fenced code blocks, superscripts and subscripts, strikeout, metadata blocks, automatic tables of contents, embedded LaTeX math, citations, and Markdown inside HTML block elements. (These enhancements, described further under Pandoc’s Markdown, can be disabled using the markdown_strict input or output format.)

http://pandoc.org/MANUAL.html#pandocs-markdown

Tricks

you have a long markdown file in GitHub and want to have a TOC, you can use

pandoc -t markdown_github --toc -o example-with-toc.md example.md

Using Markdown Templates

Math in Pure Markdown

https://github.com/jgm/pandoc/wiki/Pandoc-Tricks

Science hubs & hub Sciences

Pages