Re: [ANNOUNCE] GIT 1.5.3-rc4

Steven Grimm [off-list ref] writes:

David Kastrup wrote:

quoted

A system such as info, in contrast, is hierarchical, and organized
with indexes and cross references making it much easier to find
things.

Really? I find info a huge pain in the butt most of the time.
I can't just do a simple text search for the information I want in
the relevant manpage; I have to go navigating around to the
appropriate subsection (and that's assuming I know where it is)

You are presumably talking about the standalone reader.  I never use
it, so can't really say much about it.  With Emacs, you just do C-s
and search.  Hitting C-s again will extend the search to the section,
and then to the whole file.

and am forced to use the emacs-style pager whether I like it or not
(not a big emacs fan here). It always ticks me off when I go to read
the manpage for some command and it tells me to go read the info
page if I want complete documentation.

I would definitely not want to move to a documentation system that
prevented me from typing "man git-commit" to get a list of all the
command line options for that command.

Nobody said that we would want to get rid of man pages.

Anyway, with the info reader, you should at worst use something like
info git
i git-commit RET
to get to the git-commit man page equivalent.

However, that said, I have no objection to an alternate view of the
same information that's organized differently.

Am I alone in my dislike of info, I wonder?

I don't use the standalone info reader.  It is likely quite less
sophisticated and convenient than what Emacs does with info files.
The few times I have used it, I felt inconvenienced IIRC, though it
has supposedly been improved some time ago after being left in the
lurch for quite long.  But actually you can also use yelp to browse
info pages (point it at, say, info:coreutils).

So I would definitely agree with your assessment that _replacing_ the
man pages by info would not be the right way to go.  However, nobody
asked for that.  The idea was to use _Texinfo_, and this produces
plain text, HTML, info files, quite nice PDF and some other formats.
Of _course_, we want to have man pages as well.  I pointed out a
reference to the GCC project where they explain how they generate man
pages from Texinfo.  One would have to check whether this can be
applied to the git pages, of course.

There was also the question how to integrate documentation into
something like gitk, and there is a Tkinfo widget that could
conceivably be used.  Texinfo files can also be converted into flat
text files with basic markup (and man pages don't give you more than
that, anyway).

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum