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

[Aaron Wolf]

On 08/15/2016 09:27 AM, Bradley M. Kuhn wrote:
> 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.
> 

I'd have voted for CommonMark but I can't see any reference to
footnotes, and I would favor a system that supports footnotes. Pandoc's
Markdown has that. I was expecting and hoping to see footnote support in
CommonMark.

I don't agree about the GitHub-flavored Markdown that was suggested as I
think basically everyone who is used to that would be perfectly happy
with CommonMark, and I see no advantage (and some disadvantages) to
accepting the GitHub-flavored variety.