[Rd] Best practices in developing package: From a single file

[Duncan Murdoch]

On 31/01/2018 8:59 AM, Mark van der Loo wrote:
> I fully agree with Joris and Hadley on roxygen2.
> 
> 
> Additionally:
> 
> I wrote and published my first package before roxygen (or roxygen2) was 
> available. I found editing .Rd extremely terse (especially when code is 
> updated). For example, the fact that there are no spaces allowed between 
> } and { in \param{}{} has hurt my brain quite a few times, especially 

There's no \param macro in Rd.  You're probably thinking of \item{}{} or 
\section{}{}, or some other two-arg macro.  There aren't very many of 
them, but there are a few.

If it really is \item, then the error message you get would look 
something like this:

Warning: bad markup (extra space?) at foo.Rd:15:16

That's column 16 of line 15.  I'm not sure this guess is right, because 
that message does seem pretty informative.

There are also a couple of 1 or 2 argument macros (\eqn and \deqn), 
where the space would make the parser think you were using the 1 
argument version.  I think that's the same behaviour as LaTeX, which the 
Rd format is loosely based on.


> since R CMD check did not give any useful error messages about it. For 
> me it is a signal that the Rd parser is rather primitive.

Originally the format was defined in a really ad hoc way:  help pages 
were formed not by parsing the Rd file, but by applying a sequence of 
substitutions to it.  I wrote a parser following the usual R policy of 
trying not to break too much existing code.  This wasn't easy because 
the format had grown into something fairly awful, but I wouldn't call it 
primitive.  At the time I was really hoping someone else would propose 
something better, but I don't think that ever happened.

Duncan Murdoch


  On the other
> hand Roxygen2 now usually gives pretty good error messages when I syntax 
> error something.
> 
> Also, the 'parent' of roxygen is Doxygen, which was already widely used 
> (also by me) in the C/C++ community before roxygen was published. I 
> cannot remember anyone ever complaining about C/C++ documentation 
> deteriorating because of Doxygen.
> 
> 
> -Mark
> 
> 
> Op wo 31 jan. 2018 om 14:02 schreef Joris Meys <jorismeys at gmail.com 
> <mailto:jorismeys at gmail.com>>:
> 
>     On Wed, Jan 31, 2018 at 1:41 PM, Duncan Murdoch
>     <murdoch.duncan at gmail.com <mailto:murdoch.duncan at gmail.com>>
>     wrote:
> 
>      > On 31/01/2018 6:33 AM, Joris Meys wrote:
>      >
>      > 3. given your criticism, I'd like your opinion on where I can
>     improve the
>      >> documentation of
>     https://github.com/CenterForStatistics-UGent/pim. I'm
>      >> currently busy updating the help files for a next release on
>     CRAN, so your
>      >> input is more than welcome.
>      >>
>      >
>      > After this invitation I sent some private comments to Joris.  I
>     would say
>      > his package does a pretty good job of documentation; it isn't the
>     kind of
>      > Roxygen-using package that I was complaining about.  So I will
>     say I have
>      > received an example of a Roxygen-using package that
>      > has good help pages.
>      >
> 
>     Thank you for the nice compliment and the valuable tips.
> 
>     --
>     Joris Meys
>     Statistical consultant
> 
>     Department of Data Analysis and Mathematical Modelling
>     Ghent University
>     Coupure Links 653, B-9000 Gent (Belgium)
>     <https://maps.google.com/?q=Coupure+links+653,%C2%A0B-9000+Gent,%C2%A0Belgium&entry=gmail&source=g>
> 
>     -----------
>     Biowiskundedagen 2017-2018
>     http://www.biowiskundedagen.ugent.be/
> 
>     -------------------------------
>     Disclaimer : http://helpdesk.ugent.be/e-maildisclaimer.php
> 
>              [[alternative HTML version deleted]]
> 
>     ______________________________________________
>     R-devel at r-project.org <mailto:R-devel at r-project.org> mailing list
>     https://stat.ethz.ch/mailman/listinfo/r-devel
>