[R-pkg-devel] Sort order of vignette index?; adding purl'ed Rcode from asis vignette to vignette index?
Martin Maechler
m@ech|er @end|ng |rom @t@t@m@th@ethz@ch
Wed Jun 8 12:57:14 CEST 2022
>>>>> Duncan Murdoch
>>>>> on Thu, 2 Jun 2022 15:53:58 -0400 writes:
> On 02/06/2022 1:39 p.m., Carl Schwarz wrote:
>> Thanks for the suggestions.
>>
>> (a) Unfortunately, if you place the index.html directly into the inst/doc
>> directory, it is overwritten when the package source file (*tar.gz) is
>> created and then installed.
>> This is using RStudio on a Mac.... I did not try this on a Windows machine.
>>
>> But other files that you place in the inst/doc file are left alone and are
>> listed under the vignette index when you follow the "User guides, package
>> vignettes and other documentation" link.
>>
>> So strange that the index is overwritten but other files are left alone.
> That does sound like a bug...
>> (b) The relative links that are generated are quite long, e.g. <a
>> href="../../../library/SightabilityModel/doc/c-MoosePopR-SightabilityPopR-Demo.html">HTML</a>
>> and I don't fully understand where the "current" directory is when you
>> follow the "User guides, package vignettes and other
>> documentation" requiring you to go back up the directory tree and then go
>> back down.
>> I copied and modified these odd links for my other files and it worked fine.
> To see the links the help system is using, you can run it in an external
> browser using "help.start()". When I do that for rgl I see this link on
> the vignettes page:
> http://127.0.0.1:17854/library/rgl/doc/index.html
> and the first vignette is at
> http://127.0.0.1:17854/library/rgl/doc/WebGL.html
> generated from <a href="../../../library/rgl/doc/WebGL.html">.
> I forget why the index doesn't just use <a href="WebGL.html"> which
> would appear to be equivalent in this case, but I vaguely recall that
> there's a good reason for that. It might be because the links generated
> for static documentation are different.
> Duncan Murdoch
Apropos static documentation :
Some of you may remember that I (my institution's server) have been
providing static HTML help pages for 20 years or so at
https://stat.ethz.ch/R-manual
(linked from https://stat.ethz.ch/R/ or more importantly, the R-project.org
sidebar [Documentation] -> [Other], i.e.,
https://www.r-project.org/other-docs.html )
and there, e.g.,
https://stat.ethz.ch/R-manual/R-devel/library/grid/html/grid-package.html
or then
https://stat.ethz.ch/R-manual/R-devel/library/grid/doc/index.html
you can see (via "view source" [right click] in your browser)
the links some of which possibly could be made much shorter indeed,
but then the current code does not have to distinguish links
within the same package and those to another package (still
assumed to be in the same library though..).
Notably on the 2nd page ( = ...../index.html ),
I see that we still seem to have a buglet in our static html
construction, (and I see this also in R-patched), the first 28 lines being
~~~~~~~~~~~~~~~~~~~~~~~~~~~snip~~~~~~~~snip~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
<!DOCTYPE html>
<html>
<head><title>R: Vignettes and other documentation</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
<link rel="stylesheet" type="text/css" href="/doc/html/R.css" />
</head><body><div class="container">
<h1> Vignettes and other documentation
<img class="toplogo" src="/doc/html/Rlogo.svg" alt="[R logo]" />
</h1>
<hr/>
<div style="text-align: center;">
<a href="/doc/html/index.html"><img class="arrow" src="/doc/html/up.jpg" alt="[Top]" /></a>
</div>
<h2>Vignettes from package 'grid'</h2>
<table style="width: 100%;">
<col style="width: 22%;" />
<col style="width: 2%;" />
<col style="width: 50%;" />
<col style="width: 8%;" />
<col style="width: 8%;" />
<col style="width: 8%;" />
<tr><td style="text-align: right; vertical-align: top;"><a href="../../../library/grid/doc/displaylist.pdf">grid::displaylist</a></td>
<td></td><td style="vertical-align: top;">Display Lists in grid</td>
<td style="vertical-align: top;"><a href="../../../library/grid/doc/displaylist.pdf">PDF</a></td>
<td style="vertical-align: top;"><a href="../../../library/grid/doc/displaylist.Rnw">source</a></td>
<td style="vertical-align: top; white-space: nowrap"><a href="../../../library/grid/doc/displaylist.R">R code</a></td></tr>
<tr><td style="text-align: right; vertical-align: top;"><a href="../../../library/grid/doc/frame.pdf">grid::frame</a></td>
~~~~~~~~~~~~~~~~~~~~~~~~~~~snip~~~~~~~~snip~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
and in the first few lines *invalid* urls, already for the CSS (!) such as
<img class="toplogo" src="/doc/html/Rlogo.svg" alt="[R logo]" />
and a bit later, (the same mistake), invalid
<a href="/doc/html/index.html"><img class="arrow" src="/doc/html/up.jpg" alt="[Top]" /></a>
.... I won't time to find and fix the cause of the bug, at the moment,
so I'm happy if any of you readers does so, or even just opens
an R bugzilla report about it.
Martin
>>
>> (c) I have not tried the index.Rmd approach...
>>
>> Carl.
>>
>> On Thu, Jun 2, 2022 at 1:22 AM Sebastian Meyer <seb.meyer using fau.de> wrote:
>>
>>> Some quick comments:
>>>
>>> - You could place the index.html directly in the inst/doc folder of your
>>> package sources, avoiding the need for .install_extras from the
>>> vignettes folder. This approach is useful if there is additional
>>> non-vignette material in inst/doc.
>>>
>>> - As you say, links in index.html need to be relative to the installed
>>> *doc* dir, where the index file is located. For example, the simple links
>>> <a href="template.R">template script</a>,
>>> <a href="vignetteA.Rnw">source of vignette A</a>
>>> should work to reference a static Rscript inst/doc/template.R and a
>>> vignette built from vignettes/vignetteA.Rnw (copied to inst/doc by R CMD
>>> build), respectively.
>>>
>>> - It seems you could even generate the index.html via a vignette,
>>> index.Rmd, say. The downside is that this index vignette will be listed
>>> as a vignette (by browseVignettes(), for example) although it isn't
>>> really a vignette.
>>>
>>> - browseVignettes() sorts by vignette title, not by file name.
>>> Furthermore, its purpose is to browse *vignettes* also across packages,
>>> so is unrelated to the *doc* index for a given package, which may
>>> contain more than vignettes.
>>>
>>> Best regards,
>>>
>>> Sebastian Meyer
>>>
>>>
>>> Am 01.06.22 um 23:47 schrieb Carl Schwarz:
>>>> Here is some suggested text to be added to the Writing R Extensions
>>> manual.
>>>> Any suggestions for changes?
>>>>
>>>> 1.4.3. Customizing the vignette help index
>>>>
>>>> R provides two indices to the vignettes in a package (a) the
>>>> browseVignettes() function and (b) the html index of vignettes and other
>>>> user documentation available when you use help(package=xxx). The latter
>>> is
>>>> built when the package is installed.
>>>>
>>>>
>>>>
>>>> In some cases, customization of the html index is desirable. For example,
>>>> currently the entries in the index are sorted by the vignette engine
>>> used
>>>> to build the vignette and then by the file name of the vignette and a
>>>> different sort order may be desired. Or additional documents may wish to
>>> be
>>>> included, e.g., the purl()’d code from an “asis” vignette.
>>>>
>>>>
>>>>
>>>> Previous sections of this guide indicate that if an “index.html” file is
>>>> present in the inst/doc directory at the time of the build, then a new
>>>> “index.html” file will not be built. Previous sections also indicate how
>>> to
>>>> add additional files to the inst/doc directory. The following is then a
>>>> summary of the steps needed to customize the html index to the vignettes
>>> in
>>>> a package.
>>>>
>>>>
>>>>
>>>> 1. Create a revised ‘index.html’ file in the vignettes directory. It may
>>> be
>>>> easiest to copy an existing ‘doc/index.html’ file from an installed
>>>> package. The vignettes/index.html file should be in plain html and can be
>>>> modified to change the sort order or to add links to additional files to
>>> be
>>>> available to users. Note that files are referred to using relative path
>>>> names – follow the pattern in the copied file.
>>>>
>>>>
>>>>
>>>> 2. Add any other additional files to the vignettes directory that are to
>>> be
>>>> available to the user via the vignette help index.
>>>>
>>>>
>>>>
>>>> 3. Add an ‘.install_extras’ file to the vignettes directory (don’t forget
>>>> the leading period in this file’s name). This is a text file with the
>>> names
>>>> of the files in the vignettes directory to be added to the inst/doc
>>>> directory. Each line can be coded as a regular expression. At a minimum,
>>>> include ‘index.html’ to copy the vignettes/index.html file to the
>>> inst/doc
>>>> directory.
>>>>
>>>>
>>>>
>>>> 4. Check/build the package in the regular way.
>>>>
>>>>
>>>>
>>>> There is no evident way to modify the output of the browseVignettes()
>>>> function; however, this function currently sorts by the vignette file
>>> name
>>>> regardless of the vignette engine used.
>>>>
>>>> On Wed, Jun 1, 2022 at 1:04 AM Martin Maechler <
>>> maechler using stat.math.ethz.ch>
>>>> wrote:
>>>>
>>>>>>>>>> Jeff Newmiller
>>>>>>>>>> on Tue, 31 May 2022 16:09:16 -0700 writes:
>>>>>
>>>>> > FWIW the RStudio build is often not complete... it intentionally
>>>>> takes shortcuts that make test/run iteration faster... but you should
>>> make
>>>>> a habit of using the command line to build artifacts for sharing... it
>>> will
>>>>> help avoid gotchas.
>>>>>
>>>>> Yes, definitely.
>>>>>
>>>>> Notably, e.g., reloading the package sources (often via
>>>>> devtools) into a running R process instead of restarting R and
>>>>> loading/attaching the newly built and installed package (that
>>>>> you are developing) is much faster, but *NOT* equivalent and
>>>>> sometimes misleading -- because it's not easily possible to
>>>>> "revert" everything you did in your running R session {caches,
>>>>> method tables, DLLs, internal pointers, ...}.
>>>>>
>>>>> (read on, further down)
>>>>>
>>>>> > On May 31, 2022 3:53:57 PM PDT, Carl Schwarz <
>>>>> cschwarzstatsfuca using gmail.com> wrote:
>>>>> >> Success!
>>>>> >>
>>>>> >> Building on MT's note that if the inst/doc has an index.html
>>> file,
>>>>> R does
>>>>> >> NOT build a new index.
>>>>> >> At the end of Writing R Extensions Section 1.4, it states
>>>>> >> " When R CMD build builds the vignettes, it copies these and
>>> the
>>>>> vignette
>>>>> >> sources from directory vignettes to inst/doc. To install any
>>> other
>>>>> files
>>>>> >> from the vignettes directory, include a file
>>>>> vignettes/.install_extras which
>>>>> >> specifies these as Perl-like regular expressions on one or more
>>>>> lines.."
>>>>> >>
>>>>> >> So I copied the existing inst/doc/index.html file from the
>>> installed
>>>>> >> SighatbilityModel with the wrong sort order to my
>>>>> vignettes/index.html,
>>>>> >> edited this index.html file to get the right sort order. The
>>>>> index.html is
>>>>> >> just vanilla html so it is easy to modify "manually".
>>>>> >> Then I created a vignettes/.install_extras with a single entry
>>>>> "index.html"
>>>>> >> and now vignettes/index.html appears to be copied to inst/doc
>>> and
>>>>> so stops
>>>>> >> the building of the wrongly sorted index.
>>>>> >>
>>>>> >> Then I did a Rstudio -> Build -> BuildSourcePackage to create a
>>>>> tar.gz
>>>>> >> file; installed from the tar.gz file, and now my vignette index
>>> is
>>>>> sorted
>>>>> >> properly on my Mac machine.
>>>>> >> Also tried using devtools::check_win_release() to generate a
>>>>> windoze zip
>>>>> >> file; installed that; and the vignette index is again sorted
>>>>> properly on
>>>>> >> Windows machines.
>>>>> >>
>>>>> >> I'm hoping I can use this for (b) from my original query as
>>> well.
>>>>> >>
>>>>> >> This will mean that I have to "manually'" maintain the
>>>>> vignettes/index.html
>>>>> >> file, but that is straightforward.
>>>>> >>
>>>>> >> I hope this works when I submit to CRAN.
>>>>> >>
>>>>> >> How do I suggest to the R maintainers that an explicit section
>>> be
>>>>> added to
>>>>> >> the Writing R Extensions manual with the above steps so that
>>> future
>>>>> package
>>>>> >> writers don't repeat history? I'm willing to write the paragraph
>>>>> explaining
>>>>> >> the steps, but don't know who/how to proceed to get it added to
>>>>> Writing R
>>>>> >> Extensions.
>>>>> >>
>>>>> >> Carl Schwarz
>>>>>
>>>>> The WRE manual is part of the R sources, so formally you are
>>>>> proposing to improve (the documentation part of) R.
>>>>>
>>>>> You can propose a patch against the "R-devel" sources.
>>>>> If the changes are quite small and compact (as here), even on by e-mail.
>>>>> The source file is doc/manual/R-exts.texi
>>>>> in R's SVN (source server)
>>>>> https://svn.r-project.org/R/trunk/doc/manual/R-exts.texi
>>>>> or one of its mirrors (notably on github)
More information about the R-package-devel
mailing list