format will change from LaTeX -> (CommonMark|AsciiDoc): which should we chose?

[Bradley M. Kuhn]

I'm working to clear some of my schedule later this year to resume work
on the Copyleft Guide, including merging the pending patches.  Once
those patches are merged, my top priority is the issue of formatting.
While CONTRIBUTING.md clearly says:

    However, lack of Git and/or LaTeX knowledge is *not a barrier* for
    contribution to this project.  Useful contributions will be accepted by the
    following means  as well: ... [list]

    Please, do not worry if your patches or new sections of text are not
    properly formatted as patches and/or are not formatted in LaTeX
    properly.  Indeed, feel free to offer patches that break LaTeX
    formatting, or to just write up your suggestion in an email.

... I nevertheless believe that LaTeX formatting still creates a barrier
to entry.  I'm very comfortable in LaTeX myself, and the earliest source
materials that make up the bulk of the Copyleft Guide were all in LaTeX.

Yet, you'll see that the web formatting scripts in the repository are
insane (e.g., webhacks.cfg is a total mess.)  Furthermore, the text was
originally written to be handed out as a printed book.  While we need
that use-case to still work (as discussed publicly on the IRC channel
recently, the FSF does want to use this material for CLE classes), the
"book" format is not ideal for web publication for various reasons.

I'm thus convinced that it is worth even my time (although help would be
wonderful, of course) to convert the LaTeX -- by hand -- into an easier
format for future maintainence.

The two formats I'm considering are Markdown (specifically, CommonMark)
and AsciiDoc.  Rather than start listing my reasons, nor the outcome of
discussions I've had recently with Free Software documentation project
experts lately, I welcome everyone to begin a conversation about which
we should choose.  Here are a few links to specs and software systems to
look at while you consider this:

   http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/
   https://github.com/asciidoctor
   http://commonmark.org/
   http://pandoc.org/
   http://hyperpolyglot.org/lightweight-markup   

The last one is a nice quick reference on the two formats (and a few
others).  (I was posing this as a two-valued choice, but if you want to
argue for one of those others, please feel free. ;)

I think this is actually an important decision for a very simple reason:
we need a format that is highly likely to inspire people to contribute.
The type of person we want may be new to editing something in anything
but LibreOffice or Microsoft Word, but is probably willing to learn and
maybe even wants to learn, but also doesn't want the task to be daunting
(like editing LaTeX is).  They probably want transferrable editing
skills too as a bonus to contributing here.

The specific format we pick doesn't actually matter all that much to
regular contributors, so really the decision of which one to choose is
about comfort level of those who *want* to become regular contributors
but aren't yet, which are likely this list's subscribers.

Discuss away; I'll add my own opinions on which one I prefer later in
the thread.
-- 
   -- bkuhn
========================================================================
Become a Conservancy Supporter today: https://sfconservancy.org/supporter