[Not snipping intentionally] On Tue, Jun 27, 2017 at 12:26:54PM +0100, Daniel P. Berrange wrote: > On Tue, Jun 27, 2017 at 01:07:32PM +0200, Andrea Bolognani wrote: > > On Mon, 2017-06-26 at 16:51 +0200, Kashyap Chamarthy wrote: > > > Can anyone provide a good counter-argument as to why *not* to use a > > > format like reStructuredText (rST)? It is supremely readable in plain > > > text (and even better with a Real Editor), and renders quite nice with > > > plain HTMP or with Sphinx Documentation Generator et al. Satisfies > > > needs of those who want to not use a browser, and those who prefer > > > clean online rendering. > > > > Nothing wrong with rST specifically or similar lightweight > > markup languages in general, quite the opposite: if you want > > to have both HTML and plain text versions of a document, > > it's IMHO way more sensible to go from text to HTML rather > > than the other way around. > > > > A few things to keep in mind, though: > > > > * HTML documentation is not only distributed in release > > archives, but also published on the website, which means > > it needs to integrate properly by including headers and > > footers and so on; > > > > * depending on the format, the tool used to generate HTML > > might be difficult to set up or not work at all on some > > older operating system that libvirt still targets; > > > > * introducing a new build requirement might simply not be > > worth it unless we have at least a few documents using > > it; > > > > * someone would have to find the time and dedication to > > just sit down and convert a 52 KiB file from HTML :) Okay, all sound reasonable. Thanks. > One of the reasons QEMU chose RST is because they are targetting > multiple output formats - man pages, web pages & potentially PDF too. > For libvirt, our (in-tree) docs/ dir content is exclusively aimed at > creating web pages, so the level of indirection attained from RST is > not a mandatory feature in the sense it was for QEMU. > > I can see benefits in being able to write content in a markup language > that has less "syntax" compared to HTML. For such usage, I would have > a preference for markdown over RST. Markdown more closely aligns with > what libvirt does - it is a syntax which only cares about targetting > HTML. As such, if there is something complex you can't express in > Markdown, you don't need to create a extension to the markup engine to > enable it. Instead you just directly embed a chunk of HTML in the > markdown file. Ah, this is a useful explanation as to what libvirt is aiming at (in comparision with QEMU). And given that, Markdown indeed sounds more compelling. (I should also admit -- I didn't know of this convenient ability to embed HTML into Markdown.) > This HTML embedding would make it pretty easy for us to adopt. We > could more or less just rename all our .html.in files to .md, and > strip off the top level <html><body> tags and with a little cleanup > get valid markdown files. They'd just be using the HTML embed feature > of markdown exclusively. New content could use more of the markdown > syntax. Where appropriate we could choose to convert existing content, > but I'd suggest not doing it unless some new contributor to the > project is really interested in doing so. > > To make this possible, we would need to decide which markdown engine > we would use, and make sure it is installable on CentOS-6 (which runs > libvirt.org) without pulling in a huge number of deps. If the markdown > engine can't generate TOCs, we would still need to go from .md to > .html.in, and then run our XSL to insert the table of contents as we > have now. Yes, all very good points. Thanks, both, Andrea and Dan, for taking time to respond. My questions are answered thoroughly. -- /kashyap -- libvir-list mailing list libvir-list@xxxxxxxxxx https://www.redhat.com/mailman/listinfo/libvir-list
