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

Herbert Valerio Riedel

7 Oct 2014 7 Oct '14

11:20 a.m.

Hello GHC Developers & GHC User's Guide writers, I assume it is common knowledge to everyone here, that the GHC User's Guide is written in Docbook XML markup. However, it's a bit tedious to write Docbook-XML by hand, and the XML markup is not as lightweight as modern state-of-the-art markup languages designed for being edited in a simple text-editor are. 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]. There's obviously some cost involved upfront for a (semi-automatic) conversion[3]. So one important question is obviously whether the long-term benefits outweight the cost/investment that we'd incur for the initial conversion. All suggestions/comments/worries welcome; please commence brainstorming :) [1]: http://www.methods.co.nz/asciidoc/ [2]: http://sphinx-doc.org/ [3]: There's automatic conversion tools to aid (though manual cleanup is still needed) the initial conversion, such as https://github.com/oreillymedia/docbook2asciidoc As an example, here's the conversion of http://git.haskell.org/ghc.git/blob/HEAD:/docs/users_guide/extending_ghc.xml to Asciidoc: https://phabricator.haskell.org/P24 to give an idea how XML compares to Asciidoc

Show replies by date

Michael Snoyman

7 Oct 7 Oct

11:24 a.m.

On Tue, Oct 7, 2014 at 6:20 PM, Herbert Valerio Riedel wrote:

...

Hello GHC Developers & GHC User's Guide writers,

I assume it is common knowledge to everyone here, that the GHC User's Guide is written in Docbook XML markup.

However, it's a bit tedious to write Docbook-XML by hand, and the XML markup is not as lightweight as modern state-of-the-art markup languages designed for being edited in a simple text-editor are.

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].

There's obviously some cost involved upfront for a (semi-automatic) conversion[3]. So one important question is obviously whether the long-term benefits outweight the cost/investment that we'd incur for the initial conversion.

All suggestions/comments/worries welcome; please commence brainstorming :)

[1]: http://www.methods.co.nz/asciidoc/

[2]: http://sphinx-doc.org/

[3]: There's automatic conversion tools to aid (though manual cleanup is still needed) the initial conversion, such as

https://github.com/oreillymedia/docbook2asciidoc

As an example, here's the conversion of

http://git.haskell.org/ghc.git/blob/HEAD:/docs/users_guide/extending_ghc.xml

to Asciidoc:

https://phabricator.haskell.org/P24

to give an idea how XML compares to Asciidoc _______________________________________________ ghc-devs mailing list ghc-devs@haskell.org http://www.haskell.org/mailman/listinfo/ghc-devs

My $0.02: I originally wrote the Yesod book in XML[1], and through automated tools converted it to asciidoc. The conversion was mostly painless, and it's a *huge* improvement to be able to edit in asciidoc instead. One of the nice things is you should be able to do the transition incrementally, since you can generally mix asciidoc and DocBook. Michael [1] DITA which I converted into DocBook

Austin Seipp

11:24 a.m.

Just for the record - I'm very much in favor of this. +1 from me. I think the one-time cost is very low for the most part, if the end result is a significantly more readable users guide to hack on. IMO, I don't particularly care whether we use Sphinx or AsciiDoc. The nice thing about AsciiDoc is it has a DocBook backend, so in theory we could make the end results seem pretty similar. Sphinx on the other hand generates its own documentation directly, I believe. The more annoying bit is it will incur an extra dependency for GHC documentation - which, remember, is part of ./validate - but that's life, perhaps. On Tue, Oct 7, 2014 at 10:20 AM, Herbert Valerio Riedel wrote:

...

Hello GHC Developers & GHC User's Guide writers,

I assume it is common knowledge to everyone here, that the GHC User's Guide is written in Docbook XML markup.

However, it's a bit tedious to write Docbook-XML by hand, and the XML markup is not as lightweight as modern state-of-the-art markup languages designed for being edited in a simple text-editor are.

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].

There's obviously some cost involved upfront for a (semi-automatic) conversion[3]. So one important question is obviously whether the long-term benefits outweight the cost/investment that we'd incur for the initial conversion.

All suggestions/comments/worries welcome; please commence brainstorming :)

[1]: http://www.methods.co.nz/asciidoc/

[2]: http://sphinx-doc.org/

[3]: There's automatic conversion tools to aid (though manual cleanup is still needed) the initial conversion, such as

https://github.com/oreillymedia/docbook2asciidoc

As an example, here's the conversion of

http://git.haskell.org/ghc.git/blob/HEAD:/docs/users_guide/extending_ghc.xml

to Asciidoc:

https://phabricator.haskell.org/P24

to give an idea how XML compares to Asciidoc _______________________________________________ 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/

Brandon Allbery

11:38 a.m.

On Tue, Oct 7, 2014 at 11:24 AM, Austin Seipp wrote:

...

The more annoying bit is it will incur an extra dependency for GHC documentation - which, remember, is part of ./validate - but that's life, perhaps.

Docbook is a fairly large dependency in my experience? -- brandon s allbery kf8nh sine nomine associates allbery.b@gmail.com ballbery@sinenomine.net unix, openafs, kerberos, infrastructure, xmonad http://sinenomine.net

Austin Seipp

11:57 a.m.

I don't really care too much about the size of the dependency (since 99.9% of time it's automated anyway via some package manager). My remark was more referring to the number of dependencies increases by 1 no matter what. :) But like I said, that's just life, and I frankly don't see this part as a big deal in either case. On Tue, Oct 7, 2014 at 10:38 AM, Brandon Allbery wrote:

...

On Tue, Oct 7, 2014 at 11:24 AM, Austin Seipp wrote:

...
The more annoying bit is it will incur an extra dependency for GHC documentation - which, remember, is part of ./validate - but that's life, perhaps.

Docbook is a fairly large dependency in my experience?

-- brandon s allbery kf8nh sine nomine associates allbery.b@gmail.com ballbery@sinenomine.net unix, openafs, kerberos, infrastructure, xmonad http://sinenomine.net

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

Edward Z. Yang

11:25 a.m.

I personally don't have a problem writing Docbook, and one problem with moving to lightweight markup is it becomes a bit harder to keep your markup semantic. Edward Excerpts from Herbert Valerio Riedel's message of 2014-10-07 09:20:43 -0600:

...

Hello GHC Developers & GHC User's Guide writers,

I assume it is common knowledge to everyone here, that the GHC User's Guide is written in Docbook XML markup.

However, it's a bit tedious to write Docbook-XML by hand, and the XML markup is not as lightweight as modern state-of-the-art markup languages designed for being edited in a simple text-editor are.

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].

There's obviously some cost involved upfront for a (semi-automatic) conversion[3]. So one important question is obviously whether the long-term benefits outweight the cost/investment that we'd incur for the initial conversion.

All suggestions/comments/worries welcome; please commence brainstorming :)

[1]: http://www.methods.co.nz/asciidoc/

[2]: http://sphinx-doc.org/

[3]: There's automatic conversion tools to aid (though manual cleanup is still needed) the initial conversion, such as

https://github.com/oreillymedia/docbook2asciidoc

As an example, here's the conversion of

http://git.haskell.org/ghc.git/blob/HEAD:/docs/users_guide/extending_ghc.xml

to Asciidoc:

https://phabricator.haskell.org/P24

to give an idea how XML compares to Asciidoc

Michael Snoyman

11:36 a.m.

On Tue, Oct 7, 2014 at 6:25 PM, Edward Z. Yang wrote:

...

I personally don't have a problem writing Docbook, and one problem with moving to lightweight markup is it becomes a bit harder to keep your markup semantic.

Edward

Why would this be a problem with asciidoc? All asciidoc maps directly into DocBook markup, and for cases that the simple asciidoc markup is insufficient, you can always embed full-blown DocBook (though I've ever done that in practice). Michael

...

Excerpts from Herbert Valerio Riedel's message of 2014-10-07 09:20:43 -0600:

...
Hello GHC Developers & GHC User's Guide writers,

I assume it is common knowledge to everyone here, that the GHC User's Guide is written in Docbook XML markup.

However, it's a bit tedious to write Docbook-XML by hand, and the XML markup is not as lightweight as modern state-of-the-art markup languages designed for being edited in a simple text-editor are.

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].

There's obviously some cost involved upfront for a (semi-automatic) conversion[3]. So one important question is obviously whether the long-term benefits outweight the cost/investment that we'd incur for the initial conversion.

All suggestions/comments/worries welcome; please commence brainstorming :)

[1]: http://www.methods.co.nz/asciidoc/

[2]: http://sphinx-doc.org/

[3]: There's automatic conversion tools to aid (though manual cleanup is still needed) the initial conversion, such as

https://github.com/oreillymedia/docbook2asciidoc

As an example, here's the conversion of

http://git.haskell.org/ghc.git/blob/HEAD:/docs/users_guide/extending_ghc.xml

...
to Asciidoc:

https://phabricator.haskell.org/P24

to give an idea how XML compares to Asciidoc

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

Tuncer Ayaz

8 Oct 8 Oct

4:21 a.m.

On Tue, Oct 7, 2014 at 5:20 PM, Herbert Valerio Riedel wrote:

...

Hello GHC Developers & GHC User's Guide writers,

I assume it is common knowledge to everyone here, that the GHC User's Guide is written in Docbook XML markup.

However, it's a bit tedious to write Docbook-XML by hand, and the XML markup is not as lightweight as modern state-of-the-art markup languages designed for being edited in a simple text-editor are.

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].

There's obviously some cost involved upfront for a (semi-automatic) conversion[3]. So one important question is obviously whether the long-term benefits outweight the cost/investment that we'd incur for the initial conversion.

All suggestions/comments/worries welcome; please commence brainstorming :)

Given the choices (and existing Docbook files), I would select AsciiDoc.

Jan Stolarek

4:49 a.m.

...

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.

Janek

Johan Tibell

5 a.m.

Same here. My interaction with the user guide is infrequent enough that it doesn't matter much to me. On Wed, Oct 8, 2014 at 10:49 AM, 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.

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

Herbert Valerio Riedel

7:14 a.m.

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

Carter Schonwald

5:40 p.m.

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

Austin Seipp

15 Oct 15 Oct

7:27 p.m.

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/

3870

Age (days ago)

3878

Last active (days ago)

List overview

Download

12 comments

9 participants

participants (9)

Austin Seipp
Brandon Allbery
Carter Schonwald
Edward Z. Yang
Herbert Valerio Riedel
Jan Stolarek
Johan Tibell
Michael Snoyman
Tuncer Ayaz