R help - Feb 2013 - First R package, advice

On 02/07/2013 05:00 AM, r-help-request at r-project.org
wrote:
> I'd argue that there's an important distinction between documenting
a
> function (how to use it) vs. documenting an algorithm (how it works).
> I think noweb can work well for describing how something works, but
> it's not so good for describing how to use it
I'm a big fan of noweb for the source code, take a look a the coxme package
for extensive
use of this.  That contains the most complex mathematics of any code I have
written, and
it is a big help to have real equations and discussion mixed in with the code. 
The sparse
matrix algorithms aren't very transparent either so it is a plus on that
front too.  A big
help to me whenever I look back at something.
   That given, I agree with the above that documentation of the algorithm and 
documentation of useage are disjoint tasks.  The pdf file from my noweb source
is of
critical importance to someone changing the code, and of essentially no use to
anyone
else.  Use vignettes for the latter.

  Terry Therneau

I am still researching my best choices.

IMHO, every programming and every typesetting language ever invented
should have had a compatible basic escape sequence built in.  simple.
 just compatible with one another. something like a specific escape
sequence on the first column, like

#%@@==R
  means that now an R segment starts.

#%@@==LaTeX
  means that now a LaTeX segment starts.  (markdown and html are other
good text language choices. for programming, markdown or markup would
usually make most sense.)

maybe '#if' would have been better.  it is escaped in many languages,
except TeX and C, of course.  or '//R'.  or '%%R'.  whatever. 
IF ONLY
every language had used '#' as its comment character, it would have
been a good start.

the source could then be run through any compiler or typesetter and
every one would know what is meant for it.  if no such escapes are in
the source, then the executable would assume it owns the whole source.
 any compiles should/could decide to ignore sections not meant for it.
importantly, your favorite editor or ide would know how to highlight
the regions.

right now, the world is a mess.  perl escapes from perl to docs with
=POD commands; doxygen2 escapes from R to docs with #' commands on
every line; latex escapes with \verb+ commands, well sort of.  html
escapes with <pre> commands, but what is in between must not contain
certain sequences.  C escapes with '#if 0'.

there is really a benefit to standardization here, but the world's
standardization bodies are too unstandardized to make this feasible.

so I am contemplating---do I want R code that can be processed to spit
out some latex, or latex code that can be processed to spit out some
R, or my own code that can become both latex and R?

I could live with rolling my own IF ONLY my ide/editor would
understand my new format.  I do not have the skills to tell emacs how
to switch syntax-highlighting in the middle of files.

this collective path-dependence will plague us for decades, having
created a cost without a benefit.

/iaw
----
Ivo Welch (ivo.welch at gmail.com)