Re: Git Community Book

["Scott Chacon" <schacon@gmail.com>]

On Tue, Jul 29, 2008 at 11:42 AM, Junio C Hamano <gitster@pobox.com> wrote:
> "Scott Chacon" <schacon@gmail.com> writes:
>
>>>
>>> There is no license in the source code - what are the copying terms?
>>>
>>
>> I copied in the COPYING file from Git - GPL2.
>>
>>> It is maybe somewhat unfortunate that this is in a different format that
>>> the standard git choice asciidoc, but the formats do look rather similar
>>> so I assume it should not be hard to even convert from one to another if
>>> needed.
>>
>> I simply didn't want to get asciidoc working locally - it's always
>> been a bit of a pain to compile (I've heard it referred to more than
>> once as the only 'nightmare dependancy' in git), and I don't need to
>> make man pages or anything, so it seemed Markdown would be a better
>> choice for my output targets.  There are a number of good Markdown
>> interpreters and they're easy to get running.
>
> I personally like markdown, but doesn't your refusal to work with existing
> practices pose a significant problem, unless:
>
>  (0) you do not consider it a goal to keep the documentation shipped with
>     git and your book in sync; or
>
>  (1) you have either markdown to asciidoc (or the other way around)
>     converter; the book is written in markdown, and its conversion back
>     to asciidoc is fed to Documentation as patches (or the other way
>     around); or
>
>  (2) somebody tries to find markdown to manpage, and we convert
>     Documentation/ to markdown.
>
> Or is this, "fork once and borrow reviewer's time, but never be able to
> contribute back to the original text because the result is so different"
> approach?
>

The book is basically a fork of all three of the guides I mentioned
(User Manual and both Tutorials), and with the scope and goals I
currently have in mind, will not be kept in sync - it's just not going
to be possible.  I think in the end, the goals of the texts are so
very different that sections it will simply not make sense to try to
keep them in sync in some sort of automated fashion.  That's one of
the reasons why I choose Markdown - I saw no need to use asciidoc, as
the book will not be shipped around with Git or built using the same
processes, and I had no need for the advantages of asciidoc in my
project.  I don't think it makes much sense to have the book be a man
page at all.

However, I will watch the manual and guides and try to incorporate
changes to them as appropriate, and I will likely have some updates to
them myself as I've been more closely scrutinizing them.

Scott