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

[Dan Tenenbaum]

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