why is \alias{anRpackage} not mandatory?

classic Classic list List threaded Threaded
25 messages Options
12
Reply | Threaded
Open this post in threaded view
|

why is \alias{anRpackage} not mandatory?

Thomas Petzoldt
Dear R developers,

if one uses package.skeleton() to create a new package, then a file
anRpackage.Rd with the following entries is prepared:

\name{anRpackage-package}
\alias{anRpackage-package}
\alias{anRpackage}
\docType{package}


Packages created this way have a definite entry or overview page, so:

?anRpackage

gives new users of a certain package a pointer where to start reading.

This is similar for packages which have the same name as their main
workhorse function, e.g. zoo or nlme, but there are many packages which
don't have an \alias{anRpackage}.

"Writing R Extensions", sec. 2.1.4 says:

"Packages may have an overview man page with an \alias pkgname-package,
e.g. `utils-package' for the utils package, when package?pkgname will
open that help page. If a topic named pkgname does not exist in another
Rd file, it is helpful to use this as an additional \alias."

My question: what speaks against making this sentence more pronounced
and why not NOTE-ing a missing package alias in the package check?


Thomas Petzoldt



--
Thomas Petzoldt
Technische Universitaet Dresden
Institut fuer Hydrobiologie
01062 Dresden
GERMANY

http://tu-dresden.de/Members/thomas.petzoldt

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: why is \alias{anRpackage} not mandatory?

Duncan Murdoch
Thomas Petzoldt wrote:

> Dear R developers,
>
> if one uses package.skeleton() to create a new package, then a file
> anRpackage.Rd with the following entries is prepared:
>
> \name{anRpackage-package}
> \alias{anRpackage-package}
> \alias{anRpackage}
> \docType{package}
>
>
> Packages created this way have a definite entry or overview page, so:
>
> ?anRpackage
>
> gives new users of a certain package a pointer where to start reading.
>
> This is similar for packages which have the same name as their main
> workhorse function, e.g. zoo or nlme, but there are many packages which
> don't have an \alias{anRpackage}.
>
> "Writing R Extensions", sec. 2.1.4 says:
>
> "Packages may have an overview man page with an \alias pkgname-package,
> e.g. `utils-package' for the utils package, when package?pkgname will
> open that help page. If a topic named pkgname does not exist in another
> Rd file, it is helpful to use this as an additional \alias."
>
> My question: what speaks against making this sentence more pronounced
> and why not NOTE-ing a missing package alias in the package check?
>
>  
Not everybody likes the idea of the overview man page, so when I wrote
that I left it weak.  Some of the disadvantages:

 - there are lots of packages without one, so this would create a lot of
work for people to add them.

 - the ones that do exist tend to include outdated information.  People
update the DESCRIPTION file but forget to update the corresponding
information in the overview.

 - in general there's a lot of dissatisfaction with the Rd format, so
there's reluctance to invest any more effort in it.

It would probably be a good idea to generate one automatically if not
provided by the author, at build or install time:  this would address
the first point.  I've been slowly working on some fixes that address
the second point.  (The current idea is to use Sweave-like constructs to
import things from the DESCRIPTION file at install time.)  There's no
way to address the third point other than providing a better format, and
I don't see any prospect of that happening.

Duncan Murdoch

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: why is \alias{anRpackage} not mandatory?

Thomas Petzoldt
Duncan Murdoch wrote:

> Thomas Petzoldt wrote:
>> Dear R developers,
>>
>> if one uses package.skeleton() to create a new package, then a file
>> anRpackage.Rd with the following entries is prepared:
>>
>> \name{anRpackage-package}
>> \alias{anRpackage-package}
>> \alias{anRpackage}
>> \docType{package}
>>
>>
>> Packages created this way have a definite entry or overview page, so:
>>
>> ?anRpackage
>>
>> gives new users of a certain package a pointer where to start reading.
>>
>> This is similar for packages which have the same name as their main
>> workhorse function, e.g. zoo or nlme, but there are many packages
>> which don't have an \alias{anRpackage}.
>>
>> "Writing R Extensions", sec. 2.1.4 says:
>>
>> "Packages may have an overview man page with an \alias
>> pkgname-package, e.g. `utils-package' for the utils package, when
>> package?pkgname will open that help page. If a topic named pkgname
>> does not exist in another Rd file, it is helpful to use this as an
>> additional \alias."
>>
>> My question: what speaks against making this sentence more pronounced
>> and why not NOTE-ing a missing package alias in the package check?
>>
>>  
> Not everybody likes the idea of the overview man page, so when I wrote
> that I left it weak.  Some of the disadvantages:

You speak about the disadvantages but there are, of course, obvious
advantages. Almost all scientific papers start with an abstract, why not
requesting one for software packages, at least for new ones?

> - there are lots of packages without one, so this would create a lot of
> work for people to add them.

No, I don't think that this is too much work. Positively speaking, it's
one small contribution to bring more light into the exponentially
growing haystack.

What about starting to advertise the use of \alias{anRpackage}, i.e. a
short article in R News and subsequently an email to the developers.

> - the ones that do exist tend to include outdated information.  People
> update the DESCRIPTION file but forget to update the corresponding
> information in the overview.

This is in fact a problem. Suggestions:

- propose basic style guidelines (in an R-News article)
- allow variables in .Rd files (your idea to allow "Sweave like
constructs" may be even better). In addition to entries from
DESCRIPTION, one can think also about importing data from CITATION and
possibly also from other resources.

> - in general there's a lot of dissatisfaction with the Rd format, so
> there's reluctance to invest any more effort in it.

You are right, .Rd has its limitations, but as you say, there is nothing
better available in the moment. (BTW: I heard rumours at useR! about
discussions on a meta documentation format? Is there any public
information about this??)

> It would probably be a good idea to generate one automatically if not
> provided by the author, at build or install time:  this would address
> the first point.  

A reasonable idea -- at least if combined with a motivating request to
package authors to provide an own one.

> I've been slowly working on some fixes that address
> the second point.  (The current idea is to use Sweave-like constructs to
> import things from the DESCRIPTION file at install time.)  There's no
> way to address the third point other than providing a better format, and
> I don't see any prospect of that happening.

So if there are no advances in that direction I see no other choice than
using the existing mechanisms! Recently, I had several contacts with
package authors who were not even aware about the possibility of
providing a package information .Rd file.

> Duncan Murdoch
>

Thanks, Thomas P.

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: why is \alias{anRpackage} not mandatory?

Duncan Murdoch
On 06/10/2008 8:06 AM, Thomas Petzoldt wrote:

> Duncan Murdoch wrote:
>> Thomas Petzoldt wrote:
>>> Dear R developers,
>>>
>>> if one uses package.skeleton() to create a new package, then a file
>>> anRpackage.Rd with the following entries is prepared:
>>>
>>> \name{anRpackage-package}
>>> \alias{anRpackage-package}
>>> \alias{anRpackage}
>>> \docType{package}
>>>
>>>
>>> Packages created this way have a definite entry or overview page, so:
>>>
>>> ?anRpackage
>>>
>>> gives new users of a certain package a pointer where to start reading.
>>>
>>> This is similar for packages which have the same name as their main
>>> workhorse function, e.g. zoo or nlme, but there are many packages
>>> which don't have an \alias{anRpackage}.
>>>
>>> "Writing R Extensions", sec. 2.1.4 says:
>>>
>>> "Packages may have an overview man page with an \alias
>>> pkgname-package, e.g. `utils-package' for the utils package, when
>>> package?pkgname will open that help page. If a topic named pkgname
>>> does not exist in another Rd file, it is helpful to use this as an
>>> additional \alias."
>>>
>>> My question: what speaks against making this sentence more pronounced
>>> and why not NOTE-ing a missing package alias in the package check?
>>>
>>>  
>> Not everybody likes the idea of the overview man page, so when I wrote
>> that I left it weak.  Some of the disadvantages:
>
> You speak about the disadvantages but there are, of course, obvious
> advantages. Almost all scientific papers start with an abstract, why not
> requesting one for software packages, at least for new ones?

We already require one in the DESCRIPTION file for all packages, which
you can see with

library(help=packagename)

This is related to my first two points:  people have already done this
work so they are reluctant to do it again, and duplicate information is
a bad idea.

I think the R help system is too fragmented:  it's hard to discover all
the different types of help that are already there (Rd files,
DESCRIPTION files, vignettes, the manuals, NEWS, CHANGES, ChangeLogs,
SVN logs, source comments, mailing lists, web pages and publications,
...).  I think having a ?packagename man page is a good place for a
single starting point, and I consider packages without one to be poorly
documented.  But obviously, not everyone agrees.

>> - there are lots of packages without one, so this would create a lot of
>> work for people to add them.
>
> No, I don't think that this is too much work. Positively speaking, it's
> one small contribution to bring more light into the exponentially
> growing haystack.

I agree, and I even added these to all the packages under my control:
but there are hundreds of package authors, and some have different
priorities than you and me.

> What about starting to advertise the use of \alias{anRpackage}, i.e. a
> short article in R News and subsequently an email to the developers.

I would have thought that putting this into NEWS and Writing R
Extensions was the right way to advertise it.  If people don't read
those, why would you think they'll read R News?  But more is better, so
go ahead and submit an article to R News.

I don't like robot mailings, so I wouldn't appreciate an email on this.
  I don't recommend that you send one.


>
>> - the ones that do exist tend to include outdated information.  People
>> update the DESCRIPTION file but forget to update the corresponding
>> information in the overview.
>
> This is in fact a problem. Suggestions:
>
> - propose basic style guidelines (in an R-News article)
> - allow variables in .Rd files (your idea to allow "Sweave like
> constructs" may be even better). In addition to entries from
> DESCRIPTION, one can think also about importing data from CITATION and
> possibly also from other resources.
>
>> - in general there's a lot of dissatisfaction with the Rd format, so
>> there's reluctance to invest any more effort in it.
>
> You are right, .Rd has its limitations, but as you say, there is nothing
> better available in the moment. (BTW: I heard rumours at useR! about
> discussions on a meta documentation format? Is there any public
> information about this??)

I first heard proposals for a replacement format at DSC 2001.  I don't
know of anything concrete.

Duncan Murdoch

>
>> It would probably be a good idea to generate one automatically if not
>> provided by the author, at build or install time:  this would address
>> the first point.  
>
> A reasonable idea -- at least if combined with a motivating request to
> package authors to provide an own one.
>
>> I've been slowly working on some fixes that address
>> the second point.  (The current idea is to use Sweave-like constructs to
>> import things from the DESCRIPTION file at install time.)  There's no
>> way to address the third point other than providing a better format, and
>> I don't see any prospect of that happening.
>
> So if there are no advances in that direction I see no other choice than
> using the existing mechanisms! Recently, I had several contacts with
> package authors who were not even aware about the possibility of
> providing a package information .Rd file.
>
>> Duncan Murdoch
>>
>
> Thanks, Thomas P.

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: why is \alias{anRpackage} not mandatory?

hadley wickham
In reply to this post by Thomas Petzoldt
>> - there are lots of packages without one, so this would create a lot of
>> work for people to add them.
>
> No, I don't think that this is too much work. Positively speaking, it's one
> small contribution to bring more light into the exponentially growing
> haystack.

It may not be much work for you, but I find any additional
requirements to the package format to be a real pain.  I have ~10
packages on CRAN and having to go through and add this extra
information all at once is a big hassle.  R releases tend to happen in
the middle of the US academic semester when I have a lot of other
things on my plate.

Additionally, I find that rdoc is the wrong format for lengthy
explanation and exposition - a pdf is much better - and I think that
the packages already have a abstract: the description field in
DESCRIPTION.  The main problem with vignettes at the moment is that
they must be sweave, a format which I don't really like.  I wish I
could supply my own pdf + R code file produced using whatever tools I
choose.

Hadley



--
http://had.co.nz/

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: why is \alias{anRpackage} not mandatory?

hadley wickham
In reply to this post by Thomas Petzoldt
> You are right, .Rd has its limitations, but as you say, there is nothing
> better available in the moment. (BTW: I heard rumours at useR! about
> discussions on a meta documentation format? Is there any public information
> about this??)

What do you mean by meta documentation format?  Do you mean roxygen -
http://cran.r-project.org/web/packages/roxygen ?

Hadley

--
http://had.co.nz/

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: why is \alias{anRpackage} not mandatory?

Thomas Petzoldt
In reply to this post by Duncan Murdoch
Duncan Murdoch wrote:

> On 06/10/2008 8:06 AM, Thomas Petzoldt wrote:
>> Duncan Murdoch wrote:
>>> Thomas Petzoldt wrote:
>>>> Dear R developers,
>>>>
>>>> if one uses package.skeleton() to create a new package, then a file
>>>> anRpackage.Rd with the following entries is prepared:
>>>>
>>>> \name{anRpackage-package}
>>>> \alias{anRpackage-package}
>>>> \alias{anRpackage}
>>>> \docType{package}
>>>>
>>>>
>>>> Packages created this way have a definite entry or overview page, so:
>>>>
>>>> ?anRpackage
>>>>
>>>> gives new users of a certain package a pointer where to start reading.
>>>>
>>>> This is similar for packages which have the same name as their main
>>>> workhorse function, e.g. zoo or nlme, but there are many packages
>>>> which don't have an \alias{anRpackage}.
>>>>
>>>> "Writing R Extensions", sec. 2.1.4 says:
>>>>
>>>> "Packages may have an overview man page with an \alias
>>>> pkgname-package, e.g. `utils-package' for the utils package, when
>>>> package?pkgname will open that help page. If a topic named pkgname
>>>> does not exist in another Rd file, it is helpful to use this as an
>>>> additional \alias."
>>>>
>>>> My question: what speaks against making this sentence more
>>>> pronounced and why not NOTE-ing a missing package alias in the
>>>> package check?
>>>>
>>>>  
>>> Not everybody likes the idea of the overview man page, so when I
>>> wrote that I left it weak.  Some of the disadvantages:
>>
>> You speak about the disadvantages but there are, of course, obvious
>> advantages. Almost all scientific papers start with an abstract, why
>> not requesting one for software packages, at least for new ones?
>
> We already require one in the DESCRIPTION file for all packages, which
> you can see with
>
> library(help=packagename)
>
> This is related to my first two points:  people have already done this
> work so they are reluctant to do it again, and duplicate information is
> a bad idea.


I agree, and I also don't like duplicate inconsistent "information", but
simply try the following:

options(htmlhelp=TRUE)
library(help="base")

The result is now displayed in text format and new users don't know how
to proceed. I say new users, because an experienced user knows what to
do ... and if nothing helps he makes a grep over the sources.

> I think the R help system is too fragmented:  it's hard to discover all
> the different types of help that are already there (Rd files,
> DESCRIPTION files, vignettes, the manuals, NEWS, CHANGES, ChangeLogs,
> SVN logs, source comments, mailing lists, web pages and publications,
> ...).  I think having a ?packagename man page is a good place for a
> single starting point, and I consider packages without one to be poorly
> documented.  But obviously, not everyone agrees.

*I* agree -- completely with the that paragraph.

>>> - there are lots of packages without one, so this would create a lot
>>> of work for people to add them.
>>
>> No, I don't think that this is too much work. Positively speaking,
>> it's one small contribution to bring more light into the exponentially
>> growing haystack.
>
> I agree, and I even added these to all the packages under my control:
> but there are hundreds of package authors, and some have different
> priorities than you and me.

O.K., I see, so I suggest to add an additional motivating sentence to:

http://developer.r-project.org/Rds.html

and possibly an automatism that shows (or converts) the output of

library(help="foo")

to a formatted page in the appropriate help format (e.g. html).

>> What about starting to advertise the use of \alias{anRpackage}, i.e. a
>> short article in R News and subsequently an email to the developers.
>
> I would have thought that putting this into NEWS and Writing R
> Extensions was the right way to advertise it.  If people don't read
> those, why would you think they'll read R News?  But more is better, so
> go ahead and submit an article to R News.

People like me may read "Writing R Extensions" several times and then
have a look into some of the most prominent packages and get insecure,
as only few use this mechanism.

> I don't like robot mailings, so I wouldn't appreciate an email on this.
>  I don't recommend that you send one.

Beware, not at all! But I think it was good to open this thread on
r-devel  :-)

>>
>>> - the ones that do exist tend to include outdated information.  
>>> People update the DESCRIPTION file but forget to update the
>>> corresponding information in the overview.
>>
>> This is in fact a problem. Suggestions:
>>
>> - propose basic style guidelines (in an R-News article)
>> - allow variables in .Rd files (your idea to allow "Sweave like
>> constructs" may be even better). In addition to entries from
>> DESCRIPTION, one can think also about importing data from CITATION and
>> possibly also from other resources.
>>
>>> - in general there's a lot of dissatisfaction with the Rd format, so
>>> there's reluctance to invest any more effort in it.
>>
>> You are right, .Rd has its limitations, but as you say, there is
>> nothing better available in the moment. (BTW: I heard rumours at useR!
>> about discussions on a meta documentation format? Is there any public
>> information about this??)
>
> I first heard proposals for a replacement format at DSC 2001.  I don't
> know of anything concrete.
>
> Duncan Murdoch

Not concrete. I don't even know if these rumours were related to
something like Roxygen, extensions of a new DESCRIPTION format handling
more automated processing on CRAN (e.g. evaluation by Taskview authors)
or discussion about the list of keywords, but I'm sure that there are
several points that need strategic discussion between core and "the
developer base", including a pragmatic way to finalize conclusions.

>>
>>> It would probably be a good idea to generate one automatically if not
>>> provided by the author, at build or install time:  this would address
>>> the first point.  
>>
>> A reasonable idea -- at least if combined with a motivating request to
>> package authors to provide an own one.
>>
>>> I've been slowly working on some fixes that address the second
>>> point.  (The current idea is to use Sweave-like constructs to import
>>> things from the DESCRIPTION file at install time.)  There's no way to
>>> address the third point other than providing a better format, and I
>>> don't see any prospect of that happening.
>>
>> So if there are no advances in that direction I see no other choice
>> than using the existing mechanisms! Recently, I had several contacts
>> with package authors who were not even aware about the possibility of
>> providing a package information .Rd file.
>>
>>> Duncan Murdoch
>>>
>>
>> Thanks, Thomas P.
>

Thomas P.

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: why is \alias{anRpackage} not mandatory?

Thomas Petzoldt
In reply to this post by hadley wickham
Dear Hadley,

thank you very much for your comments.

hadley wickham wrote:

>>> - there are lots of packages without one, so this would create a lot of
>>> work for people to add them.
>> No, I don't think that this is too much work. Positively speaking, it's one
>> small contribution to bring more light into the exponentially growing
>> haystack.
>
> It may not be much work for you, but I find any additional
> requirements to the package format to be a real pain.  I have ~10
> packages on CRAN and having to go through and add this extra
> information all at once is a big hassle.  R releases tend to happen in
> the middle of the US academic semester when I have a lot of other
> things on my plate.

O.K., but the discussion with Duncan shows:

- the required information is already available (in DESCRIPTION),
- one can think about ways to generate the page automatically for
existing packages,
- the intro can be short and should link to other pages or PDFs,
- one should avoid doubling and inconsistency.

> Additionally, I find that rdoc is the wrong format for lengthy
> explanation and exposition - a pdf is much better - and I think that
> the packages already have a abstract: the description field in
> DESCRIPTION.  

o.k., but abstract may be (technically) in the wrong format and does not
point to the other relevant parts of the package documentation.

> The main problem with vignettes at the moment is that
> they must be sweave, a format which I don't really like.  I wish I
> could supply my own pdf + R code file produced using whatever tools I
> choose.
>
 > Hadley

I like Sweave, and it is also possible to include your own PDFs and R
files and then to reference them in anRpackage.Rd.

Thomas P.

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: why is \alias{anRpackage} not mandatory?

hadley wickham
>> It may not be much work for you, but I find any additional
>> requirements to the package format to be a real pain.  I have ~10
>> packages on CRAN and having to go through and add this extra
>> information all at once is a big hassle.  R releases tend to happen in
>> the middle of the US academic semester when I have a lot of other
>> things on my plate.
>
> O.K., but the discussion with Duncan shows:
>
> - the required information is already available (in DESCRIPTION),
> - one can think about ways to generate the page automatically for existing
> packages,
> - the intro can be short and should link to other pages or PDFs,
> - one should avoid doubling and inconsistency.

I'm obviously not going to object if it's done automatically, and I
already strive to avoid doubling and inconsistency by producing most
my documentation algorithmically.  I think you are being cavalier by
not caring about the extra work you want package authors to do.

>> Additionally, I find that rdoc is the wrong format for lengthy
>> explanation and exposition - a pdf is much better - and I think that
>> the packages already have a abstract: the description field in
>> DESCRIPTION.
>
> o.k., but abstract may be (technically) in the wrong format and does not
> point to the other relevant parts of the package documentation.

Then I don't think you should call what you want an abstract.

>> The main problem with vignettes at the moment is that
>> they must be sweave, a format which I don't really like.  I wish I
>> could supply my own pdf + R code file produced using whatever tools I
>> choose.
>
> I like Sweave, and it is also possible to include your own PDFs and R files
> and then to reference them in anRpackage.Rd.

Yes, but they're not vignettes - which means they're not listed under
vignette() and it's yet another place for people to look for
documentation.

Hadley


--
http://had.co.nz/

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: why is \alias{anRpackage} not mandatory?

Duncan Murdoch
On 10/6/2008 9:55 AM, hadley wickham wrote:

>>> It may not be much work for you, but I find any additional
>>> requirements to the package format to be a real pain.  I have ~10
>>> packages on CRAN and having to go through and add this extra
>>> information all at once is a big hassle.  R releases tend to happen in
>>> the middle of the US academic semester when I have a lot of other
>>> things on my plate.
>>
>> O.K., but the discussion with Duncan shows:
>>
>> - the required information is already available (in DESCRIPTION),
>> - one can think about ways to generate the page automatically for existing
>> packages,
>> - the intro can be short and should link to other pages or PDFs,
>> - one should avoid doubling and inconsistency.
>
> I'm obviously not going to object if it's done automatically, and I
> already strive to avoid doubling and inconsistency by producing most
> my documentation algorithmically.  I think you are being cavalier by
> not caring about the extra work you want package authors to do.
>
>>> Additionally, I find that rdoc is the wrong format for lengthy
>>> explanation and exposition - a pdf is much better - and I think that
>>> the packages already have a abstract: the description field in
>>> DESCRIPTION.
>>
>> o.k., but abstract may be (technically) in the wrong format and does not
>> point to the other relevant parts of the package documentation.
>
> Then I don't think you should call what you want an abstract.
>
>>> The main problem with vignettes at the moment is that
>>> they must be sweave, a format which I don't really like.  I wish I
>>> could supply my own pdf + R code file produced using whatever tools I
>>> choose.
>>
>> I like Sweave, and it is also possible to include your own PDFs and R files
>> and then to reference them in anRpackage.Rd.
>
> Yes, but they're not vignettes - which means they're not listed under
> vignette() and it's yet another place for people to look for
> documentation.

Vignettes have R code in them and a way to extract it, so it's
misleading to call something that's just a .pdf file a vignette.  But I
imagine there could be other ways to mix R code with documentation
besides the existing Sweave formats.  The most obvious way to add
another one is to write another Sweave driver.  I think it would require
changes to the base of R to allow for Sweave drivers in packages,
working with files that don't have extensions (R|r|S|s)(nw|tex), but in
principle I don't see any real objection to adding that.

Duncan Murdoch

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: why is \alias{anRpackage} not mandatory?

Thomas Petzoldt
In reply to this post by hadley wickham
hadley wickham wrote:

>>> It may not be much work for you, but I find any additional
>>> requirements to the package format to be a real pain.  I have ~10
>>> packages on CRAN and having to go through and add this extra
>>> information all at once is a big hassle.  R releases tend to happen in
>>> the middle of the US academic semester when I have a lot of other
>>> things on my plate.
>> O.K., but the discussion with Duncan shows:
>>
>> - the required information is already available (in DESCRIPTION),
>> - one can think about ways to generate the page automatically for existing
>> packages,
>> - the intro can be short and should link to other pages or PDFs,
>> - one should avoid doubling and inconsistency.
>
> I'm obviously not going to object if it's done automatically, and I
> already strive to avoid doubling and inconsistency by producing most
> my documentation algorithmically.  I think you are being cavalier by
> not caring about the extra work you want package authors to do.

Sorry if my question was misunderstood this way, but I have not
requested additional work, I simply asked "why is \alias{anRpackage} not
mandatory?"

The answer was, that they are problems with inconsistencies that can be
technically solved and that it may be too much work for some package
authors with lots of packages (can also be solved with technical means),
but that other users and developers would enjoy it to have such a
starting point.

O.K., I agree that the suggestion of NOTE-ing a missing
\alias{anRpackage} during package check was a bad idea (currently ;-),
but that one can think about a combination of a technical means and an
optional entry, analogously to the CITATION file.

>
>>> Additionally, I find that rdoc is the wrong format for lengthy
>>> explanation and exposition - a pdf is much better - and I think that
>>> the packages already have a abstract: the description field in
>>> DESCRIPTION.
>> o.k., but abstract may be (technically) in the wrong format and does not
>> point to the other relevant parts of the package documentation.
>
> Then I don't think you should call what you want an abstract.

Some sort of abstract, overview or, more precise, an *entry point*.

>>> The main problem with vignettes at the moment is that
>>> they must be sweave, a format which I don't really like.  I wish I
>>> could supply my own pdf + R code file produced using whatever tools I
>>> choose.
>> I like Sweave, and it is also possible to include your own PDFs and R files
>> and then to reference them in anRpackage.Rd.
>
> Yes, but they're not vignettes - which means they're not listed under
> vignette() and it's yet another place for people to look for
> documentation.

You are right, they are not vignettes in the strict sense, but they can
be listed in the help index of the package, the place where the majority
of "normal R users" starts to look.


ThPe

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

?foo to fall back to help(package="foo") [Was: why is \alias{anRpackage} not mandatory?]

Simon Urbanek
In reply to this post by Duncan Murdoch

On Oct 6, 2008, at 8:47 , Duncan Murdoch wrote:

> On 06/10/2008 8:06 AM, Thomas Petzoldt wrote:
>> Duncan Murdoch wrote:
>>> Thomas Petzoldt wrote:
>>>> Dear R developers,
>>>>
>>>> if one uses package.skeleton() to create a new package, then a  
>>>> file anRpackage.Rd with the following entries is prepared:
>>>>
>>>> \name{anRpackage-package}
>>>> \alias{anRpackage-package}
>>>> \alias{anRpackage}
>>>> \docType{package}
>>>>
>>>>
>>>> Packages created this way have a definite entry or overview page,  
>>>> so:
>>>>
>>>> ?anRpackage
>>>>
>>>> gives new users of a certain package a pointer where to start  
>>>> reading.
>>>>
>>>> This is similar for packages which have the same name as their  
>>>> main workhorse function, e.g. zoo or nlme, but there are many  
>>>> packages which don't have an \alias{anRpackage}.
>>>>
>>>> "Writing R Extensions", sec. 2.1.4 says:
>>>>
>>>> "Packages may have an overview man page with an \alias pkgname-
>>>> package, e.g. `utils-package' for the utils package, when package?
>>>> pkgname will open that help page. If a topic named pkgname does  
>>>> not exist in another Rd file, it is helpful to use this as an  
>>>> additional \alias."
>>>>
>>>> My question: what speaks against making this sentence more  
>>>> pronounced and why not NOTE-ing a missing package alias in the  
>>>> package check?
>>>>
>>>>
>>> Not everybody likes the idea of the overview man page, so when I  
>>> wrote that I left it weak.  Some of the disadvantages:
>> You speak about the disadvantages but there are, of course, obvious  
>> advantages. Almost all scientific papers start with an abstract,  
>> why not requesting one for software packages, at least for new ones?
>
> We already require one in the DESCRIPTION file for all packages,  
> which you can see with
>
> library(help=packagename)
>

Yes, but this is way too long to write - could we add a fall-back so  
that if ?foo alias doesn't exist but package foo does then ?foo is  
equivalent to help(package="foo")? At least for the way I use help it  
would help a lot...

Cheers,
S


> This is related to my first two points:  people have already done  
> this work so they are reluctant to do it again, and duplicate  
> information is a bad idea.
>
> I think the R help system is too fragmented:  it's hard to discover  
> all the different types of help that are already there (Rd files,  
> DESCRIPTION files, vignettes, the manuals, NEWS, CHANGES,  
> ChangeLogs, SVN logs, source comments, mailing lists, web pages and  
> publications, ...).  I think having a ?packagename man page is a  
> good place for a single starting point, and I consider packages  
> without one to be poorly documented.  But obviously, not everyone  
> agrees.
>
>>> - there are lots of packages without one, so this would create a  
>>> lot of work for people to add them.
>> No, I don't think that this is too much work. Positively speaking,  
>> it's one small contribution to bring more light into the  
>> exponentially growing haystack.
>
> I agree, and I even added these to all the packages under my  
> control: but there are hundreds of package authors, and some have  
> different priorities than you and me.
>
>> What about starting to advertise the use of \alias{anRpackage},  
>> i.e. a short article in R News and subsequently an email to the  
>> developers.
>
> I would have thought that putting this into NEWS and Writing R  
> Extensions was the right way to advertise it.  If people don't read  
> those, why would you think they'll read R News?  But more is better,  
> so go ahead and submit an article to R News.
>
> I don't like robot mailings, so I wouldn't appreciate an email on  
> this.  I don't recommend that you send one.
>
>
>>> - the ones that do exist tend to include outdated information.  
>>> People update the DESCRIPTION file but forget to update the  
>>> corresponding information in the overview.
>> This is in fact a problem. Suggestions:
>> - propose basic style guidelines (in an R-News article)
>> - allow variables in .Rd files (your idea to allow "Sweave like  
>> constructs" may be even better). In addition to entries from  
>> DESCRIPTION, one can think also about importing data from CITATION  
>> and possibly also from other resources.
>>> - in general there's a lot of dissatisfaction with the Rd format,  
>>> so there's reluctance to invest any more effort in it.
>> You are right, .Rd has its limitations, but as you say, there is  
>> nothing better available in the moment. (BTW: I heard rumours at  
>> useR! about discussions on a meta documentation format? Is there  
>> any public information about this??)
>
> I first heard proposals for a replacement format at DSC 2001.  I  
> don't know of anything concrete.
>
> Duncan Murdoch
>
>>> It would probably be a good idea to generate one automatically if  
>>> not provided by the author, at build or install time:  this would  
>>> address the first point.
>> A reasonable idea -- at least if combined with a motivating request  
>> to package authors to provide an own one.
>>> I've been slowly working on some fixes that address the second  
>>> point.  (The current idea is to use Sweave-like constructs to  
>>> import things from the DESCRIPTION file at install time.)  There's  
>>> no way to address the third point other than providing a better  
>>> format, and I don't see any prospect of that happening.
>> So if there are no advances in that direction I see no other choice  
>> than using the existing mechanisms! Recently, I had several  
>> contacts with package authors who were not even aware about the  
>> possibility of providing a package information .Rd file.
>>> Duncan Murdoch
>>>
>> Thanks, Thomas P.
>
> ______________________________________________
> [hidden email] mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>
>

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: ?foo to fall back to help(package="foo") [Was: why is \alias{anRpackage} not mandatory?]

Duncan Murdoch
On 10/6/2008 11:00 AM, Simon Urbanek wrote:

> On Oct 6, 2008, at 8:47 , Duncan Murdoch wrote:
>
>> On 06/10/2008 8:06 AM, Thomas Petzoldt wrote:
>>> Duncan Murdoch wrote:
>>>> Thomas Petzoldt wrote:
>>>>> Dear R developers,
>>>>>
>>>>> if one uses package.skeleton() to create a new package, then a  
>>>>> file anRpackage.Rd with the following entries is prepared:
>>>>>
>>>>> \name{anRpackage-package}
>>>>> \alias{anRpackage-package}
>>>>> \alias{anRpackage}
>>>>> \docType{package}
>>>>>
>>>>>
>>>>> Packages created this way have a definite entry or overview page,  
>>>>> so:
>>>>>
>>>>> ?anRpackage
>>>>>
>>>>> gives new users of a certain package a pointer where to start  
>>>>> reading.
>>>>>
>>>>> This is similar for packages which have the same name as their  
>>>>> main workhorse function, e.g. zoo or nlme, but there are many  
>>>>> packages which don't have an \alias{anRpackage}.
>>>>>
>>>>> "Writing R Extensions", sec. 2.1.4 says:
>>>>>
>>>>> "Packages may have an overview man page with an \alias pkgname-
>>>>> package, e.g. `utils-package' for the utils package, when package?
>>>>> pkgname will open that help page. If a topic named pkgname does  
>>>>> not exist in another Rd file, it is helpful to use this as an  
>>>>> additional \alias."
>>>>>
>>>>> My question: what speaks against making this sentence more  
>>>>> pronounced and why not NOTE-ing a missing package alias in the  
>>>>> package check?
>>>>>
>>>>>
>>>> Not everybody likes the idea of the overview man page, so when I  
>>>> wrote that I left it weak.  Some of the disadvantages:
>>> You speak about the disadvantages but there are, of course, obvious  
>>> advantages. Almost all scientific papers start with an abstract,  
>>> why not requesting one for software packages, at least for new ones?
>>
>> We already require one in the DESCRIPTION file for all packages,  
>> which you can see with
>>
>> library(help=packagename)
>>
>
> Yes, but this is way too long to write - could we add a fall-back so  
> that if ?foo alias doesn't exist but package foo does then ?foo is  
> equivalent to help(package="foo")? At least for the way I use help it  
> would help a lot...

?foo and help("foo") return an object with a class whose print method
displays the help.  So doing this would require a new class with a
different print method.  It seems cleaner to me to ask people to provide
the ?foo topic within the existing system, as we do now, or to produce
the topic automatically at install time, so it works within the existing
system.

Duncan Murdoch

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: ?foo to fall back to help(package="foo") [Was: why is \alias{anRpackage} not mandatory?]

Simon Urbanek

On Oct 6, 2008, at 11:18 , Duncan Murdoch wrote:

> On 10/6/2008 11:00 AM, Simon Urbanek wrote:
>> On Oct 6, 2008, at 8:47 , Duncan Murdoch wrote:
>>> On 06/10/2008 8:06 AM, Thomas Petzoldt wrote:
>>>> Duncan Murdoch wrote:
>>>>> Thomas Petzoldt wrote:
>>>>>> Dear R developers,
>>>>>>
>>>>>> if one uses package.skeleton() to create a new package, then a  
>>>>>> file anRpackage.Rd with the following entries is prepared:
>>>>>>
>>>>>> \name{anRpackage-package}
>>>>>> \alias{anRpackage-package}
>>>>>> \alias{anRpackage}
>>>>>> \docType{package}
>>>>>>
>>>>>>
>>>>>> Packages created this way have a definite entry or overview  
>>>>>> page,  so:
>>>>>>
>>>>>> ?anRpackage
>>>>>>
>>>>>> gives new users of a certain package a pointer where to start  
>>>>>> reading.
>>>>>>
>>>>>> This is similar for packages which have the same name as their  
>>>>>> main workhorse function, e.g. zoo or nlme, but there are many  
>>>>>> packages which don't have an \alias{anRpackage}.
>>>>>>
>>>>>> "Writing R Extensions", sec. 2.1.4 says:
>>>>>>
>>>>>> "Packages may have an overview man page with an \alias pkgname-  
>>>>>> package, e.g. `utils-package' for the utils package, when  
>>>>>> package? pkgname will open that help page. If a topic named  
>>>>>> pkgname does  not exist in another Rd file, it is helpful to  
>>>>>> use this as an  additional \alias."
>>>>>>
>>>>>> My question: what speaks against making this sentence more  
>>>>>> pronounced and why not NOTE-ing a missing package alias in the  
>>>>>> package check?
>>>>>>
>>>>>>
>>>>> Not everybody likes the idea of the overview man page, so when  
>>>>> I  wrote that I left it weak.  Some of the disadvantages:
>>>> You speak about the disadvantages but there are, of course,  
>>>> obvious  advantages. Almost all scientific papers start with an  
>>>> abstract,  why not requesting one for software packages, at least  
>>>> for new ones?
>>>
>>> We already require one in the DESCRIPTION file for all packages,  
>>> which you can see with
>>>
>>> library(help=packagename)
>>>
>> Yes, but this is way too long to write - could we add a fall-back  
>> so  that if ?foo alias doesn't exist but package foo does then ?foo  
>> is  equivalent to help(package="foo")? At least for the way I use  
>> help it  would help a lot...
>
> ?foo and help("foo") return an object with a class whose print  
> method displays the help.  So doing this would require a new class  
> with a different print method.  It seems cleaner to me to ask people  
> to provide the ?foo topic within the existing system, as we do now,

... which doesn't seem to work - that's why we have the discussion ;).


> or to produce the topic automatically at install time, so it works  
> within the existing system.
>

... which if ok with me - that would fit the bill ...

Thanks,
Simon

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: why is \alias{anRpackage} not mandatory?

Berwin A Turlach-2
In reply to this post by hadley wickham
G'day Hadley,

On Mon, 6 Oct 2008 08:55:14 -0500
"hadley wickham" <[hidden email]> wrote:

> >> The main problem with vignettes at the moment is that
> >> they must be sweave, a format which I don't really like.  I wish I
> >> could supply my own pdf + R code file produced using whatever
> >> tools I choose.
> >
> > I like Sweave, and it is also possible to include your own PDFs and
> > R files and then to reference them in anRpackage.Rd.
>
> Yes, but they're not vignettes - which means they're not listed under
> vignette() and it's yet another place for people to look for
> documentation.
Well, there is a kind of subversive way of how do use the facilities
provided to vignettes for PDFs that were created by some other
mechanism.  That was discussed sometime ago on this list.  The idea was
to create an "empty" vignette that uses the LaTeX package pdfpages to
include the existing PDF into a vignette.

Since you ended up with essentially two copies of the same PDF file,
you can use .Rbuildignore to exclude the original PDF from the build
and only distribute the PDF created from the vignette.

This trick worked really well as long as "R CMD check" was not trying
to latex the .tex file produced from the vignette (apparently since R
2.6.0 the behaviour of "R CMD check" in this respect has changed,
though the "Writing R Extension" manual was not updated to reflect
this change; which reminds me that I promised Kurt Hornik to file a
bug report about this).  What makes things worse is that with the
current TeX installation on Debian based operating system, latex hangs
if a file, from which pdfpages wants to include some (or all) pages,
does not exist.  That is "R CMD check" on such a tar.gz file hangs and
doesn't stop with an error message.

The solution that I am using at the moment is shown in the attached
file which resides in inst/doc of the lasso2 package on my machine.  On
my machine, "R CMD build" and "R CMD check" will, of course, work.
Essentially, this vignette only creates the information needed to index
it and then includes the file Manual-wo-help.pdf (which is the old help
for the S-Plus version of that package; I should really update all
this). Manual-wo-help.pdf is excluded from lasso2_x.y-z.tar.gz via an
entry in .Rbuildignore but the vignette is distributed and listed under
vignette().  And "R CMD check" on works the .tar.gz file too.

Cheers,

        Berwin

=========================== Full address =============================
Berwin A Turlach                            Tel.: +65 6516 4416 (secr)
Dept of Statistics and Applied Probability        +65 6516 6650 (self)
Faculty of Science                          FAX : +65 6872 3919      
National University of Singapore    
6 Science Drive 2, Blk S16, Level 7          e-mail: [hidden email]
Singapore 117546                    http://www.stat.nus.edu.sg/~statba

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

Manual-vignette.Rnw (365 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: why is \alias{anRpackage} not mandatory?

Gabor Grothendieck
In reply to this post by Duncan Murdoch
Some examples are:
- be able to use brew package or similar alternative in place of Sweave
- provide a pdf regardless how it was generated
without ugly workarounds and still let the user get a list of all pdf
documents in
one place, e.g.
  library(help = mypackage)
should list the vignettes and other pdfs too so its all together and
there should
be some facility similar to vignettes() to easily access them.


On Mon, Oct 6, 2008 at 10:22 AM, Duncan Murdoch <[hidden email]> wrote:

> On 10/6/2008 9:55 AM, hadley wickham wrote:
>>>>
>>>> It may not be much work for you, but I find any additional
>>>> requirements to the package format to be a real pain.  I have ~10
>>>> packages on CRAN and having to go through and add this extra
>>>> information all at once is a big hassle.  R releases tend to happen in
>>>> the middle of the US academic semester when I have a lot of other
>>>> things on my plate.
>>>
>>> O.K., but the discussion with Duncan shows:
>>>
>>> - the required information is already available (in DESCRIPTION),
>>> - one can think about ways to generate the page automatically for
>>> existing
>>> packages,
>>> - the intro can be short and should link to other pages or PDFs,
>>> - one should avoid doubling and inconsistency.
>>
>> I'm obviously not going to object if it's done automatically, and I
>> already strive to avoid doubling and inconsistency by producing most
>> my documentation algorithmically.  I think you are being cavalier by
>> not caring about the extra work you want package authors to do.
>>
>>>> Additionally, I find that rdoc is the wrong format for lengthy
>>>> explanation and exposition - a pdf is much better - and I think that
>>>> the packages already have a abstract: the description field in
>>>> DESCRIPTION.
>>>
>>> o.k., but abstract may be (technically) in the wrong format and does not
>>> point to the other relevant parts of the package documentation.
>>
>> Then I don't think you should call what you want an abstract.
>>
>>>> The main problem with vignettes at the moment is that
>>>> they must be sweave, a format which I don't really like.  I wish I
>>>> could supply my own pdf + R code file produced using whatever tools I
>>>> choose.
>>>
>>> I like Sweave, and it is also possible to include your own PDFs and R
>>> files
>>> and then to reference them in anRpackage.Rd.
>>
>> Yes, but they're not vignettes - which means they're not listed under
>> vignette() and it's yet another place for people to look for
>> documentation.
>
> Vignettes have R code in them and a way to extract it, so it's misleading to
> call something that's just a .pdf file a vignette.  But I imagine there
> could be other ways to mix R code with documentation besides the existing
> Sweave formats.  The most obvious way to add another one is to write another
> Sweave driver.  I think it would require changes to the base of R to allow
> for Sweave drivers in packages, working with files that don't have
> extensions (R|r|S|s)(nw|tex), but in principle I don't see any real
> objection to adding that.

The change I would like to see in Sweave would be the ability to include
or exclude R and latex sections based on the results of the R code. That
would allow it to be used in conditional report generation and not just
documentation.  I know there are workarounds but they are ugly and
not satisfactory in my opinion.  Also passing arguments to
R CMD Sweave would be nice.

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: why is \alias{anRpackage} not mandatory?

Duncan Murdoch
On 07/10/2008 9:11 AM, Gabor Grothendieck wrote:

> Some examples are:
> - be able to use brew package or similar alternative in place of Sweave
> - provide a pdf regardless how it was generated
> without ugly workarounds and still let the user get a list of all pdf
> documents in
> one place, e.g.
>   library(help = mypackage)
> should list the vignettes and other pdfs too so its all together and
> there should
> be some facility similar to vignettes() to easily access them.

The inst/doc directory can already have an index.html file to list all
the documents there.  This will be automatically produced from the
vignettes if it doesn't exist, but if you have other files, you can
write it manually.

This shows up in the HTML help system.  It would be better if it showed
up in all help formats, but there are other ways to do that, e.g.
creating an Rd help page pointing to those files.

Duncan Murdoch

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: why is \alias{anRpackage} not mandatory?

Gabor Grothendieck
On Tue, Oct 7, 2008 at 9:46 AM, Duncan Murdoch <[hidden email]> wrote:

> On 07/10/2008 9:11 AM, Gabor Grothendieck wrote:
>>
>> Some examples are:
>> - be able to use brew package or similar alternative in place of Sweave
>> - provide a pdf regardless how it was generated
>> without ugly workarounds and still let the user get a list of all pdf
>> documents in
>> one place, e.g.
>>  library(help = mypackage)
>> should list the vignettes and other pdfs too so its all together and
>> there should
>> be some facility similar to vignettes() to easily access them.
>
> The inst/doc directory can already have an index.html file to list all the
> documents there.  This will be automatically produced from the vignettes if
> it doesn't exist, but if you have other files, you can write it manually.
>
> This shows up in the HTML help system.  It would be better if it showed up
> in all help formats, but there are other ways to do that, e.g. creating an
> Rd help page pointing to those files.
>

That's good to know but I assume you are pointing out what is
available so we know as we still need to address the fragmentation.

In particular, CHM, not HTML, is the default help format under Windows so
having it in HTML will not be useful for most Windows users.
I generally do create a mypackage-package.Rd file but that's less
reliable for user since they can't be sure a package has one and
since its manually done it can become inconsistent more easily.

Also the pdf's should appear in auto-generated web pages of this sort:
http://cran.r-project.org/web/packages/zoo/index.html
in addition to the library(help = ...) page.

To me Sweave is ok for documentation but there is a learning curve
and it can't be used for reports that have conditional processing
(e.g. a report full of tables for which data is missing in some reports
so you want to eliminate those sections and the corresponding
text for those runs) without ugly workarounds which means those tend
to be written
in plain R.
Thus one can't  benefit from Sweave as much as desirable. Thus the one
other place that one might leverage your knowledge of Sweave over a
sufficiently
large set of tasks is unavailable.  I also find that despite Stangle
that debugging with
Sweave can be onerous at times.  What I would really like is one tool that
would do it all.  If the only time you use Sweave is when you create packages
there is  going to be a long time between usages and you are bound to forget
but if it can be used more widely it would be better.

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: why is \alias{anRpackage} not mandatory?

hadley wickham
In reply to this post by Duncan Murdoch
> This shows up in the HTML help system.  It would be better if it showed up
> in all help formats, but there are other ways to do that, e.g. creating an
> Rd help page pointing to those files.

Or you can just link to them from your website.

I don't think you'd argue with the statement that there's already too
many different ways to find R documentation.  There are plenty of
hacks and work-arounds to jam different types of documentation in
different places, but they are just hacks and work-arounds.  My
feeling is that evolutionary modification of the documentation system
is only going to get us so far, and at some point the entire
foundations need to be rethought.

Of course, the problem is having enough time to do that, and then to
code up the solution!

Hadley

--
http://had.co.nz/

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: why is \alias{anRpackage} not mandatory?

Duncan Murdoch
On 07/10/2008 10:17 AM, hadley wickham wrote:
>> This shows up in the HTML help system.  It would be better if it showed up
>> in all help formats, but there are other ways to do that, e.g. creating an
>> Rd help page pointing to those files.
>
> Or you can just link to them from your website.
>
> I don't think you'd argue with the statement that there's already too
> many different ways to find R documentation.  

I think that's a paraphrase of one of my earlier posts.

> There are plenty of
> hacks and work-arounds to jam different types of documentation in
> different places, but they are just hacks and work-arounds.  My
> feeling is that evolutionary modification of the documentation system
> is only going to get us so far, and at some point the entire
> foundations need to be rethought.

I don't agree with this.  Back in 2001 when this was first proposed it
might have worked, but there's far too much inertia now to make a big
change.  Weren't you the one who objected to a requirement for a
foo-package help topic?  How would you like to rewrite all the help
files for all of your packages?  (I imagine not much.  I'm certainly not
going to do that for mine.)

I think any change we make now needs to be incremental, but there's a
tremendous amount of friction against anything at all, and very few
offers of support to actually do the work.

Here are things I'm currently working on, that I'd appreciate support for:

  - Formalizing the Rd format and writing a parser for it.  (The current
parser finds errors in about 2-5% of base package man files.  Should it
be more permissive? I would guess it will find more errors in
contributed packages.)  Can it make changes?  I would really love to say
that % is nothing special in an R code section in an Rd file, but there
are lots of pages that use it as a comment, as it is documented to be.

  - Allowing macros in an Rd file.  This will give a way to avoid
duplication of information, will allow you to include an index of
whatever sort of files you want, generated on the fly, and will slice
bread if you write a macro for it.

  - Source level debugging support.  Gabor mentioned that it's hard to
debug Sweave files; this could help.


> Of course, the problem is having enough time to do that, and then to
> code up the solution!

That's the main problem.  I find the coding is much easier than the
design, though.  I can code on my own, but the design really needs
careful thought and criticism.  (It's easy to get shallow criticism; the
hard thing is to get useful criticism.)  That means at least two people
need to find time to work together on the problem, and in my experience,
that has almost never happened with any of the problems above.  So I
move very, very slowly on them.

Duncan Murdoch

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
12