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

Pàgina inicial
Delete this message
Reply to this message
Autor: Philip Hazel
Data:  
A: Marc Sherman
CC: exim-dev
Assumpte: Re: [exim-dev] Exim documentation: new format: readers wanted
On Thu, 26 May 2005, Marc Sherman wrote:

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


Accidental. But I'm not sure it's worth trying to change.

> - General question: why is the filter doc seperate from the main spec?


So that it can be published as a separate document for "ordinary" users
to read.

> - Main and Sub-headings are being rendered the same. Should main be <h1> and
> sub be <h2>?


Will check, but this is just what gets automatically generated from the
DocBook XML. Maybe there's something in the StyleSheets that can be
tweaked. (But it's hell trying to understand them.)

> - There's no main document heading giving the title of the doc (ie: above the
> TOC)


Same remark.

> - 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?


The only place anything should show is in the HTML version. (I couldn't
get any other rendering to pay attention to the markup.) There *is* one
paragraph, at the start of section 1.1 of the main spec, which is marked
as "changed". In my browser, it renders with a green background.

> - Would it be possible to add a clickable anchor link to the section headings?
> For example, where you currently generate:


NB: *I* don't generate anymore - xmlto does, and the controls are
therefore much more buried and harder to tweak.

> - 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?


I would have thought that the canonical place in ietf.org would be
better, wouldn't it?

> Hope this was helpful,


Yes, thanks.

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