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

Hi,

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.

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