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.o...@gmail.com>
To: "bioc-devel" <bioc-devel@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@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/bioc-devel
_______________________________________________
Bioc-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/bioc-devel
_______________________________________________
Bioc-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/bioc-devel
