Em Mon, 21 Nov 2016 10:48:30 -0700 Jonathan Corbet <corbet@xxxxxxx> escreveu: > On Sat, 19 Nov 2016 16:22:28 -0200 > Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx> wrote: > > > Nothing really prevents us to maintain the contents in separate, but > > that would make it harder to maintain, as, if we change something, > > we'll have two files to touch. Yet, I suspect that we won't be doing > > too much changes there. So, updating any changes on two places won't be > > hard. > > > > We could also add pad2rst to convert it in runtime, but that would > > require one extra package to be installed for documentation. Assuming > > that we won't do many changes at the POD content, this sounds > > overkill to me. > > > > Another alternative would be to make the rst content different, > > for example, running away from the man-pages style and adding more > > information at the .rst file. > > > > What do you prefer? > > My preference, honestly, would be to put the documentation in RST and > maintain that as the definitive documentation for the tool. It's not as > if there's going to be a lot of interactive users of parse-headers.pl... > I really don't like having two separate documents that will invariably > drift. Well, I still think that having a command line help is a good thing, at least while it can be run via command line. Of course, it woudn't make sense to have any help inside it, if this were a Sphinx extension. > This is also something I'm not going to get too up-in-arms about > regardless, though. It's a fairly obscure corner of the toolchain that > isn't going to concern a lot of people. > > Now...if we could get parse-headers built into sphinx as a proper > extension, that I would like :) Well, Markus could help with that. He sent a patch with an extension to call it already in the past. One possibility would be to rebase his extension. Yet, IMHO, this kind of feature should be part of Sphinx, as others could benefit of it, and would make Sphinx more like Doxygen. So, I don't object if he wants to rewrite it completely in Python. > > jon 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
