On Mon, 28 Nov 2016, Peter Zijlstra <peterz@xxxxxxxxxxxxx> wrote: > On Mon, Nov 28, 2016 at 09:44:42AM +0100, Daniel Vetter wrote: > >> > >> > Why change them? What was wrong with txt to begin with? >> >> In my opinion good docs matter, and one of the key things is to be able to >> cross reference stuff. > > Well, good docs begin with useful content; and many docs lack that. > Fixing that would be a much more useful thing to do. > > In any case, I've never had any problems with typing things like: "go > read: Documentation/file.txt for more information.". Using rst we can produce decent HTML pages, and make them available at [1], in context. You don't have to read that, but it will be a lot more discoverable for other people, another important quality of good documentation. And perhaps you don't have to tell people to go read it so much. [1] https://www.kernel.org/doc/html/latest/ > Very much agreed, once a file is no longer readable with less or the > text editor of your choice, it as good doesn't exist at all. So I very > much worry about RST even supporting such heavy markup that the end > result is unreadable. The goal is to have the best of both worlds, keeping it pretty much plain text, but adding just enough consistency in formatting that you can generate other formats out of it. We don't have to and we shouldn't go overboard with the markup. Arguably you could call rst a "coding style" for plain text. We have pretty uniform C code, I don't think it's unreasonable to have a little bit of consistency in the plain text. And really, it's not much we're asking. BR, Jani. -- Jani Nikula, Intel Open Source Technology Center -- 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
