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

[Abdelrazak Younes <younes@lyx.org>]

Hi Jan,

Jan Krüger wrote:
>> 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.

I had good success with htlatex (the default converter within LyX). I 
just modified the css and was done with it. All cross-references etc 
were correctly handled.

> Of course, hevea only translates to HTML, so, for example, generating
> manpages or plain text is an entirely different matter of considerable
> difficulty.

LyX has an excellent plain text export. You can use the export method of 
LyX at the command line without launching it graphically by the way. You 
don't even need an X server, just use 'lyx -e text mydocument.lyx'

For man page, LyX does not support it natively I'm afraid, but I guess 
there are LateX to man converter, aren't there?

> 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.

Not really. As I said to Junio, .lyx files are using a plain text utf8 
format. They are easily mergeable as LyX preserves the structure of the 
file: if the two collaborators modify two different parts of the 
document there is basically zero chance to have a conflict. On the rare 
occasion where I had  a conflict with svn, it was very easy to solve 
manually by removing the conflict tags inserted by svn. With git, I 
never had a single conflict ;-)

> 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.

That's a good argument. My personal opinion is that users prefer to use 
'-help' for short help and to read the tutorial or the user guide for 
more in-depth information. I never use man personally... OK, that's 
probably because I use Windows :-)

> And AsciiDoc is --
> by far! -- not the worst choice. I'm tempted to say it's the best that
> I know.

AsciiDoc is indeed excellent if you want to write in a plain text 
editor. But LyX is easier to use and more porwerful :-)

Thanks,
Abdel