> 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.
>>> 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@xxxxxx>
-
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
