Em Thu, 10 May 2018 18:52:20 +0200 Andrea Parri <andrea.parri@xxxxxxxxxxxxxxxxxxxx> escreveu: > On Thu, May 10, 2018 at 07:15:59AM -0600, Jonathan Corbet wrote: > > On Thu, 10 May 2018 14:23:35 +0200 > > Andrea Parri <andrea.parri@xxxxxxxxxxxxxxxxxxxx> wrote: > > > > > only > > > remember that other people (including some developers running into the > > > "disadventure" of opening an RST doc. from their preferred text editor > > > and being brought to conclude: "WTH! I need to open a web browser, I > > > guess...") _use_ such doc. and _do care_ about it, and that what might > > > be an improvement for some people might look as "vandalizing" to others. > > > > If you have an example of a place where use of a web browser has been > > made mandatory, please point it out. Avoiding that was at the top of the > > list of explicit requirements. > > That's all I need. > > > >Surely an extra colon is not going to > > force you to run screaming to the protective embrace of Firefox...? > > Let me put it in these terms: I believe that that extra colon (or the > "diagram" keywork) is not going to improve/help my use of the doc. ;D No, it won't improve, but, it won't make it harder for a human to understand if a "diagram" or "::" is added at the description. The thing is that we need something that works for the Kernel as a hole, and not just on a few places. On some subsystems, just a text is not good enough to describe things. See, for example: https://www.kernel.org/doc/html/latest/media/uapi/v4l/crop.html https://www.kernel.org/doc/html/latest/media/uapi/v4l/pixfmt-packed-rgb.html https://www.kernel.org/doc/html/latest/media/uapi/v4l/pixfmt-srggb10-ipu3.html https://www.kernel.org/doc/html/latest/gpu/drm-kms.html Images, complex tables, etc are sometimes required to show some things. Trying to explain just on text is harder to write, longer and worse for readers. In the past, DocBook was used. ReST made very simple to write documentation. From where I sit, I'm reviewing documentation patches from a lot more people than the usage of a markup language. As a bonus, we can now create cross-references for kernel-doc functions, with is really great when reading documentation for complex hardware. >From where I sit at media, the subsystem documentation, if generated in PDF, becomes a book with more than 1,100 pages, full of long tables, images and graphs[1], covering uAPI, kAPI and driver-specific documentation. [1] https://linuxtv.org/downloads/v4l-dvb-apis-new/media.pdf As on all subsystems, developers write documentation directly at .rst or as kernel-doc comments. But for reading it, even developers prefer to read the docs via the html (or pdf) output, as it better shows tables and images. It is also faster to follow the dozen thousands of links inside it. The point is: we shouldn't enforce everyone to use our own view about how to navigate through documentation. People are free to use whatever improves their workflow. Thanks, Mauro -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
