Config file parser for lists

[Jeffrey M. Vinocur]

On Tue, 7 Apr 2009, [iso-8859-1] Julien ÉLIE wrote:

> I suggest the following documentation for inn.conf.  

Reviewing.


> It might also be a bit confusing as for the difference between the To: header,
> the C<To> value and the C<To:full> overview field.

Indeed, I don't know what you're talking about here.


> Overview data for these additional headers will be generated
> for every incoming article.
      ^^^^^^^^^^^^^^^^^^^^^^

Consider: "each new article at the time of arrival"



> If an unknown header name is listed, B<innd> will log an error

Probably you should clarify here.  A user without knowledge of INN's 
internals may not understand how a header name can be "unknown".


> You should advertise only fields for which the overview database
> is consistent, that is to say it records the content or absence
> of these fields for I<all> articles from the beginning.  
                                      ^^^^^^^^^^^^^^^^^^

Consider:  ", including those already existing in the news spool."


> if you decide to add or remove a field from your overview database,
> you should either modify I<extraoverviewadvertised> and rebuild
> your overview database with makehistory(8) after removing all
> existing overview files, or use I<extraoverviewhidden>.
                              ^^^^^^^^^^^^^^^^^^^^^^^^^^^

Consider:  "implement a transition period by first using
I<extraoverviewhidden> as described below."

And maybe add something like, "Use of a transition period can accommodate 
most overview reconfigurations, but certain drastic changes may still 
require a complete overview rebuild."


> all articles in your overview database record the content or absence
> of that new field (if all your articles expire within S<30 days>,
> you can assume the database is in such a state after S<30 days>),

Consider adding a cross-reference to expire.ctl here, as well as 
mentioning that time to expiration can be unpredictable with CNFS (and 
perhaps a mention of `cnfsstat -a` for checking on when buffers have 
rolled over).


> This parameter should be used in conjunction with
> I<extraoverviewadvertised> (see it for more details).  
                                  ^^
                                  "above"


> them in response to the LIST OVERVIEW.FMT command.

That reminds me, at one or more points in this documentation, there 
should probably be something about how nnrpd handles HDR/XHDR for 
fields that are not in overview (and how that interacts with 
extraoverviewhidden).




-- 
Jeffrey M. Vinocur
jeff at litech.org