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

From: Junio C Hamano <gitster@pobox.com>
Date: Jul 30, 2008, 19:32 UTC
Message-ID: <7vy73j418t.fsf@gitster.siamese.dyndns.org>
In-Reply-To: <alpine.LSU.1.00.0807301514280.3486@wbgn129.biozentrum.uni-wuerzburg.de>

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?