Jeff King <p...@peff.net> writes: > 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.
I agree on both counts. I just like to read these in plain text while I am coding for Git (or reviewing patches coded for Git). The reason why I have mild preference to D/technical/ over in-header doc is only because I find even these asterisks at the left-side-end distracting; it is not that materials in D/technical could be passed through AsciiDoc.
