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

[Andrzej Oleś]

Hi Aaron, Dan,

thank you for reporting this! When I suggested adding the TOC I didn't
realize that the md_document() doesn't output it hyperlinked - my fault!

I was also surprised to find out that there is no easy fix for it as there
is no option for this in pandoc/rmarkdown.

However, I already have a working solution based on extending the
md_document() function, which builds on the suggestion from
http://stackoverflow.com/questions/29997263/linked-table-of-contents-toc-in-md-using-rmarkdown,
and I will incorporate it into BiocStyle. This will also facilitate the use
of BiocStyle-specific helper functions withing workflow vignettes (e.g.
ones for automatically adding links to packages like Biocpkg) in a similar
fashion as in BiocStyle::html_document()  without the need of explicitly
loading BiocStyle.

I just need to test and polish the code - I will communicate with Dan
off-list to resolve the TOC issue.

Cheers,
Andrzej

On Thu, Oct 22, 2015 at 6:39 PM, Dan Tenenbaum <dtenenba at fredhutch.org>
wrote:

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

	[[alternative HTML version deleted]]