Re: [ANNOUNCE] GIT 1.5.3-rc4

Junio C Hamano <gitster@pobox.com> writes:

If you are able to figure out what to write. Can you tell me how to include one of the man pages in an appendix, with appropriate substructure? I can't. It might be easy, but I find it impossible to guess from the information just how.

    File: texinfo,  Node: makeinfo Pointer Creation,  Next: anchor,  Prev: node,  Up: Nodes

    6.4 Creating Pointers with `makeinfo'
    =====================================

    The `makeinfo' program has a feature for automatically determining node
    pointers for a hierarchically organized document.

      When you take advantage of this feature, you do not need to write the
    `Next', `Previous', and `Up' pointers after the name of a node.
    However, you must write a sectioning command, such as `@chapter' or
    `@section', on the line immediately following each truncated `@node'
    line (except that comment lines may intervene).

      In addition, you must follow the `Top' `@node' line with a line
    beginning with `@top' to mark the `Top' node in the file.  *Note
    `@top': makeinfo top.

      Finally, you must write the name of each node (except for the `Top'
    node) in a menu that is one or more hierarchical levels above the
    node's hierarchical level.

      This implicit node pointer insertion feature in `makeinfo' relieves
    you from the need to update menus and pointers manually or with Texinfo
    mode commands.  (*Note Updating Nodes and Menus::.)

Then don't maintain them.  It is not necessary.

Anyway, I suggest that people wanting to continue to berave me for
taking the word Texinfo into my mouth do this off-list.  It is very
much clear that Texinfo is no-go as a source documentation format for
Git: it makes a considerable ratio of developers foam at the mouth.
And that simply rules it out.

It also turns out that makeinfo2x-texi is able to produce rather good Texinfo from stuff written for book output with Asciidoc. Yes, there are details missing, but it is nothing one could not slide in with sed into the Texinfo file. And adding the absent indexing information can be done in Asciidoc: that is documented.

In contrast, I have just tried using makeinfo --docbook on AUCTeX Texinfo documentation, and the docbook XML it produces is not always properly nested, and when one corrects that, the problems with processing that just start: that seems not really tested, at least with makeinfo 4.8.

So there is a good Docbook->info path, but not the other way round. Anyway, you wrote:

At least for the user manual, I can support this (without index) in a dozen lines of makefile code and another dozen lines of sed (for adding the top/dir entry information). Yes, this caught me quite by surprise. For the indexing, of course one will have to insert the appropriate Asciidoc markup into the source files. I can also work on that, but it should likely be a colloborative effort: it leads to a working Index also in the PDF output without the need to involve Texinfo.

As for making the man pages part of the main manual: I don't know my way around Asciidoc enough to be able to do this. It might be possible to fudge around this issue with sed again, converting the manual page sources to book section sources. I am sure there is a more elegant way to do this sort of transformation/conversion either on the Asciidoc or XML level, but it's beyond me.