Skip to content

R-alpha: help files of base package

7 messages · Martin Maechler, Friedrich Leisch, Peter Dalgaard +1 more

Original
Martin Maechler
# 
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
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Friedrich Leisch
# 
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
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Peter Dalgaard
# 
Friedrich Leisch <Friedrich.Leisch@ci.tuwien.ac.at> writes:
Hmm, when students say that something is not good enough, they're in a
sense right by definition (excepting cases where student aggravation
is used as a deliberate pedagogical tool -- something *I* wouldn't
dare try...), but that doesn't mean that the reasons they give should
be taken at face value.

I'd say that R-notes is about three times too *short* for a tutorial.
Discounting the examples it's about 60 pages; the notes I'm writing
for my medical PhD's are already twice that size and will probably end
somewhere around 170 pages, and this covers absolutely *no*
programming. Also, R-notes has no pedagogical sequencing (i.e. read
the first n pages and be able to do something useful, the next n
learning some more, etc.), no repetition and extension of earlier
stuff, etc.

There's nothing really wrong with that, because that isn't the kind of
document the R-notes tries to be, it's more of a structured language
overview. Some people can actually learn the language from that kind
of material alone (it's certainly better than starting from the manual
pages), but many others will feel it's like learning a human language
from a grammar book. Once you *have* learned it, document like R-notes
become much more useful than tutorial because of the stricter
structure. An index would probably be a good thing in all cases,
though.

What experience do people have with textbooks on S? Do we already have
something that fits the students' (i.e. our) needs or do "we" need to
write it ourself? (Not quite knowing who "we" should be..)
Paul Gilbert
# 
It might be better and easier to use a general purpose full texted
search such as the one for S-news at statlib
<http://lib.stat.cmu.edu/s-news>. It is all done with publicly available
programs. It sure would be nice to have that facility for R-help as
well.

Paul Gilbert


=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
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
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Friedrich Leisch
# 
PG> It might be better and easier to use a general purpose full texted
PG> search such as the one for S-news at statlib
PG> <http://lib.stat.cmu.edu/s-news>. It is all done with publicly available
PG> programs. It sure would be nice to have that facility for R-help as
PG> well.

That's something with top priority on my list ...

I already wanted to do that earlier and sent a corresponding email
(hopefully not only to R-core) ... searching the pages would be
definetely an absolute great thing.

My only problem is how to setup such a thing without a
web-server. All software packages I'm aware of use cgi scripts and
need a http server running. That's something we want to avoid, because
not everybody running R has the means of running an http server.

If you (or somebody else) could provide me with software to do such a
search without need for a http server that would definetely be one of
the next things for me to include into the R help system.

Otherwise we could take a vote if we still want search depending on
the existence of a http server ... in that case I'm aware of several
GPL'ed search packages, e.g., we use htdig here for our web server.



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
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Paul Gilbert
# 
I'm afraid I don't know how to do this. I assume the http server uses a
cgi which runs something to do the search, and this could probably be
run without the server. But then you might be faced with building an
non-HTML user interface, which might not be so easy. On the other hand,
if you can run it directly from R, rather than from an HTML form, it
might work with other help formats as well.

Best of luck,
Paul

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
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
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Friedrich Leisch
# 
PG> I'm afraid I don't know how to do this.

welcome to the club ...

PG> I assume the http server uses a
PG> cgi which runs something to do the search, and this could probably be
PG> run without the server.

yes

PG> But then you might be faced with building an
PG> non-HTML user interface, which might not be so easy. On the other hand,
PG> if you can run it directly from R, rather than from an HTML form, it
PG> might work with other help formats as well.

well, it could probably be done without troubles in a java script
... but I've never programmed java before ... so that's more of a long
term project ... 

has anybody some spare time to help out?

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