Author: Philip Hazel Date: To: Zack Weinberg CC: pcre-dev Subject: Re: [pcre-dev] manual in Texinfo?
On Fri, 15 Feb 2008, Zack Weinberg wrote:
> Another thing that's come up in the context of Monotone is that we'd
> like to have the PCRE syntax documentation as part of our manual, but
> our manual is written in Texinfo. I did a hand conversion of the
> pcresyntax and pcrepattern manpages into that format, but obviously I
> would rather not do that every time there's a major update. Thus I'm
> wondering if you would consider taking onboard a complete conversion
> of your manual to Texinfo. (I would do the work.) It natively
> generates excellent PDF and HTML output, and I can provide you with a
> Perl script (which I originally wrote and is now maintained as part of
> GCC - it might need minor modifications, but I don't anticipate
> trouble) which converts to POD format, from which you could generate
> man-format and plain text documentation.
I tangled with Texinfo when I was working on the Exim documentation, and
I have to say that I wasn't particularly happy because it couldn't do
some of the things that I wanted. Can't remember details offhand, but it
was stuff like it didn't like certain characters (quotes?) in nodes
(chapter titles). Of course things might have changed, or it might have
been my misunderstanding. [The way that the Exim documentation is
maintained was later revised, and the current Exim documentation is
generated from a marked-up source into DocBook XML and the Texinfo
version is nowadays made from that by somebody else's code. I cannot
remember if the converter grumbles, and I can't check any more because
since I retired I'm no longer working on Exim.]
I have to say that I'm not really keen on working in yet another (to me
unfamiliar) documentation format. Old dogs and new tricks and all that.
The "man" format is easy for me to maintain, and I use only a very
stylized subset; would it not be easy to write a Perl script to convert
my "man" input to Texinfo?
Currently, the HTML is generated by a Perl script that I wrote - it
checks for certain constructs such as .br and .in that are not good
practice and grumbles. It also does several other magic things; it's
been a while, so I can't recall the details, but the script is
commented. The URL references are one, and handling cases where the
"man" format needs two lines but the HTML only one is another.
