On Wed, Sep 26, 2018 at 08:43:14PM +0200, Ævar Arnfjörð Bjarmason wrote: > While we're on that subject, I'd much prefer if these technical docs and > other asciidoc-ish stuff we would be manpages build as part of our > normal "make doc" target. So e.g. this one would be readable via > something like "man 3 gitapi-oid-array". I'm mildly negative on this, just because it introduces extra work on people writing the documentation. Now it has to follow special formatting rules, and sometimes the source is uglier (e.g., the horrible +-continuation in lists). Are authors now responsible for formatting any changes they make to make sure they look good in asciidoc? Or are people who care about the formatted output going to come along afterwards and submit fixup patches? Either way it seems like make-work. Now I'll admit it seems like make-work to me because I would not plan to ever look at the formatted output myself. But I guess I don't understand the audience for this formatted output. These are APIs internal to Git itself. We would not generally want to install gitapi-oid-array into /usr/share/man, because only people actually working on Git would be able to use it. So it sounds like a convenience for a handful of developers (who like to look at this manpage versus the source). It doesn't seem like the cost/benefit is there. And if we were going to generate something external, would it make more sense to write in a structured format like doxygen? I am not a big fan of it myself, but at least from there you can generate a more richly interconnected set of documentation. -Peff
