Re: [libvirt] [PATCH 1/4] HACKING: Drop from the git repository
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 :)
--
Andrea Bolognani / Red Hat / Virtualization