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