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-o... And source (despite .txt extension, the formatting is in rST): https://kashyapc.fedorapeople.org/v3-QEMU-Docs/_build/html/_sources/docs/liv... [...] -- /kashyap