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

Góra strony
Delete this message
Reply to this message
Autor: Andreas Metzler
Data:  
Dla: exim-dev
Temat: Re: [exim-dev] Exim documentation: new format: readers wanted
On 2005-05-25 Philip Hazel <ph10@???> wrote:
[...]
> http://www.cus.cam.ac.uk/~ph10/eximdoc/spec.info.tar.bz2

[...]

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

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


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

+ I think the new-info documentation is useable.

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

Example:
html and new-info
option foo1
[Description of option foo1]
option foo2
[Description of option foo2]
3
[Description of option foo3]
etc.

old-info
<foo1>
<foo2>
<foo3>

with <fooX> being links to tiny nodes _just_ contsiaing the
description of fooX.

What I'd like is this:
<a href="#foo1">foo1</a>
<a href="#foo2">foo2</a>
<a href="#foo3">foo3</a>
...
<a id="#foo1">foo1</a>
[Description of option foo1]
<a id="#foo2">foo2</a>
[Description of option foo2]
<a id="#foo2">foo2</a>
[Description of option foo2]

This'd spare me both manual searching instead of following hyperlinks
(html) without losing the big picture (info-old)

+ Differentiating between expanded and unexpanded options. This
applies both to html and info-version. Previously we had this:

perl_startup
Use: main
Type: string
...
pid_file_path
Use: main
Type: string, expanded

and now we have
`perl_startup'            Use: _main_     Type: _string_  Default: _unset_
...
`pid_file_path'           Use: _main_     Type:          Default: _set at
                                         _string_*       compile time_


and
perl_startup     Use: main       Type: string   Default: unset
...
pid_file_path    Use: main       Type: string†  Default: set at compile time


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

+ 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]. This makes the documentation
quite unreadable on latin1 terminals:

______________________________
+-----------------------------------------------------------------------------+
|acl_not_smtp      |  Use: main   |   Type: string?    |        Default: unset|
+-----------------------------------------------------------------------------+


This option de?nes the ACL that is run when a non-SMTP message is on the point
of being accepted. See chapter 39 for further details.
______________________________

Nigel already has remarked that the ligatures make searching
difficult (they also break cut and paste from documentation to
configuration.)

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?
            thanks, cu andreas


[1]:
9 File and database lookups
***************************

Exim can be configured to look up data in files or databases as it
processes messages. Two different kinds of syntax are used:
[...]
-- 
"See, I told you they'd listen to Reason," [SPOILER] Svfurlr fnlf,
fuhggvat qbja gur juveyvat tha.
Neal Stephenson in "Snow Crash"
                                           http://downhill.aus.cc/