Em Mon, 31 Oct 2016 10:24:36 +0200 Jani Nikula <jani.nikula@xxxxxxxxxxxxxxx> escreveu: > On Fri, 28 Oct 2016, Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx> wrote: > > This patch series fix a few issues on some ABI files that violate what's > > written at Documentation/ABI/README, and add a parser, using > > kernel-cmd, to produce an ABI book. A parsed version of it can be found at: > > > > https://mchehab.fedorapeople.org/kernel_docs/admin-guide/abi.html > > So here's a constructive counter proposal: > > How about using the perl script you wrote to convert the ABI > documentation into reStructuredText format, committing the changes, and > maintaining ABI documentation in reStructuredText going forward? > This would keep the Sphinx build simple and allow richer ABI > documentation than the preformatted text blocks in above URL. I think > this would be a worthy improvement in the documentation. The format of > the ABI documentation is not ABI... we have no obligation to keep it in > some old ad hoc text format. > > Perhaps there's value in having a "database" format. But using rst does > not preclude us from formatting the documentation in a way that's also > parseable using a script. For example, use uniform header styles, use > definition lists with fixed terms, etc. Greg is the ABI maintainer, so he has the final word. IMHO, keeping ABI as a database is better, as we can display only the stuff we want. Right now, we're omitting several things, like the ABI maintainer, the Kernel where it entering, etc, as such kind of info is only relevant for someone touching the ABI, and not for a system admin. By having it as a database, it is easy to filter out undesired stuff and sort the ABI whatever we like. Also, by having it defined as lots of small per-subsystem files, it is easy to maintain, as the risk of conflicts on merges is small. That not talking about the practical aspects of such huge change. It will be as hard as changing from kernel-doc markup to something else: it will be really hard to merge such huge patchset, touching on all subsystems. Cheers, 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
