[Rd] news file included in source but not binary package

[Prof Brian Ripley]

On Fri, 25 Jun 2004, Martin Maechler wrote:

> We emacs fans would definitely additionally want 'ChangeLog' (as
> per Fritz' proposal).
> This has been a standard name for decades with a very convenient
> emacs interface ['C-x 4 a'] to create and update the file.

Only if it is in a certain very rigid format.  Unfortunately Emacs 
interferes with attempts to edit a file called ChangeLog in other people's 
formats.

>     AndyL> and use NEWS.platform as Duncan suggested
>     AndyL> (in the top-level directory, rather than
>     AndyL> platform-specific directories)?
> 
> I agree.  
> 
> BTW, both NEWS and ChangeLog have specific (but different) syntax
> the main difference that NEWS entries are anonymous and not
> dated whereas ChangeLog is a "log", i.e. has dated entries.

To my mind the main difference is that NEWS is for interesting information 
for users, and ChangeLog for notes for developers.

> Kurt (or Fritz?) already mentioned in the earlier
> 'Greg-initiated' thread that it might be interesting to consider
> automatic conversion of these files to (e.g.) html.  
> But such possibilities should not hinder us from agreeing *now*
> that e.g. files with regexps
> ----------
> m{NEWS.*}
> m{Change(s|Log)}i
> ----------

And what software you propose to evaluate those regexps (which look like 
Perl commands to me)?

> should automatically be taken from the source toplevel directory
> and put into <installed>/doc/<filename>.txt
> 			       ^^^^
> (the '.txt' maybe a good idea idea because the ./doc/ directory
>  can be easily opened in the browser in some interfaces)

I disagree.  Lots of packages already install their documentation files
where they want them, and we should not retrospectively change what the
maintainers did.  (In at least one case I deliberately do not install a
ChangeLog file, which refers to source files which are also not
installed.)  Those people who have inst/doc and a nice index probably
don't want other files added there.

Let's start from the position that we already have a mechanism for 
installing files and encourage its use.  We may want to add some 
guidelines on the use of information files, but we cannot impose them 
retrospectively.

-- 
Brian D. Ripley,                  ripley at stats.ox.ac.uk
Professor of Applied Statistics,  http://www.stats.ox.ac.uk/~ripley/
University of Oxford,             Tel:  +44 1865 272861 (self)
1 South Parks Road,                     +44 1865 272866 (PA)
Oxford OX1 3TG, UK                Fax:  +44 1865 272595