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

["Jan Krüger" <jk@jk.gs>]

Hi,

> Disclaimer: I am involved in LyX development, so anything I said will
> be biased :-)

I think that's fine since I consider LaTeX (and therefore LyX as the
best graphical editor for it that I know) a choice always worth
considering when it comes to projects that have the size of a book.

> Now, about my shameless plug: LyX is ideally suited for structured 
> documentation writing :-)

That may well be, but it gets really complicated once you want to
get your document into other markup-based formats while preserving all
the important aspects of formatting. I know this because I started
using LaTeX for a project that was supposed to be available in HTML
form along with, say, PDF. I've found that the only converter that
comes close to being useful for somewhat more ambitious sources
(including, perhaps, custom environments and stuff like that) without
spending a ridiculous amount of time trying to understand it is hevea.
Of course, hevea only translates to HTML, so, for example, generating
manpages or plain text is an entirely different matter of considerable
difficulty.

In addition to that, I suspect that LyX files might be difficult to
deal with in forky Git situations. For example, what if two
separately contributed patches need merging into a LyX source file?
This will only work automatically if the LyX source, treated as plain
text, has a really low chance of randomly changing in other places than
what the patch is supposed to touch. Also, if a merge does cause a
conflict, I imagine it would be difficult to resolve that.

Finally, it's pretty much a given that Git's manpages continue to use
AsciiDoc because there are few other things that can generate actual
manpages. I'm not sure it would be a good idea to keep half of Git's
documentation in one format and the rest in another. And AsciiDoc is --
by far! -- not the worst choice. I'm tempted to say it's the best that
I know.

-Jan