Re: Git in a Nutshell guide

From: Jakub Narebski <jnareb@gmail.com>
Date: Nov 21, 2007, 21:32 UTC
Message-ID: <200711212232.33791.jnareb@gmail.com>
In-Reply-To: <20071121194507.GA3569@efreet.light.src>

Dnia środa 21. listopada 2007 20:45, Jan Hudec napisał:

> On Wed, Nov 21, 2007 at 00:57:28 +0100, Jakub Narebski wrote:

>>  2. Git has some historical cruft, including the fact that it began as
>>     series of low level tools (plumbing) and became proper SCM (acquired
>>     proper porcelain) later, what can be even now seen in documentation...

What I meant here that some of important documentation can be only found in plumbing commands man pages.

Show 8 quoted lines

>>  3. Explanation of some features (like object model) would be much easier
>>     with some graphics (diagrams etc.), but chosen documentation format,
>>     AsciiDoc, doesn't make it easy...
> 
> I dare to disagree here. Asciidoc supports generating image tags for
> respective output formats and it really does not look hard. We could have
> PNGs and if we wanted higher press quality even SVG or EPS and convert them
> to PNGs for the HTML version (and use EPS for latex output).

The problem is that 1) language used to generate images must be easy to understand and readable in text form (so sources are enough to understand); 2) one of the main formats is manpage (although that would not matter for "Git Guide" / "The Git Book").

Should we choose PIC? Or perhaps DOT? I can write little MetaPost, but I don't think that would be good format for git diagrams, even if it can be converted to PDF, SVG and PNG.

-- 
Jakub Narebski
Poland