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

[Dan Tenenbaum]

----- 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]]
>>>
>>> _______________________________________________
>>> Bioc-devel at r-project.org mailing list
>>> https://stat.ethz.ch/mailman/listinfo/bioc-devel
>>
>> _______________________________________________
>> Bioc-devel at r-project.org mailing list
>> https://stat.ethz.ch/mailman/listinfo/bioc-devel