[libvirt] [PATCH 1/4] HACKING: Drop from the git repository

[Andrea Bolognani]

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