David Kastrup <dak@xxxxxxx> posted to the git mailing list in 2007:
> awk is used for patching up sub-par file and directory information in
> the Texinfo file. It would be cleaner to place the respective info
> straight into user-manual.txt or the conversion configurations, but I
> find myself unable to find out how to do this with Asciidoc/Texinfo.
I found how to do this, but it's not worth the trouble.
Apparently, there are two ways to specify the description for the
Info directory entry generated by docbook2X 0.8.3:
(a) Set it in the docbook2x-texi command line, with the option:
-g description="A fast distributed revision control system"
This could easily be placed in the Makefile.
(b) Add a /book/bookinfo/abstract[@role="texinfo-node"] element:
<abstract role="texinfo-node"><simpara>A fast distributed
revision control system</simpara></abstract>
docbook2x-0.8.3/xslt/texi/menudescrip.xsl claims that the role
should be "make-texinfo-node", but the template in that file
actually looks for role="texinfo-node". docbook2X 0.8.8
documents the role correctly.
The /book/bookinfo element currently comes from the [header]
section in docbook.conf of AsciiDoc. That docbook.conf does
not currently provide a way to add an abstract like that.
So, Git would have to override the whole header, unless
such a feature were added to AsciiDoc.
Then, docbook2x-texi would take the title "Git User's Manual (for
version 1.5.3 or newer)" and convert it to "Git User_s Manual
[for version 1_5_3 or newer]", presumably to avoid some reserved
characters in Info. To get a prettier title like "Git" in the
Info directory entry:
(a) A Git-specific XSL template could read the entry title from
/book/bookinfo/titleabbrev, which would also have to be added
to the header in the AsciiDoc configuration.
(b) Alternatively, the template could use a command-line parameter.
Makefile would provide -g info-dir-title="Git", and the
template would then use $info-dir-title.
Finally, to make the Info directory entry link to the right file,
one would have to add -g output-file=git to the docbook2x-texi
invocation.
In summary, it is certainly possible to make AsciiDoc and
docbook2X together generate the right kind of directory entry,
but I suspect the current Perl hack is more likely to survive
toolchain upgrades than a more proper implementation would be.
If the necessary features were added to the upstream AsciiDoc
and docbook2X, then things would be different, but I guess Git
wouldn't dare require new versions until after a year or so.
--
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
