Junio C Hamano <gitster@xxxxxxxxx> writes:
> David Kastrup <dak@xxxxxxx> writes:
>
>>> So stop this *insane* insistence of emacs. You should learn to just
>>> assume that people don't even have it installed!
>>
>> We were discussing Texinfo, not Emacs. Please focus.
>
> I would welcome if the set of our documentation output formats
> included *.info pages.
>
> However, as the input format, texinfo _is_ painful. AsciiDoc is
> 100x easier.
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.
> I've written documentaiton in texinfo format in the past, and one
> thing I found quite painful was maintaining the node header with
> prev/next links --- tedious, error prone and boring.
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::.)
> There is no good editor to help you maintain them other than Emacs
> texinfo mode as far as I know.
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:
> I would welcome if the set of our documentation output formats
> included *.info pages.
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.
--
David Kastrup, Kriemhildstr. 15, 44793 Bochum
-
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
