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

Kashyap Chamarthy kchamart at redhat.com
Mon Jun 26 14:51:19 UTC 2017

On Mon, Jun 26, 2017 at 01:43:33PM +0200, Andrea Bolognani wrote:
> On Mon, 2017-06-26 at 13:19 +0200, Peter Krempa wrote:


> > > The rationale for tracking the generated file is to help out
> > > people who just cloned the git repository looking to contribue;
> > > however, README-hacking already contains enough information to
> > > get perspective contributors to a place where they can simply
> > > look at docs/hacking.html instead.
>> > NACK, there wouldn't be no sane way to look at the file without using a
> > browser.
> What's wrong with using a Web browser?

FWIW, I actually can see Peter's rationale.

> If you don't want to leave the terminal emulator, something like lynx
> will display the HTML version very reasonably.

I know I'm bringing Yet-Another Format into picture.  But this is
definitely worth considering.

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.

FWIW, to give a sense of it, I just wrote a 1000-line QEMU API doc patch
in rST


Its rendering:


And source (despite .txt extension, the formatting is in rST):




More information about the libvir-list mailing list