Re: RFC: Source-markup language for GHC User's Guide

OK, to kick this thread around: It seems like several people who touch the users guide are in favor of this due to: - Simpler markup - DocBook compatibility - Hopefully attracting more users if it's easier to manage. Cons: - +1 Dependency (minor) - No formal grammar (I don't think it has one either, re: Carter), but in ambiguous cases we can embed DocBook. And most other people seem completely neutral. Therefore: I'd say it's probably worth doing, since most people doing the editing are in favor, while most other people seem neutral. Does anyone else have strong opposition or other views? If not, I'd say we could get this over with before I create the STABLE branch. On Wed, Oct 8, 2014 at 4:40 PM, Carter Schonwald wrote:

does asciidoc have a formal grammar/syntax or whatever? i'm trying to look up one, but can't seem to find it.

On Wed, Oct 8, 2014 at 7:14 AM, Herbert Valerio Riedel wrote:

...

On 2014-10-08 at 10:49:33 +0200, Jan Stolarek wrote:

...

...

Therefore I'd like to hear your opinion on migrating away from the current Docbook XML markup to some other similarly expressive but yet more lightweight markup documentation system such as Asciidoc[1] or ReST/Sphinx[2].

...

My opinion is that I don't really care. I only edit the User Guide once every couple of months or so. I don't have problems with Docbook but if others want something else I can adjust.

I'd argue, that casual contributions may benefit significantly from switching to a more human-friendly markup, as my theory is that it's much easier to pick-up a syntax that's much closer to plain-text rather than a fully-fledged Docbook XML. With a closer-to-plain-text syntax you can more easily focus on the content you want to write rather than being distracted by the incidental complexity of writing low-level XML markup.

Or put differently, I believe or rather hope this may lower the barrier-to-entry for casual User's Guide contributions.

Fwiw, I stumbled over the slide-deck (obviously dogfooded in Asciidoc)

http://mojavelinux.github.io/decks/discover-zen-writing-asciidoc/cojugs20130...

which tries to make the point that Asciidoc helps you focus more on writing content rather than fighting with the markup, including a comparision of the conciseness of a chosen example of Asciidoc vs. the resulting Docbook XML it is converted into.

Cheers, hvr _______________________________________________ ghc-devs mailing list ghc-devs@haskell.org http://www.haskell.org/mailman/listinfo/ghc-devs

_______________________________________________ ghc-devs mailing list ghc-devs@haskell.org http://www.haskell.org/mailman/listinfo/ghc-devs

-- Regards, Austin Seipp, Haskell Consultant Well-Typed LLP, http://www.well-typed.com/