SwarmLab-HowTos/labs/Howtos/doclive/asciidoc.adoc

= Ascii Convert !
Apostolos rootApostolos@swarmlab.io
// Metadata:
:description: Intro and Install
:keywords: iot, swarm. docker
:data-uri:
:toc: right
:toc-title: Table of contents
:toclevels: 4
:source-highlighter: highlight
:icons: font
:sectnums: 

{empty} +

****
Asciidoctor is a fast text processor and publishing toolchain for converting AsciiDoc content to HTML5, DocBook 5, EPUB3, PDF and other formats. Asciidoctor is the leading implementation of the AsciiDoc syntax, first introduced and implemented in the Python-based AsciiDoc project.
****


== Convert

- Open a console

- Switch to the directory that contains  *.adoc documents

- Call the Asciidoctor processor with the  command


.Convert  example
[NOTE]
====
[source,bash]
----
docker run --rm -v $(pwd):/documents/ registry.vlabs.uniwa.gr:5080/swarmlab-asciidoctor asciidoctor --safe -b html5  -a theme=flask -a toc2 -a toc-placement=right -o ./path/to/FILENAME.html   ./path/from/FILENAME.adoc
----
Please note, there is a **asciidoctor** in ./path
====

.Convert2html/pdf
[source,bash]
----
pathname="$1" // <1>
docker run --rm -v $PWD:/documents/  asciidoctor/docker-asciidoctor asciidoctor       --safe -b html5  -a theme=flask -a toc2 -o $pathname.html   $pathname // <2>
docker run --rm -v $PWD:/documents/  asciidoctor/docker-asciidoctor asciidoctor-pdf   --safe -a toc  -o $pathname.pdf   $pathname // <3>
----
<1> The first argument from a command line can be found with the positional parameter $1.
<2> See asciidoctor -b html5 options
<3> See asciidoctor-pdf option


=== More options

More options

- diagrams         with  *asciidoctor-diagram*     options
- presentation     with  *asciidoctor-revealjs* -a revealjsdir=https://cdnjs.cloudflare.com/ajax/libs/reveal.js/3.9.2 option
- mathematical     with  *asciidoctor-mathematical* option
- etc


== Why AsciiDoc?

* It is only *TEXT.* So you can *"versioning"* and  *collaborate* https://git-scm.com/book/en/v2/Getting-Started-About-Version-Control[More info^]

* Standardized format


** The formatting of Asciidoc is standardized so there is only one 'flavor' unlike in Markdown. The definitive user guide is  http://asciidoctor.org/docs/asciidoc-writers-guide/[here^]

* Asciidoctor can convert directly to HTML or DocBook. 



AsciiDoc is about being able to focus on expressing your ideas, writing with ease and passing on knowledge without the distraction of complex applications or angle brackets.

AsciiDoc works because:

- It’s readable
- It’s concise
- It’s comprehensive
- It’s extensible
- It produces beautiful output (HTML, DocBook, PDF, ePub and more)

AsciiDoc is easy to write and easy to read (in raw form). It’s also easy to proof and edit. After all, it’s plain text, just like that familiar e-mail.

Best of all, it only requires a text editor to read or write.



== AsciiDoc vs  Markdown

The defacto lightweight markup language is Markdown. (At least, that’s what you call it at first). *The main advantage of Markdown lies in its primitive syntax:* its manual and cheatsheet are one and the same. *But this advantage is also its greatest weakness.*

As soon as authors need something slightly more complex than basic prose (e.g., tables, cross references, footnotes, embedded YouTube videos, etc.), they find themselves *resorting to embedded HTML* or seeking out more feature-rich implementations. Markdown has become a maze of different implementations, termed “flavors”, which make a universal definition evasive.
[NOTE]
====	
The IETF has declared “there is no such thing as "invalid" Markdown.” https://tools.ietf.org/html/rfc7763#section-1.1[See This Is Markdown! Or: Markup and Its Discontents.]
====

Here’s how the story inevitably goes. 

- You start out with Markdown. 
- Then it’s Markdown + X. 
- Then Markdown + X + Y. 
- And down the rabbit hole you go. 

*What’s worse, X and Y often require you to sprinkle in HTML, unnecessarily coupling content with presentation and wrecking portability. Your instinct to choose Markdown is good. There are just better options.*

== Setup live preview Using a web browser 


All you need to preview an AsciiDoc document in a web browser is to install 

- the https://chrome.google.com/webstore/detail/asciidoctorjs-live-previe/iaalpfgpbocpdfblpnhhgllgbdbchmia[Chrome extension] 
- or the https://addons.mozilla.org/en-US/firefox/addon/asciidoctorjs-live-preview[Firefox add-on] 
- or the https://addons.opera.com/fr/extensions/details/asciidoctorjs-live-preview[Opera extension] 

Then you can see the AsciiDoc file rendered as HTML just by visiting it!

.Live Preview
image:tiled-editor-and-web-preview.png[alt="Swarmlab"]

=== Installing the Chrome Extension

. Download https://github.com/asciidoctor/asciidoctor-chrome-extension/releases/download/v1.5.4.100/asciidoctor-chrome-extension.nex[asciidoctor-chrome-extension.nex]
. Open chrome://extensions
. Drag'n'drop the `.nex` file into the page to install

=== Installing the Firefox Extension

. Download https://github.com/asciidoctor/asciidoctor-firefox-addon/releases/download/v0.5.3/asciidoctor-firefox-addon-0.5.3-signed.xpi[asciidoctor-firefox-addon.xpi]
. Open the file with Firefox to install

=== Installing the Opera Extension

. Dowload https://github.com/asciidoctor/asciidoctor-chrome-extension/releases/download/v1.5.4.100/asciidoctor-chrome-extension.nex[asciidoctor-chrome-extension.nex]
. Open opera://extensions
. Drag'n'drop the `.nex` file into the page to install

== Install Docker


****
Docker is a set of platform as a service (PaaS) products that use OS-level virtualization to deliver software in packages called containers.

Containers are isolated from one another and bundle their own software, libraries and configuration files; they can communicate with each other through well-defined channels
****

http://docs.swarmlab.io/SwarmLab-HowTos/labs/Howtos/docker/install.adoc.html[installation^]

That's all folks! :-)