Re: [ANNOUNCE] GIT 1.5.3-rc4

!MAILaRCHIVE_VOTE_RePLACE
Previous message: [thread] [date] [author]
Next message: [thread] [date] [author]
To: Steven Grimm <koreth@...>
Cc: Sam Ravnborg <sam@...>, Junio C Hamano <gitster@...>, Ismail <ismail@...>, <git@...>
Date: Saturday, August 4, 2007 - 8:19 am

Steven Grimm <koreth@midwinter.com> writes:


Personally, I think it would make sense to move to a different
documentation system, or at least a different organization.  The
problem with the current layout is that it is basically flat.

A system such as info, in contrast, is hierarchical, and organized
with indexes and cross references making it much easier to find
things.  More importantly, it makes it possible to put things into
perspective: which commands are porcelain, which are plumbing?  What
do you do in a typical workflow?  What are the related internal data
structures?  Where are they documented?  Can I print or navigate a
complete PDF document explaining the whole system?

The manual pages of git have a high quality, but they remain manual
pages: they are all standalone, not putting the tool into a context or
hierarchy.  While the user manual is a place to start, it is more or
less added as an afterthought: it does not structure the available
documentation.

For Texinfo there is a large number of backends, and there are also
usable reader plugins (Tkinfo, and the presumably embeddable GNOME
"yelp" also displays info files and the embedded links, and of course
the wonderful Emacs info browser) for things like git-gui.

It may be that the asciidoc/Docbook workflow also contains ways to get
similarly useful stuff out: comments welcome.  I am just more
acquainted with Texinfo myself.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum
-
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Previous message: [thread] [date] [author]
Next message: [thread] [date] [author]

Messages in current thread:
[ANNOUNCE] GIT 1.5.3-rc4, Junio C Hamano, (Fri Aug 3, 8:28 pm)
Re: [ANNOUNCE] GIT 1.5.3-rc4, Robin Rosenberg, (Sat Aug 4, 9:11 am)
Re: [ANNOUNCE] GIT 1.5.3-rc4, Julian Phillips, (Sat Aug 4, 9:42 am)
Re: [ANNOUNCE] GIT 1.5.3-rc4, Ismail , (Fri Aug 3, 8:41 pm)
Re: [ANNOUNCE] GIT 1.5.3-rc4, Junio C Hamano, (Fri Aug 3, 9:30 pm)
Re: [ANNOUNCE] GIT 1.5.3-rc4, Steven Grimm, (Fri Aug 3, 11:49 pm)
Re: [ANNOUNCE] GIT 1.5.3-rc4, Junio C Hamano, (Sat Aug 4, 12:38 am)
Re: [ANNOUNCE] GIT 1.5.3-rc4, Michael, (Sat Aug 4, 11:19 am)
Re: [ANNOUNCE] GIT 1.5.3-rc4, Timo Hirvonen, (Sat Aug 4, 6:39 am)
Re: [ANNOUNCE] GIT 1.5.3-rc4, Johannes Schindelin, (Sat Aug 4, 7:46 am)
Re: [ANNOUNCE] GIT 1.5.3-rc4, Timo Hirvonen, (Sat Aug 4, 8:51 am)
Re: [ANNOUNCE] GIT 1.5.3-rc4, David Kastrup, (Sat Aug 4, 3:30 am)
Re: [ANNOUNCE] GIT 1.5.3-rc4, Steven Grimm, (Sat Aug 4, 2:11 am)
Re: [ANNOUNCE] GIT 1.5.3-rc4, Johannes Schindelin, (Sat Aug 4, 7:38 am)
Re: [ANNOUNCE] GIT 1.5.3-rc4, J. Bruce Fields, (Sat Aug 4, 10:29 am)
Re: [ANNOUNCE] GIT 1.5.3-rc4, Sam Ravnborg, (Sat Aug 4, 5:12 am)
Re: [ANNOUNCE] GIT 1.5.3-rc4, Steven Grimm, (Sat Aug 4, 6:55 am)
Re: [ANNOUNCE] GIT 1.5.3-rc4, David Kastrup, (Sat Aug 4, 8:19 am)
Re: [ANNOUNCE] GIT 1.5.3-rc4, Linus Torvalds, (Sat Aug 4, 12:59 pm)
Re: [ANNOUNCE] GIT 1.5.3-rc4, David Kastrup, (Sat Aug 4, 1:49 pm)
Re: [ANNOUNCE] GIT 1.5.3-rc4, Jeff King, (Sun Aug 5, 5:42 am)
Re: [ANNOUNCE] GIT 1.5.3-rc4, David Kastrup, (Sun Aug 5, 5:54 am)
Re: [ANNOUNCE] GIT 1.5.3-rc4, Jeff King, (Sun Aug 5, 5:59 am)
Re: [ANNOUNCE] GIT 1.5.3-rc4, David Kastrup, (Sun Aug 5, 6:20 am)
Re: [ANNOUNCE] GIT 1.5.3-rc4, Jeff King, (Sun Aug 5, 6:22 am)
Re: [ANNOUNCE] GIT 1.5.3-rc4, David Kastrup, (Sun Aug 5, 6:40 am)
Re: [ANNOUNCE] GIT 1.5.3-rc4, David Kastrup, (Sun Aug 5, 7:23 am)
Re: [ANNOUNCE] GIT 1.5.3-rc4, Linus Torvalds, (Sat Aug 4, 3:03 pm)
Re: [ANNOUNCE] GIT 1.5.3-rc4, David Kastrup, (Sat Aug 4, 3:55 pm)
Re: [ANNOUNCE] GIT 1.5.3-rc4, Linus Torvalds, (Sun Aug 5, 12:29 am)
Re: [ANNOUNCE] GIT 1.5.3-rc4, David Kastrup, (Sun Aug 5, 3:51 am)
Re: [ANNOUNCE] GIT 1.5.3-rc4, Linus Torvalds, (Sun Aug 5, 1:08 pm)
Re: [ANNOUNCE] GIT 1.5.3-rc4, David Kastrup, (Sun Aug 5, 2:08 pm)
Re: [ANNOUNCE] GIT 1.5.3-rc4, Junio C Hamano, (Sun Aug 5, 7:38 pm)
Re: [ANNOUNCE] GIT 1.5.3-rc4, David Kastrup, (Mon Aug 6, 1:44 am)
Re: [ANNOUNCE] GIT 1.5.3-rc4, Miles Bader, (Sun Aug 5, 8:13 pm)
Re: [ANNOUNCE] GIT 1.5.3-rc4, Linus Torvalds, (Sun Aug 5, 3:29 pm)
Re: [ANNOUNCE] GIT 1.5.3-rc4, Bruce Korb, (Sun Aug 5, 5:43 pm)
Re: [ANNOUNCE] GIT 1.5.3-rc4, David Kastrup, (Sun Aug 5, 6:15 pm)
Re: [ANNOUNCE] GIT 1.5.3-rc4, J. Bruce Fields, (Sun Aug 5, 6:31 pm)
Re: [ANNOUNCE] GIT 1.5.3-rc4, Linus Torvalds, (Sun Aug 5, 2:23 pm)
Re: [ANNOUNCE] GIT 1.5.3-rc4, David Kastrup, (Sun Aug 5, 3:06 pm)
Re: [ANNOUNCE] GIT 1.5.3-rc4, David Kastrup, (Sun Aug 5, 4:32 pm)
Re: [ANNOUNCE] GIT 1.5.3-rc4, Johannes Schindelin, (Sun Aug 5, 2:35 pm)
Re: [ANNOUNCE] GIT 1.5.3-rc4, David Kastrup, (Sun Aug 5, 3:11 pm)
Re: [ANNOUNCE] GIT 1.5.3-rc4, J. Bruce Fields, (Sat Aug 4, 5:27 pm)
Re: [ANNOUNCE] GIT 1.5.3-rc4, Steven Grimm, (Sat Aug 4, 12:03 pm)
Re: [ANNOUNCE] GIT 1.5.3-rc4, Jeff King, (Sun Aug 5, 5:50 am)
Re: [ANNOUNCE] GIT 1.5.3-rc4, David Kastrup, (Sat Aug 4, 12:27 pm)
Re: [ANNOUNCE] GIT 1.5.3-rc4, Johannes Schindelin, (Sat Aug 4, 12:08 pm)
Re: [ANNOUNCE] GIT 1.5.3-rc4 , Doug Maxey, (Sat Aug 4, 2:17 am)
Re: [ANNOUNCE] GIT 1.5.3-rc4, Daniel Barkalow, (Sat Aug 4, 12:57 am)
Re: [ANNOUNCE] GIT 1.5.3-rc4, Junio C Hamano, (Sat Aug 4, 1:23 am)
Re: [ANNOUNCE] GIT 1.5.3-rc4, Daniel Barkalow, (Sat Aug 4, 1:52 am)
Re: [ANNOUNCE] GIT 1.5.3-rc4, Ismail , (Fri Aug 3, 9:48 pm)
Re: [ANNOUNCE] GIT 1.5.3-rc4, Junio C Hamano, (Fri Aug 3, 11:13 pm)
Re: [ANNOUNCE] GIT 1.5.3-rc4, Ismail , (Sat Aug 4, 9:26 am)