From Friedrich.Leisch@ci.tuwien.ac.at  Mon Sep  8 14:25:08 1997
From: Friedrich.Leisch@ci.tuwien.ac.at (Friedrich Leisch)
Date: Mon, 8 Sep 1997 15:25:08 +0200
Subject: R-alpha: old Rdoc 2 new Rdoc
In-Reply-To: <x2oh6df3zr.fsf@bush.kubism.ku.dk>
References: <199709011312.PAA03979@galadriel.ci.tuwien.ac.at>
 <x2oh6df3zr.fsf@bush.kubism.ku.dk>
Message-ID: <199709081325.PAA04403@galadriel.ci.tuwien.ac.at>

>>>>> On 01 Sep 1997 17:28:08 +0200,
>>>>> Peter Dalgaard BSA (PDB) wrote:

PDB> Friedrich Leisch <Friedrich.Leisch@ci.tuwien.ac.at> writes:
>> Attached is a conversion script for converting current R doc files to
>> the proposed new format ... I'm not sure if it handles everything

PDB> Speaking of the docs, we really need to make sure that our HTML pages
PDB> pass weblint or similar checkers. I just tried it and found several
PDB> pieces of strangeness. Basically, what you get out is stuff like

PDB> $ weblint /home/sfe/pd/R/html/funs/density.html
PDB> /home/sfe/pd/R/html/funs/density.html(1): <HEAD> must immediately follow <HTML>
PDB> /home/sfe/pd/R/html/funs/density.html(1): outer tags should be <HTML> .. </HTML>.
PDB> /home/sfe/pd/R/html/funs/density.html(2): empty container element <A>.
PDB> /home/sfe/pd/R/html/funs/density.html(90): illegal context for <TR> - must appear in <TABLE> element.
PDB> /home/sfe/pd/R/html/funs/density.html(93): illegal context for <TR> - must appear in <TABLE> element.
PDB> /home/sfe/pd/R/html/funs/density.html(96): illegal context for <TR> - must appear in <TABLE> element.
PDB> /home/sfe/pd/R/html/funs/density.html(99): illegal context for <TR> - must appear in <TABLE> element.
PDB> /home/sfe/pd/R/html/funs/density.html(102): illegal context for <TR> - must appear in <TABLE> element.
PDB> /home/sfe/pd/R/html/funs/density.html(126): <XMP> is obsolete.
PDB> /home/sfe/pd/R/html/funs/density.html(133): unknown element <->.
PDB> /home/sfe/pd/R/html/funs/density.html(134): no closing </XMP> seen for <XMP> on line 126.

PDB> Here's what I found of obvious pieces of "fluff":

PDB> The whole page needs to be inside <HTML>..</HTML>
PDB> "<" symbols make trouble, even within <PRE> (use "&lt;")
PDB> <XMP> should not be used ("use <PRE>" seems to be the idea)
PDB> <TR>'s need to be surrounded by a <TABLE> environment

PDB> "<" within <PRE> gets formatted correctly by Netscape, but not by
PDB> lynx, so it isn't all just formalities.

I agree totally that we should stick with the HTML standards.

The new conversion script is almost ready and currently in
`alpha-testing' by Martin and Kurt. I've checked its output with
weblint and on the HTML pages of the whole base library all I get are
only minor warnings:

attach.html(1): The HTML spec. recommends the TITLE be no longer than 64 characters.
chisquare.test.html(36): empty container element <P>.
detach.html(1): The HTML spec. recommends the TITLE be no longer than 64 characters.
ls.diag.html(1): The HTML spec. recommends the TITLE be no longer than 64 characters.
ls.print.html(1): The HTML spec. recommends the TITLE be no longer than 64 characters.
t.test.html(84): empty container element <P>.


which cannot be avoided without considerable effort or side effects ...
e.g., every browser that cannot handle long tiles will truncate them
anyway, so I see no purpose in doing this myself. But we can include
it as a recommendation that the title of a doc file is no longer than
64 characters (that makes sense anyway for the INDEX files etc.)



best,
fritz
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
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
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-


R-alpha: old Rdoc 2 new Rdoc
Friedrich Leisch