Re: Git in a Nutshell guide

From: jhud7196@artax.karlin.mff.cuni.cz <jhud7196@artax.karlin.mff.cuni.cz>
Date: Nov 22, 2007, 16:37 UTC
Message-ID: <60224.194.138.12.144.1195749434.squirrel@artax.karlin.mff.cuni.cz>
In-Reply-To: <200711212232.33791.jnareb@gmail.com>

Show 11 quoted lines

> 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.

Yes, that's true. And does indeed make /writing/ the book harder, because the information is harder to compile. Fortunately it should not make it so much harder to read.

Show 17 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").

Ad 1), I don't think we have to generate the images. For most images it is easier to just draw them in a vector image editor.

As you say, 2) does not matter for "Git Guide"/"The Git Book". The man pages will have to do without graphics or with Ascii-art replacements.

> 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.

I'd use DOT for things that can be done with it (ie. visualizing histories) and just hand-draw the rest in SVG (prefered) or PNG (for illustrations).

--
                                               Jan Hudec <bulb@ucw.cz>