Re: [libvirt] [PATCH 1/4] HACKING: Drop from the git repository
[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