Re: markdown 2 man, was Re: Git Community Book

[Junio C Hamano <gitster@pobox.com>]

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

> Note also that Markdown cannot create TOCs automatically, AFAICT.  So 
> probably it would be not all that easy to convert the User Manual to that 
> format.

The use of markdown may mean updates to the User Manual won't be merged
back to his book without effort and manual porting on his side, and the
side porting in the other direction has the same issue as well, but the
contents and the way materials are presented will be vastly different in
future versions anyway; not being able to side-port new material verbatim
may not be an issue.  Discussion with Scott seems to suggest that the
overall philosophy of his book is "this is a different book targetted for
different audiences; its initial text happens to heavily borrow from the
existing documents but expected to become vastly improved", in other
words, fork-and-never-return.

That's one valid approach.  I or you might have taken a different avenue,
but after all, it's his book, not mine, not yours, nor git list's book.

As I am not in "graphics and screencast" camp, I may probably not be able
to offer much help improving his book, and I suspect some people on this
list might feel the same way.  But that's is Ok --- we are not dumping the
User Manual.

We originally hoped (well, at least I did) that Scott's effort on his book
might help us in improving the User Manual as well, but the approach seems
to make it unlikely.  But that is nothing to hold against him --- he is
doing his own thing in a way he feels is the best, and that's perfectly
fine.  We lost nothing, perhaps except for a chance to cooperate a bit
better and to widen the community.

> If at all, I would have preferred a format switch to Wiki syntax so that 
> we can use the same source on the Git wiki as in our Documentation/ 
> directory.

Yeah, that's also true.  I seem to recall markdown was used in ikiwiki?