Re: [exim-dev] Exim documentation: new format: readers wante…

Αρχική Σελίδα
Delete this message
Reply to this message
Συντάκτης: Philip Hazel
Ημερομηνία:  
Προς: Andreas Metzler
Υ/ο: exim-dev
Αντικείμενο: Re: [exim-dev] Exim documentation: new format: readers wanted
On Fri, 27 May 2005, Andreas Metzler wrote:

> I've taken a _short_ look at the info-stuff:


Thank you.

> + There seems to be a problem with the "Detailed Node Listing" in the main
> table of contents, the first section of a chapter is not referenced
> there.
>
> I've marked links with <> in this example:
> ------------
> --- The Detailed Node Listing ---
> File and database lookups
>
> * <Lookup types::>
> * <Single-key lookup types::>
> ------------
>
> The link to the initial part[1] is missing here, because
> "File and database lookups" is no link, sections consisting only of a
> single part (like "18 The ipliteral router") are therefore completely
> missing from the detailed node listing.


This is all done completely automatically by the "docbook2texi" program;
I have no idea what one might do to fix things.

> + Doublechecking against the "[add hyperlink]"-entries on
> http://bugs.debian.org/src=eximdoc4 showed that the new info contained
> all the missing links. (I guess these were your own testcases, too.)


Nope. I have done nothing, but I'm glad something has been fixed!

> + I think the new-info documentation is useable.


Phew!

> + The structure of the document is now similar to the html version,
> previously there were a couple of interim nodes. e.g. there was one
> node containg just a (linked) list of all main options, now it is like
> in the html version. - I'd actually like to have something in between,
> a liked list on top but no separate nodes for every single option.


I suppose that is not surprising, given that the new version is made
from the XML by a similar toolchain. I do not know how to do it any
differently.

> What I'd like is this:


If anybody can tell me how to drive db2x_xslt-proc and db2x_texixml how
to do this, I can consider it. They are the two tools that
"docbook2texi" uses, according to its man page.

> + Differentiating between expanded and unexpanded options. This
> applies both to html and info-version.


> I wonder whether the asterisk * or [arrow upwards] is prominent enough.


It shows as a dagger in my browser in the HTML version. Maybe inserting
a space before it would help?

> + Usage of non-latin1 characters.
>
> The new html documentation makes extensive use of characters which are
> not available in ISO-8859-1, mainly for ligatures and to designate
> expanded options with [arrow upwards].


Yes, well, we are supposed to be moving into a Unicode world, aren't we?
However, Nigel has also complained about the ligatures. I don't really
mind for the HTML version. I *do* strongly regret not being able to use
them for the PS/PDF versions.

> Personally I am using UTF-8-terminals, but I am still hit by the
> difficulties in searching. - How about using non-latin1 characters
> only in ps and pdf?


That is, of course, possible. Should it be an asterisk instead of the
dagger?

-- 
Philip Hazel            University of Cambridge Computing Service,
ph10@???      Cambridge, England. Phone: +44 1223 334714.
Get the Exim 4 book:    http://www.uit.co.uk/exim-book