Re: [ANNOUNCE] GIT 1.5.3-rc4

From: David Kastrup <dak@gnu.org>
Date: Aug 4, 2007, 16:27 UTC
Message-ID: <857iobfenn.fsf@lola.goethe.zz>
In-Reply-To: <46B4A35E.5040601@midwinter.com>

Steven Grimm <koreth@midwinter.com> writes:

Show 9 quoted lines

> David Kastrup wrote:
>> 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.

Show 8 quoted lines

> 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