Philip Hazel wrote:
>
> Meanwhile, I would like as many people as possible to take a look at the
> results, and tell me whether they think they are good enough to use. My own
> view is that the presentation is not good in a number of ways, but despite
> this, I think we probably have to make this change and hope that XML processors
> get better.
>
> http://www.cus.cam.ac.uk/~ph10/eximdoc/filter.html
- The filter doc is being generated as a single file. In the currently
published version, each section is a seperate file. Was that an
intentional change? It's small enough that I don't have a strong
feeling about it one way or the other.
- General question: why is the filter doc seperate from the main spec?
I frequently find myself bouncing back and forth between them,
particularly between the filter doc and chapter 11 of the spec
(expansion). If they were a single doc, the examples in chapter F.3.4
could be cross referenced with chapter S.11, making that stuff easier to
find.
- Main and Sub-headings are being rendered the same. Should main be
<h1> and sub be <h2>?
- There's no main document heading giving the title of the doc (ie:
above the TOC)
- I like the beige boxes highlighting code examples. I think that's a
genuine improvement over the current docs.
- The doc doesn't have any changebars showing -- were you not able to
get that working, or does this version of the doc just not have any new
content tagged? If the latter, could you fake some just so we can see
how it renders?
- Would it be possible to add a clickable anchor link to the section
headings? For example, where you currently generate:
<a id="id2451006"></a>
instead, generate something like:
<a id="id2451006" href="#id2451006">X.Y Section Title</a>
That would give something to right-click on to use Firefox's Copy Link
Location feature, for easily finding appropriate links to paste into
RTFM messages to exim-users.
In the currently published version of the filter.html, you have the
section headings link back to the TOC. IMO, a self link is a bit more
useful here, but if you want to keep the link back to the TOC, at least
I can do what I want with that, though it does require an extra click
(click the link to get back to the TOC, then right-click on the TOC
entry to copy the link back to the section I was interested in).
- The doc has a lot of references to RFCs. Would it be possible to make
them links to the RFC online, perhaps at faqs.org?
- In the Sieve section, there are a number of references to subsections
of the Seive RFC. For example, in section 2.10, you reference sections
2.7.1 and 2.7.3. It wasn't immediately clear to me that those were refs
to the seive doc, rather than refs to other sections of this doc. I
spent a while trying to find sections 2.7.1 and 2.7.3 before I realized
what was going on. Of course, this comment holds true for the current
docs, it's not related to the new XML docs, this is just the first time
I've ever read the Sieve section so I never noticed it before.
- Another non-XML-specific editing comment: at the end of the doc, a
colon is missing from "Handle multiple personal mailboxes".
Hope this was helpful,
- Marc
