HTML manuscript display enhancements for Q1 2019

[dhimmel]

The Greene Lab welcomes @vincerubinetti on-board as a frontend developer starting in January 2019. Part of @vincerubinetti's role will be contributing to Manubot, along with @dongbohu. Since I'll be traveling for parts of January, I wanted to jot down some initial tasks which can be started in my absence.

Primarily, it'd be great to improve the HTML display used by Manubot. A quick rundown: Manubot uses Pandoc to generate the HTML Manuscript. The styling of the HTML is controlled by github-pandoc.css, which we took from here and modified slightly over time as issues arose. I am guessing there is large room for improvement.

Here is the current frontend, on the Meta Review manuscript which has a variety of types of content, like figures, tables, and citations:

• webpage
• gh-pages source

Here are several enhancements that we can consider for the first quarter of 2019:

• Fix superscript appearance issues described at Table summarizing writing alternatives greenelab/meta-review#88 (comment)
• update github-pandoc.css to follow current best practices and consider whether we should migrate to an entirely different solution such as a JATS viewer Look into JATS frontends & the Manuscript Exchange Common Approach #139.
• assess feasibility of page numbers in the WeasyPrint PDF export Page numbers in the print / PDF output #104
• add tooltip for citations to show full reference info (and possibly highlight other occurrences of the reference). Also consider whether to add show context to items in the bibliography as per Show context for references #118.
• will keep editing this comment to add to this list

@vincerubinetti no pressure to think about any of this until you start, just I wanted to make sure you aren't blocked by me when you do start! Happy New Year everyone.

[slochower]

This is great. Happy to provide feedback or review things as requested.

[agitter]

From an overall design standpoint, will these changes only affect the HTML outputs and leave the PDF untouched? Currently pandoc uses github-pandoc.css for both HTML and PDF conversion, right? Will there be separate CSS for HTML and PDF manuscripts as these changes are implemented?

[dhimmel]

I was hoping we could continue to use the same CSS for the web view and the PDF that gets exported from it.

[agitter]

@dhimmel I would like to do that as well for the overall aesthetics, but what about the dynamic elements like tooltips and scroll bars in the HTML version? Will those have to be separated somehow?

[dhimmel]

what about the dynamic elements like tooltips and scroll bars in the HTML version? Will those have to be separated somehow?

Perhaps @vincerubinetti can comment, but essentially the PDF is generated as a "printed" version of the webpage using weasyprint. The CSS @page rules allow specifying the style just for the printed version. I imagine tooltips are not a problem as they just won't appear in the printed format?

[vincerubinetti]

@agitter If I understand you correctly, yes @dhimmel is right. I've already made it (PR #157) such that the tables will overflow with a scroll bar on a screen (@media only screen) but will squash to the correct width for print (@media print), as is normal behavior for tables. If we want to have more complex behavior like breaking columns to the next page for super wide tables, I believe that is a bit more complex and will have to be looked into.

Also, yes the tooltips aren't visible when printing. They're actually not in the document at all until you hover over a citation link.

[vincerubinetti]

I think we can probably close this, since these improvements and issues are naturally being broken down into other issues by myself and @dhimmel.