[R-wiki] Top level organization

[Martin Maechler]

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