Am 22.11.2016 um 09:44 schrieb Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx>: > Em Mon, 21 Nov 2016 08:48:00 +0100 > Markus Heiser <markus.heiser@xxxxxxxxxxx> escreveu: > >> Am 19.11.2016 um 19:22 schrieb Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx>: >>> >>> And, a more detailed description using --man. Right now --man >>> displays an identical content of the part below that comment >>> in the rst file, because I used pad2rst for the conversion. >> >> Sorry, IMO this is conceptual wrong. >> >> reST is the base format from which we create other output formats. >> Even if we have no man page generation from reST yet, we should not >> promote toolchains using language specific markups (POD) as base >> format. > > Sorry but I don't agree with you here ;) I'am very happy with your last commit: "to be in the mid term " ;-) > IMHO, *all* Executable files should have an usage and a help argument > that would at least explain the arguments to such script. Even sphinx-build > script has it, despite the fact that the more detailed documentation > for it is in ReST format. > > In the case of Perl, the simplest way to do it is to use POD. > > POD supports two levels of help: a quick summary and a > comprehensive one. Both are created from the POD markups inside > it, by calling pod2usage($verbose). if $verbose is 1, it > provides a quick summary; if $verbose is 2, it provides the > complete help, on a format similar to a man page. > > Making perl read the documentation from a RST file will be > an ugly hack, IMHO. I was unclear in my last mail (sorry), making a --help option on the command line is IMO a must-have and when POD is the way perl goes, it is right to use it. >> So it might be time to investigate some efforts in a 'man'-page >> target. Ask me if I can help. > > Generating man pages is something that we need to do anyway. > It would be great if you could restart such work. Its on the way, but before I need to clarify conceptual how to merge the builder into the kernel sources. A preview of the work is available at: https://h2626237.stratoserver.net/kernel/docs.html follow the 'man' links in the parenthesis. The man page builder source is available here: https://github.com/return42/linuxdoc/blob/master/linuxdoc/manKernelDoc.py -- Markus -- -- 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
