R-alpha: help files of base package

[Friedrich Leisch]

>>>>> On Tue, 11 Nov 1997 18:01:11 +0100,
>>>>> Martin Maechler (MM) wrote:

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

MM> One thing which could and should be changed immediately, is to
MM> 1)  have a new chapter or section for each package in  Man.tex,
MM> 2)  Use a tableofcontents at the beginning

Ok, that Man.tex needs re-organization is obvious now that we have tex
files for all installed pkg's. But that doesn't help with the html
pages. 



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

Second thing is that a couple of students complained about the R-notes
... they simply don't think it's a good intro to R because it's rather
longish, but has bo index etc. ... I can't complain about it, but I
had this feedback from several R novices independently. Has anybody
had similar experiences?



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 ...

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

Oh, sorry, I just reread my email fromn yesterday ... when I started
to write it I wanted to put something in like ``this has to be done in
connection with the current keyword concept'' but then forgot to
actually write the line ... SORRY!

Making html index pages for all keywords would be a possibility, but
But as you said: I'm not sure how this would affect printed
documentation ... I still think that the latex part of base should
have subsections ...

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

Please see this as STRONG encouragement!



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

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

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

MM> We could resolve the problem by defining the convention
MM> 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.

MM> Index, YES(!)   ((I've always wanted to do this for quite a while...)
MM> 		The index should have an entry 'foobar' for each \alias foobar.
MM> This could be started immediately, as of now.
MM> It is very useful anyway (i.e. even with alphabetically sorted man pages), and
MM> 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)?

MM> It's a good idea (not new however)

I'm aware of that ... most good ideas aere not new ... just wanted to
restart discussion ...

MM> which needs quite a bit of work to be properly implemented
MM> (editing hundreds of .Rd files  AFTER thinking which keywords to use...).

exactly!

that's why I thought about introducing \category{} ... but simly using
the first keyword would be fine with me ...

We could start (and that shouldn't be too much work) with a rather
small set of obvious hyper-keywords/categories to group things a
little bit ... of course with goal of a larger set of keywords
providing finer clusters in the long run.

MM> Once you have these categories, you'll want to rely on them.
MM> Therefore, wrong, misspelled or missing keywords WILL be a more severe
MM> problem than other typos / inaccuracies in *.Rd files.

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

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

Yes!



Best,
Fritz
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
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
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=