[Rd] Flat documentation?

[Dirk Eddelbuettel]

This requirement of a particular comment strikes me as more 
restrictive than the requirement of having to learn the .Rd format. 

My preferred "dumb" format is Perl's POD.  It has a very simple 
markup structures, paragraphs come trough as is (in an ascii sense
of WYSIWYG) and it does require the user to comment code in any
particular way.  Would that (or something like it) be an alternative?

Dirk

> Dear Duncan,
> 
> At 10:51 AM 12/12/2002 -0500, Duncan Murdoch wrote:
> >On Thu, 12 Dec 2002 09:35:40 -0500, you wrote in message
> ><5.1.0.14.2.20021212092533.01ddb880@mcmail.cis.mcmaster.ca>:
> >
> > >Dear Duncan,
> > >
> > >At 09:18 AM 12/12/2002 -0500, Duncan Murdoch wrote:
> >
> > >>For example, if it's done with
> > >>comments (which would be my preference), there should be a way to
> > >>enter multi-line comments (like /* ...  */ in C).  If it's done with
> > >>attributes there needs to be an easy way to put free-form text into
> > >>the attribute.
> > >
> > >I can think of several ways to store a multi-line text attribute: a vector
> > >of strings, a string with new-line characters, etc. It would be easiest to
> > >import the text from a file, and it would be up to help() to display the
> > >information correctly.
> >
> >Storage isn't a problem, I'm thinking of the user interface.  I
> >normally write my functions in a text editor, then source them into R.
> >Other people use a workspace as the primary place to store functions.
> >Both methods should allow for easy addition of lightweight
> >documentation.
> 
> I was assuming the use of your third style. At present -- in the absence of 
> multiline comments -- that would require #ing each comment line at the 
> start of the function.
> 
> Alternatively, you could create a separate text file, say sum.txt, and 
> define the function as:
> 
>          sum <- function(x, y) x + y
>          doc(sum, "sum.txt")
> 
> [or sum <- doc(sum, "sum.txt") for an implementation of doc() without side 
> effects.]
> 
> Either method should work whether functions are kept in text files or in 
> saved workspaces.
> 
> >One problem with using embedded comments is that people don't agree on
> >the One True Comment Style.  For example, I wrote a Turbo Pascal
> >language parser once that built help files from comments in Pascal
> >source, and I found it very useful.  However, when I gave it away to
> >other people, I found that everyone has their own comment style, and
> >they didn't like the assumptions my parser was making about how to put
> >the comments into the help file.  For example this sort of problem
> >(translated into R) came up.  Which style of source should I assume?
> >
> >Version 1:
> >
> >  # Add two vectors
> >  sum <- function(x, y) x+y
> >
> >  # Subtract two vectors
> >  diff <- function(x, y) x-y
> >
> >Version 2:  (This one makes more sense in TP, where you give the
> >function header in one section, and the implementation in another)
> >
> >  sum <- function(x, y) x+y
> >  # Add two vectors
> >
> >  diff <- function(x, y) x-y
> >  # Subtract two vectors
> >
> >Version 3:
> >
> >  sum <- function(x, y) {
> >         # Add two vectors
> >         x+y
> >   }
> >
> >  diff <- function(x, y) {
> >         # Subtract two vectors
> >         x-y
> >   }
> 
> Regards,
>   John
> 
> -----------------------------------------------------
> John Fox
> Department of Sociology
> McMaster University
> Hamilton, Ontario, Canada L8S 4M4
> email: jfox@mcmaster.ca
> phone: 905-525-9140x23604
> web: www.socsci.mcmaster.ca/jfox
> -----------------------------------------------------
> 
> ______________________________________________
> R-devel@stat.math.ethz.ch mailing list
> http://www.stat.math.ethz.ch/mailman/listinfo/r-devel
> 
> 
> 

-- 
According to the latest figures, 43% of all signatures are totally worthless.