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

From: Stephan Beyer <s-beyer@gmx.net>
Date: Jul 31, 2008, 13:01 UTC
Message-ID: <20080731130101.GC18106@leksak.fem-net>
In-Reply-To: <4891A0D0.6060503@lyx.org>

Hi,

Abdelrazak Younes wrote:

> Please ignore if this is not appropriate.

Well, so I should've ignored, but I think this is worth some correction.

> Asciidoc or Markdown are tools that accommodate the _developer_, not the  
> user. I understand that these markup language are ideally suited for in  
> source documentation (thought I personally much prefer Doxygen).

http://www.methods.co.nz/asciidoc/ says
 ``AsciiDoc is a text document format for writing short documents,
   articles, books and UNIX man pages. AsciiDoc files can be translated to
   HTML and DocBook markups using the asciidoc(1) command.''

http://daringfireball.net/projects/markdown/ says
 ``Markdown is a text-to-HTML conversion tool for web writers. Markdown
   allows you to write using an easy-to-read, easy-to-write plain text
   format, then convert it to structurally valid XHTML (or HTML).''

So those are not suited for in-source documentation.

They're "lightweight" markup for documentation, very easy to read and somehow
easy to write for non-developers.
The user manual can give you an impression:
	http://repo.or.cz/w/git.git?a=blob;f=Documentation/user-manual.txt

I think, this is easier than LyX for users and developers..

Regards,
  Stephan

-- 
Stephan Beyer <s-beyer@gmx.net>, PGP 0x6EDDD207FCC5040F