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

[Austin Seipp]

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
<carter.schonwald at gmail.com> 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 <hvriedel at gmail.com>
> 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/cojugs201305/index.html
>>
>> 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 at haskell.org
>> http://www.haskell.org/mailman/listinfo/ghc-devs
>
>
>
> _______________________________________________
> ghc-devs mailing list
> ghc-devs at haskell.org
> http://www.haskell.org/mailman/listinfo/ghc-devs
>



-- 
Regards,

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