R-alpha: naming convention for index files

[Kurt Hornik]

>>>>> Martin Maechler writes:

KH> In the process of moving to the new directory structure, we might also
KH> reconsider the naming of the various index files.

KH> A simple idea would be to have an `INDEX' file in each directory where
KH> this is appropriate.  E.g., we could have

KH> pkg/funs/INDEX		(rather than help/pkg/INDEX)

> but  help/base/INDEX  is autogenerated
> where as everything in ./funs/  (or /R/  as you propose later)  is  SOURCE

KH> pkg/data/INDEX		(rather than index.doc)
> index.doc is source

KH> pkg/help/INDEX		(rather than AnIndex)
> this is auto-generated again...

> --
> in summary, we could well say   INDEX  instead of different names,
> but I don't think we should  autogenerate a file in a directory
> where there's only source  (other than the 'Makefile'; Lib... files that
> 			    configure generates, and which are not needed
> 			    anymore after installation)

> Remember: 

> 	The big idea is still that after

> 		make install + install-help + ..
> 			(just after all the installation)

> 	you should be able to
> 	REMOVE the full  ./src/  tree and still have a completely 
> 	working R (including online help, ...).


KH> or e.g.

KH> pkg/INDEX.funs
KH> pkg/INDEX.data

KH> etc.

KH> The package TITLE files would be used for building the package index of
KH> a library tree (LibIndex?)

> very good idea

KH> In any case, the `plain' indices to be displayed upon calling an
KH> appropriate form of help() could contain MORE than simply a list of
KH> things.  I.e., more like a README.

KH> My idea is (assuming only RHOME is in .lib.loc):

KH> library()

KH> `RHOME' is the location of the default R library tree.
KH> Blah blah blah ...

KH> Packages in `RHOME':

KH> base		The basic package.
KH> eda		...
KH> mva		...

KH> The last lines could be generated from the packages' TITLE files.  The
KH> other info from some stub, perhaps LibIndex.in?

> very good idea

KH> As usual, any feedback is appreciated.

> as usual, I give you some ... ;-)

Yes, Martin, what would I do without you?

You are right, of course, there should be some distinction between the
static and the dynamic (automatically generated) index files.

I think we need to distinguish two things.  On the one hand, we need
some short (a one-liner as in TITLE) and some long ``documentation'' on
a package.  The long one could be sort of like the README files which
come with certain S add-ons (and typically list the user-level objects
in the pkg).

If we ask for information about a package, the long one is what we
should get, I think.

On the other hand, it is clearly useful to have lists of R objects and
data sets a package provides.  These are the INDEX files.  But these
could also be auto-generated upon installation from the man sources.
In fact, as we also need them in HTML (and maybe in LaTeX), there is
not too much use for prebuilt ones ...

So, what shall we do about the indices?  As I already said, I think that
the documentation for data should be converted to the new Rd format and
merged with the R object documentation (same name space etc).  

Clearly, we should have a list of data somewhere, so that we can quickly
list all data sets.  Hmmm ... I guess I am not entirely sure what to do.

Library `info' should be o.k.:  we create the LibIndex from a README
like file and the TITLE files of all packages in the lib.

***

For the time being, I will not change anything.  (Unless we have a real
breakthough ...)

In the new dir structure, should the INDEX and TITLE files be installed
to $lib/$pkg or its help subdir?  They make sense outside of help ...

-k

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
r-devel mailing list -- Read http://www.ci.tuwien.ac.at/~hornik/R/R-FAQ.html
Send "info", "help", or "[un]subscribe"
(in the "body", not the subject !)  To: r-devel-request@stat.math.ethz.ch
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-