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
--
libvir-list mailing list
libvir-list@xxxxxxxxxx
https://www.redhat.com/mailman/listinfo/libvir-list
