Re: [Bioc-devel] improving navigation within workflows

Sun, 06 Aug 2017 08:56:53 -0700 

On 08/04/2017 05:00 PM, Andrzej Oleś wrote:

Hi Vince,

thanks for your feedback. The floating TOC would be technically possible,
the question is more about the aesthetics of such solution. As we thought
of using the right column for the supplementary stuff such as figure/table
captions or footnotes, this space cannot harbor a floating TOC as it would
obscure the view of these items.

Regarding the document metadata section at the top: this is a fair point
and I'm interested to hear the opinion of others. Personally I would argue
that some of these information is quite important and should be emphasized
at the beginning, such as installation instructions or recent modification
and compilation dates. I agree that links to package tarballs are more
obscure and could be maybe moved somewhere downstream. As workflow pages
tend to be relatively long documents, I'm a bit worried though whether
burying it at the very bottom after the output of `sessionInfo()` won't
virtually prevent people from reaching it at all. I'm looking forward to
the thoughts of other developers on this.
I feel like most of the provenance and installation instruction at the top is relevant and important for successful use of the workflows, including the package name, installation instructions, and built / modified date. That leaves the Rscript (not essential but useful) and tar balls (obscure detail) which in principle could be moved.
Maybe there is scope for making the presentation of this information and similar information on package landing pages more consistent? 

Martin



Cheers,
Andrzej

On Fri, Aug 4, 2017 at 5:01 PM, Vincent Carey <st...@channing.harvard.edu>
wrote:


interesting.  is the floating toc not an option for this?  also, IMHO the
"about this document" should go at the end.  one wants the content to hit
the reader right away, not the provenance, i think.

On Fri, Aug 4, 2017 at 9:33 AM, Aaron Lun <a...@wehi.edu.au> wrote:


Mind -> blown. Yes, that's exactly what I wanted, thanks.

-Aaron

On 04/08/17 14:19, Andrzej Oleś wrote:

Hi Aaron,

I'm happy to inform that I've implemented your suggestion to add
navigation links at workflow pages. Feel free to have a look at the
working prototype under
https://www.bioconductor.org/help/workflows/testproj/testfile/

The new workflow-rendering engine which includes the navigation links
will be enabled soon after some additional testing is finished. The
transition will be announced in a separate email to the devel mailing

list.


Cheers,
Andrzej


On Mon, Jul 17, 2017 at 10:15 AM, Aaron Lun <a...@wehi.edu.au
<mailto:a...@wehi.edu.au>> wrote:

     Hi Andrzej,

     Interesting. I also didn't realize that we could get figure

referencing

     via bookdown, that's nice to know. I was thinking that the floating

TOC

     could go onto the right margin, but I guess that doesn't fit

anymore now

     that you have the footnotes and figure captions.

     CRAN-style links might be the best compromise, e.g., if they can be
     placed in the right margin. A simple set of three links
     (<previous><contents><next>) beside each section/subsection heading
     would probably sufficient for effective navigation, without using

up too

     much space.

     Cheers,

     Aaron

     On 17/07/17 00:35, Andrzej Oleś wrote:
     > Hi Aaron,
     >
     > thanks for your feedback. We are currently looking into ways of
     > improving the building of workflows for the website in order to

enable

     > cross references, html widgets, and similar. So far these were not
     > supported because of some technical constraints of the current
     > implementation which involves rendering the workflows into an
     > intermediate .md file. The new approach will overcome these

limitations

     > by skipping this intermediate step and rendering directly to

html. For a

     > preview see:
     > https://www.bioconductor.org/help/workflows/testproj/testfile/
     <https://www.bioconductor.org/help/workflows/testproj/testfile/>

(it

     also
     > uses a slightly modified layout with some of the supporting

information

     > such as figure and table captions, or footnotes moved to the

right column)

     >
     > Regarding the navigation, a floating TOC would be in principle

possible

     > in the new implementation. It is not entirely clear to me,

however,

     > weather this will visually work with the bioconductor.org <

http://bioconductor.org>

      > <http://bioconductor.org> website template. Links to the TOC,

such as

     > ones in e.g.
     > https://www.bioconductor.org/help/workflows/highthroughputassays
     <https://www.bioconductor.org/help/workflows/highthroughputassays>

could

     > be relatively easily inserted automatically after each section.

Static

     > CRAN-like solution as you mentioned it would probably require

some more

     > work.
     >
     > Cheers,
     > Andrzej
     >
     > On Sun, Jul 16, 2017 at 9:36 PM, Aaron Lun <a...@wehi.edu.au

<mailto:a...@wehi.edu.au>

     > <mailto:a...@wehi.edu.au <mailto:a...@wehi.edu.au>>> wrote:
     >
     >     Indeed, that's exactly what I was thinking of. I have a

floating TOC in

     >     my own Rmarkdown files, but I'm not sure if it's supported by

the

     >     workflow builder, given that it adds a separate hyperlinked

TOC to the

     >     start of the workflow page.
     >
     >     On 16/07/17 19:29, Vincent Carey wrote:
     >     > like this?
     >     >
     >     > http://bioconductor.org/packages/release/bioc/vignettes/

BiocStyle/inst/doc/AuthoringRmdVignettes.html

     <http://bioconductor.org/packages/release/bioc/vignettes/

BiocStyle/inst/doc/AuthoringRmdVignettes.html>

     >     <http://bioconductor.org/packages/release/bioc/vignettes/

BiocStyle/inst/doc/AuthoringRmdVignettes.html

     <http://bioconductor.org/packages/release/bioc/vignettes/

BiocStyle/inst/doc/AuthoringRmdVignettes.html>>

     >     >
     >     > On Sun, Jul 16, 2017 at 11:53 AM, Aaron Lun <

a...@wehi.edu.au <mailto:a...@wehi.edu.au> <mailto:a...@wehi.edu.au

     <mailto:a...@wehi.edu.au>>
      >     > <mailto:a...@wehi.edu.au <mailto:a...@wehi.edu.au>
     <mailto:a...@wehi.edu.au <mailto:a...@wehi.edu.au>>>> wrote:
      >     >
      >     >     Hello all,
      >     >
      >     >     I was wondering if there's any plans to improve the
     navigation for the
      >     >     BioC workflows. I was looking at my simpleSingleCell
     workflow:
      >     >
      >     >
     https://www.bioconductor.org/help/workflows/simpleSingleCell/
     <https://www.bioconductor.org/help/workflows/simpleSingleCell/>
      >
       <https://www.bioconductor.org/help/workflows/simpleSingleCell/
     <https://www.bioconductor.org/help/workflows/simpleSingleCell/>>
      >     >
       <https://www.bioconductor.org/help/workflows/simpleSingleCell/
     <https://www.bioconductor.org/help/workflows/simpleSingleCell/>
      >
       <https://www.bioconductor.org/help/workflows/simpleSingleCell/
     <https://www.bioconductor.org/help/workflows/simpleSingleCell/>>>
      >     >
      >     >     ... and I've realized that it's gotten pretty long.
     It's a pain to keep
      >     >     on scrolling up and down when I'm stuck in the middle
     of the document
      >     >     and I want to jump somewhere else quickly (or even just
     go to the TOC).
      >     >
      >     >     It would be nice to have some sort of floating
     navigation bar containing
      >     >     links to every section, rather than a TOC at the top.
     Failing that,
      >     >     section numbers and hyperlinks to the top or end (a la
      >     >
     https://cran.r-project.org/doc/manuals/r-release/R-exts.html
     <https://cran.r-project.org/doc/manuals/r-release/R-exts.html>
      >     <https://cran.r-project.org/doc/manuals/r-release/R-exts.ht

ml

     <https://cran.r-project.org/doc/manuals/r-release/R-exts.html>>
      >      >
       <https://cran.r-project.org/doc/manuals/r-release/R-exts.html
     <https://cran.r-project.org/doc/manuals/r-release/R-exts.html>
      >     <https://cran.r-project.org/doc/manuals/r-release/R-exts.ht

ml

     <https://cran.r-project.org/doc/manuals/r-release/R-exts.html>>>)
      >     would be
      >      >     useful.
      >      >
      >      >     Cheers,
      >      >
      >      >     Aaron
      >      >     _______________________________________________
      >      > Bioc-devel@r-project.org <mailto:Bioc-devel@r-project.org

     <mailto:Bioc-devel@r-project.org <mailto:Bioc-devel@r-project.org>>
      >     <mailto:Bioc-devel@r-project.org
     <mailto:Bioc-devel@r-project.org> <mailto:Bioc-devel@r-project.org
     <mailto:Bioc-devel@r-project.org>>>
      >     mailing list
      >      > https://stat.ethz.ch/mailman/listinfo/bioc-devel
     <https://stat.ethz.ch/mailman/listinfo/bioc-devel>
      >     <https://stat.ethz.ch/mailman/listinfo/bioc-devel
     <https://stat.ethz.ch/mailman/listinfo/bioc-devel>>
      >      >     <https://stat.ethz.ch/mailman/listinfo/bioc-devel
     <https://stat.ethz.ch/mailman/listinfo/bioc-devel>
      >     <https://stat.ethz.ch/mailman/listinfo/bioc-devel
     <https://stat.ethz.ch/mailman/listinfo/bioc-devel>>>
      >      >
      >      >
      >     _______________________________________________
      > Bioc-devel@r-project.org <mailto:Bioc-devel@r-project.org>
     <mailto:Bioc-devel@r-project.org <mailto:Bioc-devel@r-project.org>>
     mailing list
      > https://stat.ethz.ch/mailman/listinfo/bioc-devel
     <https://stat.ethz.ch/mailman/listinfo/bioc-devel>
      >     <https://stat.ethz.ch/mailman/listinfo/bioc-devel
     <https://stat.ethz.ch/mailman/listinfo/bioc-devel>>
      >
      >









        [[alternative HTML version deleted]]

_______________________________________________
Bioc-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/bioc-devel




This email message may contain legally privileged and/or...{{dropped:2}}

_______________________________________________
Bioc-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/bioc-devel

Reply via email to