[R-wiki] Top level organization
Martin Maechler
maechler at stat.math.ethz.ch
Sat Feb 4 16:49:45 CET 2006
>>>>> "PhGr" == Philippe Grosjean <phgrosjean at sciviews.org>
>>>>> on Sat, 04 Feb 2006 14:50:54 +0100 writes:
PhGr> Martin Maechler wrote:
>>>>>>> "PhGr" == Philippe Grosjean <phgrosjean at sciviews.org>
>>>>>>> on Sat, 04 Feb 2006 08:17:38 +0100 writes:
>>
>>
PhGr> Gabor Grothendieck wrote:
>> >> On 2/3/06, Ben Bolker <bolker at zoo.ufl.edu> wrote:
>> >>
>> >>> Gabor Grothendieck wrote:
>> >>>
>> >>>> This is looking very good.
>> >>>
>> >>> definitely agree. I think we may eventually want
>> >>> to tweak the categories in Tips&tricks, but we're getting
>> >>> to the point now where we'll need to let some material
>> >>> accumulate before we can really decide on the best
>> >>> arrangement.
>> >>>
>> >>> A few comments:
>> >>>
>> >>>> - what is the difference among Manuals, Cookbooks and Tips and Tricks.
>> >>>> Its not clear to me.
>> >>>
>> >>> Manuals and "cookbooks" are longer and by a single or a few authors;
>> >>> tips and tricks are shorter and more collaborative (I've tried to
>> >>> clarify a little bit by adding a few short descriptions to
>> >>> "start2"). That said, I think the subdivision within "Guides"
>> >>
>> >>
>> >> This is still not clear.. There are THREE categories currently,
>> >> not two. The three possible categories I can see are:
>> >>
>> >> - official R manuals. The official manuals that come with R wifieid.
>>
PhGr> No, there is no plan to wikify the official R manuals (just a link to
PhGr> their PDF version on CRAN).
>>
>> why that? All the official R manuals (apart from the
>> "reference", i.e. the help pages) are written in *.texi
>> (texinfo) which then are translated to latex and pdf, but also
>> to HTML (and to Emacs info). Why not link to the HTML versions
>> of the official manuals, or maybe even "wikify" the HTML version
>> (but the "wikification" should setup in a way to be updatable
>> with every new release of R).
>>
>>
PhGr> There will be only a wikified version of the
PhGr> online help on R functions (in the R documentation section). This serves
PhGr> two purposes:
>>
>> .............
>>
>>
>> Martin Maechler, ETH Zurich
PhGr> Because the interest of making a Wiki version of the R manuals is to
PhGr> allow changes in them, even if restricted to a given group of users. If
PhGr> you allow this:
PhGr> - How do your merge those changes with the original texinfo version?
PhGr> - Who will decide what to keep and what to reject?
PhGr> - etc...
no changes allowed, but *notes* to the pages
PhGr> May be am I a little bit behind here, but I don't think the idea is to
PhGr> put *everything* in the Wiki. We want to put only what can be modified
PhGr> by R users. The only exception, currently, is the 'R documentation',
PhGr> alias the .Rd files that will be read-only, but with a discussion
PhGr> section at the end that will be editable. The Wiki is a *complement* to
PhGr> other resources, not a *replacement*, isn't it?
Indeed!
Where I can't really speak for all of us, I'd guess that most R-core
members consider *both* the help pages and the official
manuals *together* as ``the'' R documentation.
So what goes for the help pages should also be possible for the
manuals. Both categories will have to be easily updated for every
new R relase, i.e., should be mostly "read only" with the
possibility of "annotation".
Remember that one of the 3 "official R-core" statements on the
subject of 'R-wiki' was
>> - Suggestions for the R documentation would best be filtered through the
>> Wiki maintainers, who could e.g. supply suggested patches during the
>> alpha phase of an R release.
and I (and at least one other R core member) would mean to
include both the help pages and the "official manuals" in the
term "R documentation".
Of course it is no pre-requisite to have most of this available
when the wiki starts; OTOH, it would be really nice
to have both of these official documentation categories;
particularly since this is currently one weakness of the
help/docu system, that we haven't found a way to *link* between
the help pages and the manuals (in a platform-portable,
maintainable way).
Martin
PhGr> Otherwise, there is no technical barriers to put also the manuals (as
PhGr> read-only) on the Wiki. Same remark for package vignettes.
PhGr> Best,
PhGr> Philippe Grosjean
More information about the R-sig-wiki
mailing list