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

[Kashyap Chamarthy]

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

    https://lists.nongnu.org/archive/html/qemu-devel/2017-06/msg04679.html

Its rendering:

    https://kashyapc.fedorapeople.org/v3-QEMU-Docs/_build/html/docs/live-block-operations.html

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

    https://kashyapc.fedorapeople.org/v3-QEMU-Docs/_build/html/_sources/docs/live-block-operations.txt


[...]

-- 
/kashyap