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/
