R-alpha: help files of base package

[Martin Maechler]

>>>>> "FrL" == Friedrich Leisch <Friedrich.Leisch@ci.tuwien.ac.at> writes:

    FrL> I'm not happy at all with the html and latex version of the base
    FrL> help files, because presenting (currently) 320 files in alphabetic
    FrL> order is not a good way for unexperienced users.

One thing which could and should be changed immediately, is to
1)  have a new chapter or section for each package in  Man.tex,
2)  Use a tableofcontents at the beginning
Currently (with 'base' 'eda' and 'mva') We just have 'xy.coords' (last of
base) followed by 'line' (first of 'eda').

ok.
For the inexperienced one, I think we need the "Rnotes chapters" part of
the manual, anyway...

    FrL> I'm thinking about introducing a new command like \category or
    FrL> whatever to split the help files up into parts like
    FrL> graphics commands random numbers linear models input/output ...

Fritz, you must know that I had emphasized the introduction of \keyword{.}
a few months ago.

If you read current appendix A  ``Writing R Documentation'', you find (p.2)
that I say how (one or more) "\keyword{.}" should be used.
I've put several dozens of these \keyword{.} in several of the  *.Rd
files, also, but then I lacked time (and motivation because nobody
encouraged me .. ;-} ).

I also made a point to write  RHOME/doc/KEYWORDS
(was RHOME/mansrc/KEYWORDS in version 0.50) and mentioned it in
the output of  prompt(foo) and the above appendix A.

My goal has always been to have categories
 (these, as you see in KEYWORDS, are further grouped into "Hyper-Categories"). 
for online help  AND  printed documentation.

The point is:  Many functions (& and help files) should have more than one
keyword, since they belong into more than one category.
This is quite fine for   topics() and help.start() [HTML help],
but it is not so easy for printed documentation.

We could resolve the problem by defining the convention
that for printed docu, only the FIRST keyword will be used.

    FrL> such that we can organize things a little bit. this way we could
    FrL> also have a concise index of ALL functions available that is still
    FrL> helpfull.

Index, YES(!)   ((I've always wanted to do this for quite a while...)
		The index should have an entry 'foobar' for each \alias foobar.
This could be started immediately, as of now.
It is very useful anyway (i.e. even with alphabetically sorted man pages), and
has no real connection to the \keyword / category  side.


    FrL> what do you think?

    FrL> how to organize such a thing (besides providing the technical
    FrL> means)?

It's a good idea (not new however)
which needs quite a bit of work to be properly implemented
(editing hundreds of .Rd files  AFTER thinking which keywords to use...).
	
Once you have these categories, you'll want to rely on them.
Therefore, wrong, misspelled or missing keywords WILL be a more severe
problem than other typos / inaccuracies in *.Rd files.

Still, I am deeply convinced that its worth the work.
If several people divided it up, it would be even more fun
(and probably lead to a better  result).

If you start doing the ``technical means''
[[ Enhancing  Rdconv (and  Rd.sty, functions.html) for  latex and html ]],
I'd be very much motivated to restart on the big job of putting in more
\keywords. 
As said, maybe it'll be better to divide this up among several people.

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