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

[Aaron Lun]

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.

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
>