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

Tue Jun 27 11:50:09 UTC 2017

[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