Add syntax help to cli

[mojavelinux]

AsciiDoc Python shows a quick reference when you type asciidoc --help syntax. We should do something similar in Asciidoctor. I propose that we respond to both --help syntax as well as just --syntax.

asciidoc --help syntax

AsciiDoc Markup Syntax Summary
==============================

A summary of the most commonly used markup.
For a complete reference see the 'AsciiDoc User Guide'.

Text formatting
---------------
  *bold text*                 (boldface font)
  _emphasized text_           (normally italics)
  'emphasized text'
  +monospaced text+           (proportional font)
  `monospaced text`           (inline literal passthrough)

Document links
--------------
  [[id]]                      (define link target)
  <<id,caption>>              (link to target id)
  link:filename#id[caption]   (link to external HTML file)

URLs
----
  Use normal URL and email addess syntax or:

  http:address[caption]       (link to web page)
  mailto:address[caption]     (link to mail recipient)

Images
------
  image:filename[caption]     (inline image)
  image::filename[caption]    (block image)

Document header
---------------

  The Document Title
  ==================
  author <email>
  revision, date

author, email, revision and date are optional.

Section title underlines
------------------------
  Underlined:

  Level 0                     (document title)
  =======
  Level 1
  -------
  Level 2
  ~ ~ ~ ~
  Level 3
  ^^^^^^^
  Level 4                     (bottom level)
  +++++++

  Single line:

  = Level 0 =                 (document title)
  == Level 1 ==
  === Level 2 ===
  ==== Level 3 ====
  ===== Level 4 =====         (bottom level)

Paragraphs
----------
A normal paragraph.           (styles: literal,verse,quote,listing,
                                       NOTE,TIP,WARNING,IMPORTANT,CAUTION)
  An indented literal
  paragraph.

Delimited blocks
----------------
Delimiters must begin at left margin.

  -------------------         (styles: source,music,graphviz)
  listing block
  -------------------

  ...................         (styles: listing,verse)
  literal block
  ...................

  *******************
  sidebar block
  *******************

  [style, author, cite]
  ___________________         (styles: quote,verse)
  quote block
  ___________________

  ===================         (styles: NOTE,TIP,WARNING,
  example block                        IMPORTANT,CAUTION)
  ===================

  ///////////////////
  comment block
  ///////////////////

  +++++++++++++++++++         (styles: pass,asciimath,latexmath)
  passthrough block
  +++++++++++++++++++

  [style]                     (styles: abstract,partintro)
  --
  open block
  --

More block elements
-------------------
  [attributes list]
  .Block title
  // Comment line
  include::filename[]

Tables
------
  .An example table
  [width="40%",cols="^,2m",frame="topbot",options="header,footer"]
  |======================
  |Column 1 |Column 2
  |1        |Item 1
  |2        |Item 2
  |3        |Item 3
  |6        |Three items
  |======================

  Common attributes:

  grid:    none,cols,rows,all
  frame:   topbot,none,sides,all
  options: header,footer
  format:  psv,csv,dsv
  valign:  top,bottom,middle
  width:   1%..100%
  cols:    colspec[,colspec,...]

  colspec:    [multiplier*][align][width][style]
  multiplier: 1...
  width:      1... or 1%...100%
  align:      [horiz][.vert]
               horiz: < (left), ^ (center), > (right)
               vert:  < (top),  ^ (middle), > (bottom)
  style:      d[efault], e[mphasis], m[onospaced], a[sciidoc],
              s[trong], l[iteral], v[erse], h[eader]
  cell:       [cellspec]|data
  cellspec:   [span*|+][align][style]
  span:       [colspan][.rowspan]
               colspan: 1...
               rowspan: 1...

Bulleted lists
--------------
  - item text
  * item text
  ** item text
  *** item text
  **** item text
  ***** item text

  (styles: callout,bibliography)

Numbered lists
--------------
  1. arabic (decimal) numbering
  a. loweralpha numbering
  F. upperalpha numbering
  iii) lowerroman numbering
  IX) upperroman numbering

  . arabic (decimal) numbering
  .. loweralpha numbering
  ... lowerroman numbering
  .... upperalpha numbering
  ..... upperroman numbering

  (styles: arabic,loweralpha,upperalpha,lowerroman,upperroman)

Labeled lists
-------------
  label:: item text
  label;; item text
  label::: item text
  label:::: item text

  (styles: horizontal,vertical,glossary,qanda,bibliograpy)

More inline elements
--------------------
  footnote:[footnote text]    (document footnote)

[ggrossetie]

This would be a great addition!

How do you plan to emphasis Asciidoctor syntax ? Maybe we should also add a link to the AsciiDoc Syntax Quick Reference.

[mojavelinux]

I think we'll just create something from scratch. I like the idea of the link to the online version. Ultimately, the quick reference and this should become the same and the existing quick reference should become the complete syntax reference (as we've talked about doing for a long time).

[mojavelinux]

Here's another article from which to draw some ideas. http://www.mimiz.fr/en/asciidoc-asciidoctor-first-step-and-first-thoughts/

[mojavelinux]

Here's another proposal. https://duckduckgo.com/?q=asciidoc+cheat+sheet&ia=answer&iax=1

The goal here is to settle on draft of the cheatsheet so that we can begin to integrate it.

[mojavelinux]

I don't like how the cheat sheet on DuckDuck go only recommends the double marks (unconstrained) for inline formatting. It's important that we make the distinction from single marks (constrained).

[jaredmorgs]

This seems to be something that needs to be addressed in core, rather than being ported over to .org.

I wonder though: would some extra Tech Writer eyes on the content be a good idea.

I wonder if breaking down the syntax groups in the command line help could be useful.

For example:

asciidoctor --help tables could access the quick reference syntax summary just for tables, then have a link to the tables anchor in the user guide.

asciidoctor --help could prompt the user with a menu prompt that lets the user select an option that matches a pre-defined list of help topics. You could then include --help commands in with --help tables for a rich in-terminal help experience.

[mojavelinux]

would some extra Tech Writer eyes on the content be a good idea.

Absolutely! Without a doubt.

We desperately need a canonical cheat sheet document that can be understood at a glance. We have inklings of one all over the place, but have yet to put together something solid.

The best way to approach this may be to start with the output of asciidoc --help syntax, modernize the syntax, clean up the examples, add Asciidoctor-specific features, then iterate from there.

asciidoctor --help tables could access the quick reference syntax summary just for tables, then have a link to the tables anchor in the user guide.

Excellent idea. We could use section IDs for this.

asciidoctor --help could prompt the user with a menu prompt that lets the user select an option that matches a pre-defined list of help topics.

That may be out of scope for this issue, but an excellent idea for the next phase.

[mojavelinux]

What I recommend is adding a file named data/reference/syntax.adoc, paste the output from asciidoc --help syntax, commit it and send a pull request. We can then iterate on it in that pull request. I'll follow-up by sending the code changes necessary to hook this to the asciidoctor --help syntax command. WDYT?

[mojavelinux]

I'll also implement something like asciidoctor --help syntax urls to grab a single section by its ID (in this case, urls).

[mojavelinux]

When we revise this document, we should switch to using examples that we have in the Asciidoctor User Manual, where it would add clarity. For the basic stuff, it's probably fine how it is.

[mojavelinux]

This work by @anthonny could also be good raw material for this:

https://github.com/anthonny/hubot-asciidoc/blob/master/src/asciidoc.coffee