"J. Bruce Fields" <bfields@xxxxxxxxxxxx> writes: > On Mon, Aug 06, 2007 at 12:15:24AM +0200, David Kastrup wrote: >> Or things like including the manual pages in an appendix or elsewhere. >> Any chance for that? Slim, at least for me. > > I'd like to do exactly that at some point. I was hoping it would be as > simple as just adding a bunch of include:: statements, but there's > probably some more obstacles. If someone had the time to look into what > would be required to get it working, I'd be grateful. Well, I posted already a patch set (or rather, several iterations) that built info documentation from the user manual. I only got a single comment from Jakub about notices in INSTALL, and about the awk dependency. The last iteration from yesterday addressed both AFAICT. Since it does not affect existing Makefile targets at all, I hope that it may end up in 1.5.3. However, independently from info, I think the git documentation should be structured into one or more standalone documents that make sense as a single DocBook document (and ultimately a printed PDF) each. Of course this will benefit generating info, but it will also give other people better documentation into their hands. I digress. Concerning your request > If someone had the time to look into what would be required to get > it working, I'd be grateful. I did some digging and some trying. The inclusion of the manual pages will not work out of the box: they have different markup and logical sectioning levels. However, AsciiDoc does provide mechanisms that could be used for including this sort of stuff, by just matching the markup used in the man page sources and replacing it with the appropriate headers or markup for the DocBook case. To figure this out, read up on the following parts: <URL:http://www.methods.co.nz/asciidoc/userguide.html#toc67> <URL:http://www.methods.co.nz/asciidoc/userguide.html#toc71> <URL:http://www.methods.co.nz/asciidoc/userguide.html#toc75> It turns out, however, that this may be doing it the hard way: There is a way to have sections/appendices consisting of just manual pages: <URL:http://www2.informatik.hu-berlin.de/~draheim/doc/docbook-manpages.html> So it may be easiest to just create a <reference> section in the XML, include the man pages in there, and see what the various DocBook converters make of that. Of course, in such a document one would want to change the gitlink macros to actually point to the included reference rather than an outside resource. That would have to be done in Documentation/asciidoc.conf as far as I can see. There are already autogenerated files cmds*.txt that contain lists of the various manpages. One could either use them directly (with a temporary gitlink definition that includes a manual page rather than referring to it), or generate similar files with a more straightforward relation of content and behavior. -- David Kastrup - To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
