Re: [libvirt] [PATCH 1/4] HACKING: Drop from the git repository
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-bloc...
And source (despite .txt extension, the formatting is in rST):
https://kashyapc.fedorapeople.org/v3-QEMU-Docs/_build/html/_sources/docs/...
[...]
--
/kashyap