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

[Andrzej Oleś]

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))

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

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?

Cheers,
Andrzej

	[[alternative HTML version deleted]]