[Bioc-devel] Bioconductor Workflows: TOC and displaying document details

----- Original Message -----

From: "Aaron Lun" <alun at wehi.edu.au>
To: "Dan Tenenbaum" <dtenenba at fredhutch.org>
Cc: "bioc-devel" <bioc-devel at r-project.org>
Sent: Thursday, October 22, 2015 8:45:58 AM
Subject: Re: [Bioc-devel] Bioconductor Workflows: TOC and displaying

document details

Hi Dan,

The added TOC looks good; but can the lines also be hyperlinked to the
appropriate (sub)sections? This would make it a lot easier to use, like:

https://www.bioconductor.org/help/workflows/variants

Right now, it's like I'm reading a physical book; I'm pressing the TOC
line with my fingers, before remembering that I need to actually flip
the pages to get to where I need to go.

That's a good point and I should have caught that. The workflow builder
takes an .Rmd file and processes it to .md with
library(rmarkdown)
render(filename, md_document(toc=TRUE))

Then later in the pipeline, the engine that builds the bioc website
(nanoc) converts the md file to an HTML file with the same look and feel as
other pages on the web site.

The problem is that the render() command above generates a TOC but one
without links, for example given the following file called test.Rmd:

---begin---
# First H1

Some text.

## First H2

Some text.

# Second H1

Some text.

## Second H2

Some text.

### First H3

Some text.
---end---

The command above produces the following TOC:

-   First H1
    -   First H2
-   Second H1
    -   Second H2
        -   First H3

As you can see, no hyperlinks. Is anyone aware of a way to fix this?
Perhaps there is a pandoc
argument that can be passed?

I guess part of the problem is that until the document is processed into
html, there are no html headers wth ID attributes that can be linked to.

Perhaps we should just go back to the manual TOCs.
Dan

Cheers,

Aaron

On 19/10/15 23:47, Dan Tenenbaum wrote:

Hi Andrzej,

----- Original Message -----

From: "Andrzej Ole?" <andrzej.oles at gmail.com>
To: "bioc-devel" <bioc-devel at r-project.org>
Sent: Tuesday, October 13, 2015 5:39:25 AM
Subject: [Bioc-devel] Bioconductor Workflows: TOC and displaying

document

    details

Hi everyone,

while browsing through http://www.bioconductor.org/help/workflows/

I've

noticed some inconsistency in using TOC in workflow vignettes. As the

TOC

is currently not automatically generated, some authors create it

manually,

while others do not have it at all.

I suggest to address this shortcoming by leveraging the rmarkdown

build in

mechanism to automatically generate a TOC for all workflows freeing up

the

authors from the burden of curating it manually. For this to work, it

would

be probably enough to use during document conversion

library(rmarkdown)
render("document.Rmd", md_document(toc = TRUE))

I have implemented this. The next time workflow authors trigger a build

by

committing their source document(s), the automatic TOC will be

generated, so I

suggest that workflow authors remove any manually-generated TOC before
committing.

Incidentally, rebuilding will also cause the workflow to be rebuilt

under the

newly released Bioconductor 3.2.

possibly with the depth limited with 'toc_depth = 2'.

I decided not to limit the TOC depth.

Also, I think that it would be more readable and visually appealing to
present the document title, author and date in form of a proper

document

header (similarly as for regular BioC vignettes) above the "About This
Document" table. Regarding the table itself, it contains a lot of

technical

details (actually, even more than on package landing pages, like "First
Committed" or "SVN Revision"), which I'm not sure if they are

informative

to the end user and relevant to the content. Maybe these could be

either

moved to the document footer or dropped completely?

I will think about this one.
Thanks,
Dan

Cheers,
Andrzej

    [[alternative HTML version deleted]]