Re: [Exim] Exim 4 ideas.

On Sun, Jan 07, 2001 at 12:37:27PM +0000, Philip Hazel wrote:

> I certainly would not like to maintain a document in raw SGML, because
> of its verbosity, though of course one can trivially generate it from
> some simpler markup (which is what I've done for the Exim book).
>
> > Whatever, I would personally vote for 3 formats:
>
> I suspect the info-lovers wouldn't like me if I abolished the Texinfo
> version, though maybe I'm wrong. Maybe HTML is taking over. Would
> anybody out there who uses the Texinfo documentation like to comment?

I use it, because it's easily searchable. As soon as an HTML document is
split into multiple pages, it's a lot harder to search. Personally I like
single page HTML documents, but a lot of people don't, particularly for
something as long as the exim manual.

Speaking as the maintainer of the debian package, I'd like to be able to
download the manual in one format and build other formats from it. That's
sort of possible from the TeXinfo, but the HTML you get that way isn't as
good as the HTML that's provided for exim (particularly not now there's
pictures in the latter!).

>[man page]
> This has been suggested before, but I do not want to have to maintain
> two different versions of the same information.

Couldn't you write a script of some kind to do it for you?

> This is an ongoing complaint. I hope that the forthcoming book may
> be the answer to some of this, but unfortunately, Exim is so flexible it
> is difficult to cover all possibilities. I intend to keep the reference
> manual very much as a reference manual. Once the book has been
> published, there may even be an excuse to put *fewer* examples in the
> ref manual.

Some of the examples in the manual aren't strictly necessary, but many of
them are: where there a number of commands that interact, an example of how
they are used together is often the only way to clearly show how they work,
and therefore has a place in a manual however strictly the manual is kept as
a reference.