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/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@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/ ___ ghc-devs mailing list ghc-devs@haskell.org http://www.haskell.org/mailman/listinfo/ghc-devs
Re: RFC: Source-markup language for GHC User's Guide
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/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@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
Re: RFC: Source-markup language for GHC User's Guide
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@haskell.org http://www.haskell.org/mailman/listinfo/ghc-devs
Re: RFC: Source-markup language for GHC User's Guide
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 > ___ ghc-devs mailing list ghc-devs@haskell.org http://www.haskell.org/mailman/listinfo/ghc-devs
Re: RFC: Source-markup language for GHC User's Guide
> 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
Re: RFC: Source-markup language for GHC User's Guide
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. ___ ghc-devs mailing list ghc-devs@haskell.org http://www.haskell.org/mailman/listinfo/ghc-devs
Re: RFC: Source-markup language for GHC User's Guide
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 > allber...@gmail.com ballb...@sinenomine.net > unix, openafs, kerberos, infrastructure, xmonadhttp://sinenomine.net -- Regards, Austin Seipp, Haskell Consultant Well-Typed LLP, http://www.well-typed.com/ ___ ghc-devs mailing list ghc-devs@haskell.org http://www.haskell.org/mailman/listinfo/ghc-devs
Re: RFC: Source-markup language for GHC User's Guide
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 allber...@gmail.com ballb...@sinenomine.net unix, openafs, kerberos, infrastructure, xmonadhttp://sinenomine.net ___ ghc-devs mailing list ghc-devs@haskell.org http://www.haskell.org/mailman/listinfo/ghc-devs
Re: RFC: Source-markup language for GHC User's Guide
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 > ___ ghc-devs mailing list ghc-devs@haskell.org http://www.haskell.org/mailman/listinfo/ghc-devs
Re: RFC: Source-markup language for GHC User's Guide
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 ___ ghc-devs mailing list ghc-devs@haskell.org http://www.haskell.org/mailman/listinfo/ghc-devs
Re: RFC: Source-markup language for GHC User's Guide
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 ___ ghc-devs mailing list ghc-devs@haskell.org http://www.haskell.org/mailman/listinfo/ghc-devs
Re: RFC: Source-markup language for GHC User's Guide
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/ ___ ghc-devs mailing list ghc-devs@haskell.org http://www.haskell.org/mailman/listinfo/ghc-devs
RFC: Source-markup language for GHC User's Guide
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
