livecomsjournal / article_templates Goto Github PK

The template was for "Computational Comparisons", and we had changed that section name. Proposed fixed from PR #76. The one thing I'm not sure if the title should read "A LiveCoMS Software Analysis" or "A LiveCoMS Software Analyses Paper". Thoughts? I'm leaning to the former (though it currently has the latter)

This is a to-do list spinning off of discussion in #16 ; it will be updated as we get more discussion there. Currently, I'm expecting we'll want to make at least these changes to the template:

Important:

• Setup checklists (perhaps a custom checklist environment) providing visually appealing checklist-like panels
• Date, DOI and version in the left column of the first page (see #10 )
• Add an official location for a link to the GitHub repo (below corresponding authors) have a note steering reader comments/feedback to GitHub repo; also do the same in a subsection at the end just before author contributions, to emphasize the importance of this.
• Broaden conflicts section to indicate how conflicts can be other than financial.
• Get rid of gutter after first page, probably going to two column for subsequent pages
• Provide a way to easily display nicely formatted fixed-width code blocks for programming code/pseudocode, rather like what GitHub provides as discussed here, kind of like:

x = 23
y = 37
for i in range(23): print x*y

Probably nice to have:

• Sans serif math fonts to go with the sans serif text

Very minor

• p6 of our sample PDF has differing spacing between the lines which seems odd and should probably be fixed.

And in a final stage:

• After all of the above are done, create templates for the other article types (as in #9 )
• Make custom changes for specific types of documents -- perhaps Best Practices documents should use more of the full width of the page for body text and checklists
• Organize each template as appropriate for the type of document; e.g. best practices documents may need to explicitly note scope, etc., as noted here.

@dwsideriusNIST

I apologize for the naming of this issue, but I couldn't resist opening Pandora's box.

During the "Upon Acceptance" stage, I entered the information required for the pubversion option. However, I noticed that there was not a parameter for the Issue number, i.e., \pubissue or \issuenum. I asked @mrshirts and he suggested that I post an issue on GitHub for @dwsideriusNIST. So that is what I am doing.

Perhaps we want to provide a draft template code of conduct for how people should be using the relevant GitHub repositories (commenting, etc.), see livecomsjournal/livecomsjournal.github.io#21 .

The current template puts the "blurb" containing the GitHub repo URL in a special left text box, which causes it to split awkwardly across multiple lines:

Instead, what if we eliminate the left-hand text and put this just under the Abstract?

I can open a PR if people like this style.

New issue, visible in main.pdf of dmzuckerman/Sampling-Uncertainty@35d18d5

Figure captions are right justified, when they should be full justified.

I suggest that the LaTeX class be modified to remove the section and subsection names in the header of each page. It's inconsistent and uses numbering that is not in the actual text.

Do we want to impose strict formatting of the URL / DOI in the bibliography? I'm finalizing the references for the sampling uncertainty paper and need to make a decision one way or the other.

Using the "url" tag in BibTeX creates a nice link. But I would highly recommend requiring the URL to be "https://dx.doi.org/10.XXXX/YYYYY" as opposed to the publisher's proprietary link (which will change).

Conversey, using the "doi" tag in BibTeX creates a doi entry in the reference, but it is not a hyperlink that actually works (for any of the PDF viewers I've tested it with).

"doi" seems to be a better choice from a citation / reference cataloging POV, but the link is useless. Using both seems duplicative.

Thoughts?

We need to enforce having the licensing terms for the article in the article itself. There could be some automatic choices (CC-BY is what we recommend), but also the government no copyright choice, that they can just check off. There will be a few exceptions, but that can just involve a field that can't be empty for now. Something along these lines for CC licenses (https://wiki.creativecommons.org/wiki/Marking_your_work_with_a_CC_license).

On the left below the GitHub notice seems like a good place.

This was a lingering issue in the Sampling-Uncertainty paper, but it's cropped up in the TransportChecklist paper too.

Basically, if there is a reference with editors, but no authors, the first editor's name should be bolded to be consistent with the rest of the references. E.G., see refs 20 and 50 in https://github.com/dmzuckerman/Sampling-Uncertainty/blob/c38f4fb567ba249fd479f4aed36e1a966b608ff7/main.pdf

I found how to bold the first editor's names, but then it bolded the editor name when there are authors as well (e.g., ref. 43 in the same PDF above).

It seems like it might make most sense to define the version in some \newcommand and have that automatically filled in in the title (and other places) with the right formatting. There is significant inconsistency in how the version is being included so far, so coming up with a consistent choice (such as "Best Practices Paper: v1")

Other thoughts on this?

Compiling the new template, I have two issues, that are probably resolvable for me, but might be problematic for new people by raising the barrier. Should we check with LianTze on this?

1. if attempting to compile with 'pdflatex', I get

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!
! Fatal fontspec error: "cannot-use-pdftex"
!
! The fontspec package requires either XeTeX or LuaTeX to function.
!
! You must change your typesetting engine to, e.g., "xelatex" or "lualatex"
! instead of plain "latex" or "pdflatex".
!
! See the fontspec documentation for further information.
!
! For immediate help type H .
!...............................................

Some people might not want to/be able to switch? Both programs seem to be installed in my LiveTeX distribution, though. We need to check on portability on this, though.

2. If I switch to 'xelatex', I get the error:

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!
! fontspec error: "font-not-found"
!
! The font "Latin Modern Mono" cannot be found.
!
! See the fontspec documentation for further information.
!
! For immediate help type H .
!...............................................

l.74 ...t[Scale=MatchLowercase]{Latin Modern Mono}

? H
|'''''''''''''''''''''''''''''''''''''''''''''''
| A font might not be found for many reasons.
| Check the spelling, where the font is installed etc. etc.
|
| When in doubt, ask someone for help!
|...............................................

When I switch to 'lualatex', it spends a while building a font database, then I got several errors of the form

! LaTeX Error: Command `\digamma' already defined.

See the LaTeX manual or LaTeX Companion for explanation.
Type H for immediate help.
...

l.259 ...mbol{\digamma} {\mathord}{AMSb}{"7A}

?

! LaTeX Error: Command `\backepsilon' already defined.

See the LaTeX manual or LaTeX Companion for explanation.
Type H for immediate help.
...

l.265 ...mbol{\backepsilon} {\mathrel}{AMSb}{"7F}

With a few more weird warnings scattered in.

Just a really neat repository for converting LaTeX docs into pretty impressive looking HTML pages.

Not entirely useful for this journal, but could be nice to keep in mind.

https://github.com/arxiv-vanity/engrafo
Could also generate HTML pages in addition to pdf.

Will the official version of a LiveCoMS paper have some branding and/or volume information in the header/footer/somewhere? Perhaps added by Scholastica? There should be some indication of how to cite the article.

This repository currently serves two slightly different purposes

1. It provides the LaTeX templates for livecoms articles and instructions on how to use them
2. It contains instructions on how to create your own github repository to accompany your article (explained in some subitems of "Getting started")

I have to admit that I totally overlooked point 2 when I downloaded the LaTeX templates, and browsing some of the git repositories associated with livecoms articles, the diversity of choices (README/no README, store PDFs / store TeX, use subfolders for versions/use git tags for versions/ ...) suggests to me that some standardization would be useful.

I would suggest to consider replacing the manual instructions for 2. by Github's "template repository" mechanism.
I.e. keep this repository for the Latex templates and documentation but provide another, minimalistic Github repository that already contains the README + .gitignore + some basic directory structure.
Starting a new repository from it can then be done with a few clicks.

Here is an example of how this could look like:
https://github.com/ltalirz/livecoms-template-repository

We should add a date display in the template so all PDFs are automatically dated, e.g.:

% For ongoing development use
\date{\today}
% For release versions use
%\date{ January 20, 2017 }

Currently, we don't get the desired format when a class option (such as bestpractices) is not specified (see #30 (comment) ) ; we either need to make sure it still formats properly in such cases OR require a document type class option be specified. I'd lean towards the latter.

@liantze - is one of these easier/better than the other? Are you able to help with this?

I love the eLife template that you're starting with.

Here are some suggestions that may make it better for our purposes:

• A nice custom checklist panel environment would make it a lot easier for authors to come up with something that is usable and has a consistent style. Perhaps the appendix box environment could be adapted for this purpose?
• For the Best Practices papers, it probably makes sense to use more of the page width for body text and checklists.
• I have a stylistic preference for sans serif math fonts to go along with the sans serif text.
• The date, version, and DOI should probably appear in the left column on the first page.
• The template can be restructured to give a better example of what we hope the Best Practices papers to look like:
  • The Abstract might have specific subsections that describe the intended audience, specific application domains, and scope of the document to make it easier for readers to find Best Practices of relevance to them.
  • An Introduction might follow the Abstract, clarifying the scope and highlighting some recent applications to give the readers a better idea of whether this is the document they want
  • The Checklist might come next
  • The Detailed Best Practices section that elaborates on the decisions recommended by the Checklist may come next
  • A Discussion at the end may highlight still-under-debate areas (though maybe we want a specific section for this?), as well as areas for improvement or things that would help focus areas the next revision can improve

@mrshirts - I think I volunteered to curate the GitHub side of things. Any thoughts on what I should be doing on here? Things that come to mind offhand are:

Basic repo:

• Make sure there are good README's explaining what this is about, linking to journal, etc.
• Make sure there are examples of using the template (the template itself provides one; we can add more later)

In a new "paper writing as code development" document:

• Likewise give some brief explanations of "paper-writing as code development" and why

In some instructional documents (here or somewhere else? Update: I like here for things which should get attached to their repo, which will be quite a few of these), deal with GitHub practicalities for authors:

• Explain how authors should set up their GitHub repo (protecting master, enabling issue tracker, etc.)
• Explain how to handle versioning and dates of changes
• Explain how to do a release
• Explain the branch-pull-merge/fork-pull-merge models
• Have them protect master
• Give LaTeX formatting tips for easier handling of revisions on GitHub (e.g. one sentence per line)
• Give concrete examples of specific scenarios and handling via GitHub

What else am I missing?

I've added several of the above in #1 (some PR, not that one).

Problem: if the GitHub URL for the permanent article repository is too long, then it runs into the text of the abstract.

Likely solution: We added
\RequirePackage[hyphens]{url}

before the document class definition. This breaks the URLS on hyphens. This could probably be put somewhere in template so authors don't need to worry about this.

We'd like to add a way to add translators to an article, as well as a link back to the original article for these translations. Would be ideal if there were templates where people just put the previous article information and the translator names, and it was all formatted correctly - translators added to author's list with a marking that they are translators, link to original repository properly formatted and printed (in abstract? Not sure where else).

Ideally, would be a class (or something similar) of the article, so the same template could be used for both article and translation of that article.

Still brainstorming this all ...

Using a large \begin{checklists}[p!]\end{checklists} directive, means that the page will overflow and some kind of manual tweaking is required. Any thoughts on how to do that?

I have attached an example of it not working based on the best practices template.

overflowing_checklists.pdf
overflowing_checklists.txt

Something goes wrong with the inclusion of the github repo name in the front matter, so that it extends into the abstract, using luauatex from TexLive 2015. The solution may simply to be not recommend lualatex, since most people don't use it anyway. This does not appear to be a problem with latex from TexLive 2016 or later.

New issue: if the \maketitle \begin{abstract}...\end{abstract} is not stated between \begin{frontmatter} and \end{frontmatter}, the entire document is rendered single column.

It's easy to spot and fix; question is whether there should be a warning or compilation error.

However, this should wait until we've nailed down the commonalities between all, so we don't have too many differences between .tex files that all require editing.

The current template (or, the current template with some people's LaTeX implementation) are doing something weird with some character combinations, especially lower case 'fi'. For example, if you look at;

https://github.com/dmzuckerman/Sampling-Uncertainty/blob/master/main.pdf

In Adobe Reader 11.0.23 on MacOS, and copy and paste the 1.2 section header "Key Definitions", then it show in text as "Key De1nitions" in plain text, and the word "definitions" isn't found using search. Same with the word "final", if the f is lower case. Although it appears fine visually. However, one reviewer said it looked like an accented a there in "Definitions" instead of 'fi'. We are tracing down what software they were using to view.

In Preview 10.0 on MacOS, there were no issues.

Any suggestions for this? Choice of font the issue? How it's compiled?

One more stylistic concern: the elife template uses a very wide left margin; I suspect this is to provide the "For correspondence", etc. text blocks on the first page. But on every other page, this is just wasted space. Can we modify the class file to use more of the page width for pages 2+?

The livecoms documentclass currently uses the natbib package for bibliography management which is ancient and no longer really developed.
In particular, natbib only supports the bibtex format, which has very limited support for citing things like web sites or software (which I guess is a common use case here) - they all end up as the @misc entry type.

Switching to biblatex would provide support for the biber backend (while still supporting bibtex as well). biber supports a much wider range of entry types, as well as UTF-8 inside the .bib file.

See e.g. this great summary on the topic.
Note that overleaf also recommends using biblatex.

Currently the recommendation the main README.md makes is to clone the repo rather than fork the repo in order to get started. @mrshirts , is this intended? I had thought that forking would be better because:

• Forking is explicitly designed for creating spinoff derivatives (what they are typically intending to do if they are writing a paper, presumably)
• Cloning means they are making a local copy of this repo as a starting point for their paper, which seems perhaps odd to me if we are intending they start their own paper
• If they fork, we can track who forked it; if they clone, we can't

Not sure. Looks inconsistent, maybe overkill, but thoughts?

References should be numbered by order of appearance in text, e.g. not as in https://github.com/dmzuckerman/Sampling-Uncertainty/blob/4bf625d64a533da9e20aab0ddb625e711c2e56d3/main.pdf

1. Sometimes, the link to the GitHub repository in the PDF isn't working. See https://www.livecomsjournal.org/article/5965-introduction-to-markov-state-modeling-with-the-pyemma-software-article-v1-0
2. Figure out ORCID iD placement.

Currently, the citation format is the (FirstAuthorSurname (Year)) format. This 1) adds bloat to the articles and 2) unnecessarily complicates cross-referencing the in-text citation to its associated entry in the bibliography.

I suggest that the citation format be altered to the physics-style numbered format, e.g., "For example, Leach’s Molecular Modelling [2] ..." instead of "For example, Leach’s Molecular Modelling (Leach(2001)) ..."

For example, something like like Overleaf or other editors. Plus other stuff.

Would make it easier for the reviewer? Is there an option that can be switched for the templates.

Have the template include an explicit place to list author contributions. For example, see the contribution sections on this Nature Chemical Biology article (http://www.nature.com/nchembio/journal/v9/n5/abs/nchembio.1212.html#author-information) .

Let's create a wish-list for modernizing the bibliography style for LiveCoMS

1. Add 'Accessed on _' note to electronic content, including software repositories
2. Evaluate biber/biblatex as a replacement for BibTeX. First step should be to identify a biblatex style that gets us close to the current bibliography format. [@dwsideriusNIST: have to learn how to write a style for biber.]
3. Allow URLs to break at hyphenation. This can be handled with BibTex by adding the following line to an article preamble

\usepackage{url}
\def\UrlBreaks{\do\/\do-}

Solution may be different for biber/biblatex

New formatting issue: long section and subsection titles intrude into the gutter between columns and the right margin. For example, see page 7 of https://github.com/dmzuckerman/Sampling-Uncertainty/blob/4bf625d64a533da9e20aab0ddb625e711c2e56d3/main.pdf

As soon as we have examples using the templates (beyond just the simple example the template itself provides) we should link to them in the md files here.

I wonder if we should reorganize this a bit into something which authors can just fork in order to immediately start their GitHub repos. Probably that was the intention and it didn't dawn on me until now. For some reason I had in my head the main thing they'd be getting was the LaTeX stuff.

I think if we were going to reorganize that way, we would make sure to have NO information here about how to do things (e.g. the README.md content relating to the issue tracker, etc.) and just provide templates they should update for everything:

• Template LaTeX
• Template README.md for their article, including info on what this publication model is, etc.
• Template "instructions for readers/commenters" md file for them to edit which has boilerplate text on how readers can raise issues, etc.

Anything else?

See the following for how we are supposed to include DOI's in article information; this should be reflected in the article templates (potentially in the web site as well).
https://www.crossref.org/display-guidelines/

An issue specifically dealing with the document at https://github.com/davesmith4398/best_practice_membranes

"Eliminating white space: we have experienced a lot of difficulty “taming” the tables in our document (in both tabular and longtable formats). Given that the article is two-column format, allowing the tables to span both columns was a challenge in and of itself. The current problem, as you note, is with this white space. We have tried to prevent page breaking, for example, but we are stuck on how to formally address this. We currently have “hacked” the problem a bit by rearranging some of the text before and after the tables. If you or any of the other LiveCoMS people or LaTeX people you know in general know how to solve this, I would greatly appreciate your help.?