R-alpha: Proposal for a new R doc source format

[Friedrich Leisch]

With help by Kurt and Martin I have written a short proposal for a new
R doc source format that should be easier to parse using, e.g.,
perl. There should be especially a clearer distinction between text
and keywords.

Here we go, please make comments, corrections, etc.

Best,
Fritz

**********************************************************

Conversion:
-----------

A perl module providing functions to parse the source text which are
used by other functions to produce latex, html, etc. 


Environment delimiters:
-----------------------
Change from () to {} as in latex and most programming languages such
that `()' can be used in equations without need for escaping


Keywords:
---------
Start all keywords with a backslash like in latex, because IMO the
word TITLE should not be something special simply because it is
written in capital letters.

if possible, keep latex syntax whenever possible, e.g., replace
greekalpha with \alpha, LDOTS with \ldots, etc.


Unknown keywords are ignored and result in a warning message from the
parser.


Logical Blocks:
---------------

The current logical blocks of the source files such as

	TITLE(...)
	USAGE(...)
	ALIAS(...)
	ARGUMENTS(...)

are kept and the first step of parsing the file is splitting it into
these blocks.

Then the single blocks are parsed and splitted into their parts (like
ARG lists), the remaining parts should then be something like `Rdoc text'
which must only be correctly converted into the output language
(equations, bold font, ...).


VALUE(S)
--------

Here only one environment should be necessary, if it contains more
than one ARG environment, it is what's now VALUES.


New keywords:
-------------

	TITLE, USAGE, ...	\title{...}, \usage{...}, ...
	ARG			\arg{argname}{description}
	BOLD			\bf{word}
	ITALIC			\emph{word}
	LANG			\code{word}
	PARA			\par
	BLANK			\blank
	LINK			\link{...}
	DOTS			\dots
	LDOTS			\ldots
	EQUALS			\=       ???but why is this needed???
	LT			\lt
	GT			\gt
	...

replace all math constructs with latex commands

Equation commands:

	EQN()			\eqn{A1}{A2}   ??? or \eqn[A2]{A1} ???
	DEQN(A1 @@ A2)		\deqn{A1}{A2}

where A1 is pure latex and A2 is an ascii version of the formula. If
only one argument is given, A1 and A2 are taken to be the same (such
that we don't have to write \eqn{x}{x}). \eqn corresponds to latex's
$$ and \deqn corresponds to \[ \].


Hard line break
---------------

\cr gives a hard line break



Comments:
---------

Ignore everything after a `%', \% gives the corresponding
character. We don't use the usual # for comments, because # appears to
often in example environments.







=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
r-devel mailing list -- Read http://www.ci.tuwien.ac.at/~hornik/R/R-FAQ.html
Send "info", "help", or "[un]subscribe"
(in the "body", not the subject !)  To: r-devel-request@stat.math.ethz.ch
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-