====Description====

Un éditeur de texte de type markdown.

[[https://asciidoctor.org/|Site Web]]

====Installation====

===Manuelle===

  * Installer [[https://rubyinstaller.org/downloads/|Ruby]]
  * Installer AsciiDoc : ''gem install asciidoctor''

===Docker===

  docker pull asciidoctor/docker-asciidoctor

Pour exécuter une convertion, on lance docker puis asciidoctor.

  docker run -v <your directory>:/documents/ --name asciidoc-to-html asciidoctor/docker-asciidoctor
  asciidoctor -D /documents/output --out-file=specifications.fr.html doc/specifications/readme.fr.asciidoc

====Editeur====

Utiliser une interface graphique avec [[prog:vsc|Visual Studio Code]] :
  * Installer [[https://code.visualstudio.com/download/|Visual Studio Code]]
  * Installer l'extension depuis [[https://marketplace.visualstudio.com/items?itemName=asciidoctor.asciidoctor-vscode|Visual Studio Code]] [[https://github.com/asciidoctor/asciidoctor-vscode|Source github]]
  * Installer et exécuter [[https://github.com/plantuml/plantuml-server|PlantUML Server]] via Docker : ''docker run -d -p 8080:8080 plantuml/plantuml-server:tomcat''
  * Configurer le module pour utiliser plantuml : éditer les préférences utilisateurs et ajouter :
<code javascript>
    "asciidoc.preview.attributes": {
        "plantuml-server-url": "http://localhost:8080"
    }
</code>
  * Activer l'aperçu via ''ctrl+shift+v''.
====Traduction====

Cela se fait avec le paquet [[prog:po4a|po4a]].

  * Création du fichier de traduction

Utiliser le code de langage conformément à la norme ISO 639.

  po4a-gettextize -f asciidoc -m documentation.asciidoc -p documentation_fr-FR.po

  * Traduire la documentation

On peut utiliser [[prog:poedit|poedit]]

  * Création du fichier

  po4a-translate -f asciidoc -m documentation.asciidoc -p documentation_fr-FR.po -l documentation_fr-FR.asciidoc -k 0

  * Mettre à jour le fichier de traduction suite à la mise à jour de la documentation

  po4a-updatepo -f asciidoc -m documentation.asciidoc -p documentation_fr-FR.asciidoc

====Travis====

Le projet fourni une image Travis qu'il est possible d'intégrer à GitHub.

La page ci-dessous explique parfaitement comment faire. Par contre, l'interface de Travis a changé depuis et il faudra un peu chercher.

[[http://mgreau.com/posts/2016/03/28/asciidoc-to-gh-pages-with-travis-ci-docker-asciidoctor.html|Convert AsciiDoc to HTML/PDF & publish to GitHub Pages with Travis CI and Asciidoctor Docker containers]] {{ :prog:asciidoc:convert_asciidoc_to_html_pdf_publish_to_github_pages_with_travis_ci_and_asciidoctor_docker_containers_2020-04-04_10_58_48_am_.html |Archive du 28/03/2016 le 04/04/2020}}

====Attributs====

===HTML===

  :last-update-label!:

Désactive la génération de la date lors du rendu HTML. Intéressant pour faire un diff sans se préoccuper de ce paramètre.

===Coloration syntaxique===

Utilise [[https://highlightjs.org/|highlight.js]].

  * Exemple

<code>
:source-highlighter: highlight.js
:highlightjsdir: highlight

[source,sh]
----
mkdir build
----
</code>

  * Compilation

Ici, on ne compile que le langage ''bash'' et ''cpp''.

<code bash>
git clone --depth=1 https://github.com/highlightjs/highlight.js.git
cd highlightjs
node tools/build.js -t browser cpp bash
</code>

''highlight.min.js'' est dans le dossier ''build''.

Ensuite, il faut garder l'architecture suivante à coté du fichier HTML généré :

<code>
+highlight
   |highlight.min.js
   +styles
      |github.min.css
</code>

Pour le style, il faut prendre l'un des fichiers dans ''highlight.js\build\demo\styles'' et impérativement lui dossier le nom de fichier ''github.min.css''.