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 :) 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. 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. I'm not volunteering todo any of this, but I'd support anyone interested in enabling markdown usage. Regards, Daniel -- |: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :| -- libvir-list mailing list libvir-list@xxxxxxxxxx https://www.redhat.com/mailman/listinfo/libvir-list
