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

Tue Jun 27 11:26:54 UTC 2017

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 :|