Added class option to include journal publication information in arti…

[dwsideriusNIST]

Added class option to include journal publication information in article footer. Sample documents updated to include parameter definitions and instructions regarding pubversion class option.

Since we're not 100% certain of the DOI format yet, I made this generic; the DOI is not auto-generated and could be entirely independent of the article number.

May need to write some instructions for authors regarding the "pubversion" class option that triggers the footer.

[davidlmobley]

Excellent, @dwsideriusNIST . Yes, definitely need some instructions...

[davidlmobley]

(Can merge this, or could bring in instructions at the same time. Preferences?)

[dwsideriusNIST]

I placed some instructions in the sample TeX files, perhaps we add a short section to https://github.com/livecomsjournal/article_templates/blob/master/information_for_authors.md ? I was initially reluctant to do so, as that file is not about the nitty-gritty of LaTeX. Opinion/advice is kindly received.

[mrshirts]

There's two choices; we do the fix ourselves to add date, version, issue, or they do it.

One thought; we might not assign an issue or number in the issue until after it's published. We might want the options of having some intermediate marker (ASAP?) until the release is triggered. Which would be a giant pain for 5-10 papers, just updating the numbering. Or, after an issue is released, we start numbering with the next issue, but say that issue N is released when all of the articles from N are published (we just essentially do a press release . . . )

[dwsideriusNIST]

@mrshirts:

1. There probably should be an "ASAP" or "Accepted" descriptor before the issue/article number is available. I am in favor of minimal granularity, so max of three categories: "Just Accepted", "ASAP" (meaning in final form but without issue and/or number), and "In Print."

2. There should probably be a date field to indicate when the reviewed version (should be vX.0, right?) was in final form. In a sense, the publication date of the reviewed version. It can be another line in the footer, very easy to add.

[davidlmobley]

@mrshirts

There's two choices; we do the fix ourselves to add date, version, issue, or they do it.

I'm ambivalent as to which; preferences?

@dwsideriusNIST - what would be the differnece between "just accepted" and "ASAP"? It seems to me we could just do this: 1) As soon as accepted, get them (or us) to make a final publication-ready version 2) Post that in advance of the issue Then once we are ready to release an "issue" we: 3) Change the numbering on it to indicate what issue it is in and re-post

I don't think it would necessarily be a big pain to update the numbers; it'd just be adding the issue number on all of the papers, or am I missing something, @mrshirts ?

[mrshirts]

If there was a release-tagged version of the paper when it was accepted, then we could go in and just add the issue, and have them generate the .pdf. Then they would have to mail it to the journal, and we could post it. So, doable for now, but kind of a pain.

[davidlmobley]

Slightly painful, but seems tolerable perhaps.

I did hear of the Journal fo Open Source Software which basically does everything we are trying to do (including, I believe, automatic releases from GitHub being published) except only for software. It's possible longer-term we could shift to use their infrastructure, as I think it basically does everything we want in a more automated way, or at least that was my superficial understanding.

[mrshirts]

We are planning a submission there soon, so I will investigate. https://joss.theoj.org/. I worry there might be too many differences in how they want to do things, but we could at least learn from them.

[dwsideriusNIST]

@davidlmobley My definitions were: "Just Accepted" : the version accepted by the editors, but without any post-processing. "As is" "ASAP" : in final form, but without an issue number or other metadata that can't be known until the issue is assembled

That distinction may be less relevant for this journal since most of the formatting responsibility is on the authors.

[dwsideriusNIST]

@davidlmobley and @mrshirts Can we re-start this discussion? There are two interacting issues here: 1) information to include in the footer of the paper and 2) the procedure for entering that information into the LaTeX source.

I propose that we finalize the footer information first. That will help determine which macros/functions need to be in the class file.

Currently, the footer is set up (when "pubversion" is in the class options list) to print:

-------------hrule---------------- DOI: {\it Living J. Comp. Mol. Sci.} , <volume/issue identifier>, <"page"/article number> Page X of YY

The previous discussion indicates that we would like to annotate the article to state if it is "just accepted" or "ASAP" or "in final form" (or maybe the published form, since revisions are allowed post-publication) or some variation on that theme. Cribbing from ACS, we could include relevant dates such as received/revised/in final form/date of peer review. So, what do we really want? An annotation like ASAP, etc., or a list of dates?

[davidlmobley]

I like the info you have in the footer. Obviously minor additions are needed:

I am still not convinced we need a distinction between "just accepted" and "in final form"/"ASAP" and then with metadata (the first two seem like they could be the same, to me), but this issue does not seem crucial. Also, including relevant dates sounds like a good idea, though less important than ACS since all of that is available on GitHub. I'd be inclined to propose we only list the date of the PDF, but I'd also be OK with listing the date(s) received and possibly accepted if you want to advocate for that.

So I think that leads me to conlcude we want:

• The info you already have
• A description of "ASAP" or "in final form" or similar
• Key date/date(s)

Does that sound reasonable? THoughts @mrshirts ? @dmzuckerman ?

[dmzuckerman]

Since authors are doing their own editing, I think 'accepted' and 'final' become the same thing. @mrshirts ?

I think we'd better list both received and accepted dates. Despite our total reliance on github, our authors may be seeking tenure or some other weird status (Nobel prize for lessons learned?) where dates on the paper will matter. We have promised 'academic credit' for previously unheralded types of work, so we should deliver the full package.

[mrshirts]

I think 'accepted' and 'final' become the same thing. @mrshirts ?

Up to some formatting cleanup, yes.

I think we'd better list both received and accepted dates.

Agreed.

[dwsideriusNIST]

OK, I'm going to work on a set of class functions that put the received and accepted dates somewhere on the first page. I'll likely reproduce something like the ACS / JPC:x style.

This will all require a small amount of documentation in the template guide. Due to the non-traditional nature of the journal (by that I mean the option to revise post-review), we should also clearly define what "received" and "accepted" mean for LiveCoMS. Just to be clear, I would define them as:

Received: Date of submission to LiveCoMS Accepted: Date (following review) when the reviewed version was accepted by the editors.

There is still the "This version dated <---->" blurb on the front page, which is created by the class file using the date that the PDF was compiled. Or perhaps we need to revisit that aspect of the LaTeX class, as the PDF will have to be compiled post-acceptance, making that date always more recent than the Accepted date. Thoughts?

[dwsideriusNIST]

OK, here are some ideas: main.pdf

1: On the first page, in the left footer are the received and accepted dates. These rely on a few parameter declarations in the source LaTeX file.

2: The footer is getting a bit busy - do you prefer the page "1 of 23" to be in the right footer (current LiveCoMS style) or centered (like ACS)? Obviously it shouldn't be centered and in the right footer, I just wanted to show them simultaneously.

[dwsideriusNIST]

I'm closing this PR so that the BibTeX style can be updated in a different PR, then we'll settle on the footers for the article template.

[davidlmobley]

@dwsideriusNIST - I think centered, not right footer, would be best. Otherwise I like it.

There is still the "This version dated <---->" blurb on the front page, which is created by the class file using the date that the PDF was compiled. Or perhaps we need to revisit that aspect of the LaTeX class, as the PDF will have to be compiled post-acceptance, making that date always more recent than the Accepted date. Thoughts?

Hmm, good point. I'm inclined to think this "version dated" should NOT be auto-added on compiling the PDF but basically the date the authors last changed anything. Other thoughts?

[dwsideriusNIST]

I wonder if there's a way to get that date from the last entry in the Git log. For now, though, I'm going to start a new PR with the updated footer and, possibly, instructions for entering the article ID, etc. Stay tuned.

[davidlmobley]

That would be cool.

[dwsideriusNIST]

OK, PR #58 addresses the footer information in the document, leaving the "This version dated...." issue unaddressed.

A few stack overflow searches came up with ways to supply the git log information to the document, but they're NOT user friendly. Often requires a command-line directive during the latex compilation, which I think we should avoid. So, no proper answer yet.

[dwsideriusNIST]

Here are some options for getting the Git log into the LaTeX document automatically:

1. Use either gitinfo or gitinfo2 (packages available in TeXLive); these rely on a post-commit hook in the git configuration that creates a metadata file for LaTeX to interpret. Upside: simple integration, transparent use, platform-independent. Downside: Authors have to create the necessary hook; we would have to include directions in the author checklist that involves adding a file to the .git/hooks directory. Additional downside: the .git directory is not version-controlled, so extra git magic is required for the hook to propagate to clones/forks.

2. Use some variation of \immediate\write18{git status > git.tex}\include{git.tex} to pipe command-line output to a text file. Upside: no packages required. Downside: POSIX-specific implementation, plus the compiler has to be run with a --shell-escape or --enable-write18 directive.

I cannot recommend either option as a workable solution for LiveCoMS. Both require manual user-level interactions with LaTeX and/or git that are not conducive to generation of consistently-styled PDFs for the journal.

Does anyone else have any other methods for automatically placing Git information in a LaTeX document?

[dmzuckerman]

@dwsideriusNIST thanks a lot for investigating. I'm sorry but all this is beyond my expertise.

[davidlmobley]

I don't, @dwsideriusNIST - BUT, since my last experiment was such a success, let me ask Twitter. :)

[HaoZeke]

Is it such a good idea to include the git log? That would require additional guidelines for commits which the authors should adhere to, at the very least in the form of:

file: Change description

Additionally if any code is included then --shell-escape is required as well (for minted).

Of course for just obtaining dates there is no need for the above commit guidelines.

In any case the example repos being cloned should not have to depend on the user's knowledge of TeX or anything else. An appropriate build system (make or tup or gulp) ought to make up the user interface.

Of the three the most OS independent (apart from a go binary which might be overkill) is actually gulp even though it's slightly slower.

In general gitinfo2 is better, and a build task can easily set up the necessary hooks.

[dwsideriusNIST]

@HaoZeke My intention wasn't to put a lot of git metadata in the document, just either 1) the last commit date or 2) an indicator that the current compiled PDF is dirty compared to the commit log.

A makefile would be my solution also (I actually use makefiles to do a lot of TeX / git / BibTeX operations), but that is still not platform independent. Despite the pain of saying this, I don't want to lock out a Windows/something else (Overleaf? ShareLaTeX?) user from straightforward document formatting for the journal.

[HaoZeke]

@dwsideriusNIST ah yes, I also noticed that late and modified the comment...

yarn with gulp and shx is actually very cross platform.... I've tested it for windows, *nix and MacOS as well, for example to run this pure js platform independent document generator and this tup based tool which has CI support and uses shx to run on multiple OSs'.

However, Overleaf and ShareLaTeX will be a major stumbling block as I believe they only support a small subset of the git features. However we can still provide for those fringe cases by having CI like Semaphore or Travis or wercker build the final pdfs on each push.

That way we can have a standardized build system throughout, controlled by the CI running a custom docker image, like this one.

[davidlmobley]

Twitter agrees that one either needs to use a build system or a script to get a date from git into an article, e.g. see https://twitter.com/the_mabraham/status/1015477503660576769