New editing process

[rougier]

Dear @ReScience/editors , @ReScience/reviewers

Both the submission and the publication process has been proved to be quite painful and we may need to rethink the whole submission/publication process. This repository proposed a new latex template (no more pandoc since it lead to many problems) for ReScience articles. The idea is to use the metadata.yaml file to generate all the relevant information but this is not yet done. This will serve to generate the .xml (DOI), .md (for website entry) and .tex (for finished article).

My question so far is whether you like the new template and can you compile it without too much trouble? If you want to test:

pdflatex article
biber article
pdflatex article
pdflatex article

[cJarvers]

I just tried compiling the article (using the commands you posted) and it worked without problems.
Visually, I think the pdf output looks quite nice and I think the split into different tex files such that the authors only need to touch the article-content.tex is also good.
I typically use texstudio with bibtex, not biber, and tried that too just now. As expected, the bibliography is gone but otherwise it worked. I guess if I fiddle with the compilation settings a bit I should be able to make it use biber too.

[ThomasA]

The article compiles fine here with Texlive 2016. I like the template; for example the fact that important metadata is easily readable at the bottom of the front page and the DOI is featured in the page footer.
I think it is a good choice to use Biblatex and Biber for references. IMO BibTeX itself has been irrelevant for close to 10 years for anything but its file format.
latexmk also compiles the article without any trouble:

latexmk -pdf article

I am one of those who had a problem with Pandoc before, because it was unable to find a necessary font for the old template on my system.

[ThomasA]

How is .md output going to be produced from article.tex?

[rougier]

@cJarvers @ThomasA Thanks for the tests.
@ThomasA I need to write the python parser for the .yaml in order to produce the different files (including the .md for the website). It is relatively easy but producing the .xml (for crossref) might be a bit harder (see here)

[ThomasA]

@rougier since I suppose LaTeX -> Markdown (for web page) is not something everybody needs to be able to do, would it not be straight-forward to use Pandoc for that part?

[rougier]

The website is using Jekyll and we only need to generate a post for each new entry using information from the yaml data. It should be (more or less) straightforward. I think the website also need some change in order to display the abstract as well as the relevant information.

[ThomasA]

I have just tested the compilation using Texlive 2018. This, among other things, contains a newer version of Biblatex: 3.11. The new Biblatex seems to have a problem with 'biblatex-dm.cfg'. I get the following error when trying to compile:

(./biblatex-dm.cfg)
! Parameters must be numbered consecutively.
<to be read again> 
                   1
l.6132 \def\do#1
                {%

[MehdiKhamassi]

Hello,

Thanks a lot for setting up a new template. It looks great!

I am on Mac OS X. I compiled the article both with the pdflatex/biber commands in a terminal and with TeXShop. In both cases, there was the following error:

! Package xkeyval Error: giveninits' undefined in families blx@opt@pre'.

See the xkeyval package documentation for explanation.
Type H for immediate help.
...

l.10997 \blx@processoptions

?

Nevertheless, after pressing enter, the compilation still completed and generated the pdf file.

In TexShop, I could compile the article. Nevertheless, if I try to compile the references with BibTex which is by default integrated in TexShop, then I get the following errors:

This is BibTeX, Version 0.99d (TeX Live 2015)
The top-level auxiliary file: article.aux
I found no \citation commands---while reading file article.aux
I found no \bibdata command---while reading file article.aux
I found no \bibstyle command---while reading file article.aux
(There were 3 error messages)

Finally, an unrelated question: what are Figures 3 and 4?

Best wishes

[rougier]

@ThomasA Ouch, I've no idea what it that problem. The biblatex-dm.cfg is for having clickable bib entry (instead of just the DOI). I'll need to install TexLive 2018 to test it.

@MehdiKhamassi You need to tell TexShop to use biber instead of bibtex (I imagien you should have an option somewhere). For the first error, you might need to update your texshop installation (but not so sure, do not update if this breaks everything else on your system...)

[rougier]

@MehdiKhamassi Figures 3 & 4 are totally unrelated (they're are from another paper, not sure how they ended here)

[benureau]

I think that indeed a latex template will simplify a lot of things for authors and editors. Thanks for taking the time to do that. I really like the ID badges after the authors/editors/reviewers names. Everything compiles fine for me. Adding a Makefile to automate the four commands may be judicious.

Concerning the design, generally, I preferred the first one. For many comments below, it's just a matter of my personal taste, feel free to dismiss them. I feel a bit out of step since everybody seems to like the new layout. Still:

• The information "A reference implementation of" is gone. That's disastrous. I could dig into the author's text, the title is probably in the abstract, but then I'll have to look in the reference to get the exact details and an actual link. A core information relegated to the last pages of the article.
• The motto "Reproducible Science is Good, Replicated Science is Better", I feel, is a bit too much (it feels a bit arrogant here, prominent, front and center, on the top of the article, in the place of honor usually reserved for the title. In my opinion, we should put our authors, not the journal, first.). Similarly, in the footer, "An Open Access Journal" feels slightly strange as the subtext of a url. "An" rings like "Among many others", but it might just be me. I feel that "Open Access" would be equally good, but probably elsewhere?
• The new font. It feels "funky". The small pointy flourishes on the top-left and bottom-left "R" of Rescience make it seems... like it's jiggling? dancing? Anyway, it does not feel serious. The kerning is very wide, leaving the letter of the text a bit dislocated from their neighbors in the title. Beside, when zoomed to actual size, it shows inconsistencies on my screen (UHD, under Preview, macOS). The "l" of Nicolas will have large space around it, but the "a" and "s" will be almost touching. Generally speaking, I feel the previous font was much better.
• I kinda like the black/red contrast in the ReScience text. Now the camel case feels just "geeky" and inelegant.
• We have a fantastic round logo. The red rectangle is pretty much destroying its circularity.
• It seems that we are abandoning the red theme: the links are blue now. I would advocate to go full red instead, including links and references.
• So, the margin in the previous template was great for the first page (it also made the article have a quite distinct look), but then awkward for the following pages. However, with the new footer, while the information is there, it's more difficult to get at a glance. In the previous template, the date for instance was instantaneously accessible, both on the side and in the right footer. Now, sandwiched between the editor/reviewers and the copyright notice (do we really really need that?), you have to squint a bit to get it.
• The four corner header/footer combo on every page trap the text in some hellish pentagram (with the addition of the page number). At least liberate a corner as previously (does anybody actually need the volume/issue information on all pages? We could remove it or compact it with Rescience such as "Rescience 1(1)"). The blank top-right was wonderful, and was helped by the free-floating logo on the top-left. More generally, I would find a way to remove any header.
• The footer on the first page is quite big. Everything is spelled out. Any way to remove ("Cite as:", "Copyright") or simplify (compact form of the license) anything ?

[khinsen]

Thanks @rougier for preparing this template! It looks nice, no complaints about the result. However, I get the same compilation error as @MehdiKhamassi, using TeXLive 2016 under macOS. No TeXShop in my case, just the command line tools.

I won't try to update my TeX installation before finishing two paper revisions I am working on. Too many bad memories from past TeX updates.

[rougier]

@benureau Thanks for all the comments. I'll try to upgrade the style.

For the fonts, I chose Libertine and Biolinum but I'm not really satisfied either with the Biolinum one. Other choices are available from http://www.tug.dk/FontCatalogue/sansseriffonts.html

[rougier]

Just made some light modifications.

[ha0ye]

Is the template on Overleaf yet? Getting it to work there would solve a lot of issues for individuals dealing with myriad Tex packages.

[rougier]

Good point. I think it might be compatible with overleaf but I did not try yet.

[otizonaizit]

A question: with the DOI I think there is a bit of a chicken-and-egg problem. To get the DOI from zenodo, we need to publish an archive with the PDF inside. At that point we get the DOI, so the DOI is still not available when we generate the PDF. Once we have the DOI, if we update the PDF, we would get a new DOI, right? That is the reason why the DOI is not present in the current PDFs we publish, right?

[ha0ye]

@otizonaizit You can use the top-level concept DOI on Zenodo to represent all versions of a record:
http://blog.zenodo.org/2017/05/30/doi-versioning-launched/

[rougier]

Also, you can reserve a DOI when you submit on Zenodo (pre-register) such that you know the DOI in advance.

[oliviaguest]

Is there any way we could use something like @whedon, e.g., openjournals/jose-reviews#11?

[trallard]

I like @oliviaguest 's suggestion. If this were something you'd like to implement I would be happy to help with it

[khinsen]

@oliviaguest @trallard From a quick glance at a few reviewing threads there, that bot looks useful indeed. Does anyone have an idea of the effort involved for implementing and maintaining it?

[trallard]

@khinsen I have implemented similar bots in the past so working around work commitments it would take me around a couple of weeks to get one set up and then we would need to run some test submissions to identify any existing bugs before opening this up for open regular submissions.

Maintenance-wise it does not tend to be much of a burden just the occasional dependencies update, unexpected bugs and similar things. I will, of course, make sure everything is well tested and documented to make it easier to debug and maintain in the long-term.

[oliviaguest]

Also I assume @labarba knows more?

[labarba]

All the code for the Open Journals is open source: https://github.com/openjournals

[labarba]

You might be interested in the Editorial Guide I wrote for JOSE:
https://github.com/labarba/jose/blob/master/EditorsGuide.md

[oliviaguest]

@labarba Nice! I see @whedon's code is all there too of course. 👍

[otizonaizit]

@oliviaguest @trallard : speaking with my editor's hat on, I am not sure @whedon would solve our most painful issues.
In my experience, most of the problems arise in 1) fix pandoc issues, 2) copy and pasting things around between the paper repo, zenodo, the ReScience repos, etc..., 3) uploading the right thing to zenodo and manually copying there the metadata.

1. I think one of the reasons to move to latex is to be able to offload the compilation (and fixing the issues thereof) to the authors. We can't reasonably ask the authors to fix pandoc compilation issues, because the pandoc platform is so unstable that sometimes it is indeed not possible to get the right paper layout with a different version than the one originally used by @rougier [I am talking by experience here].
2. Another thing we need is reducing the duplication of metadata about the paper. Right now the metadata is found in three/four different places and needs to be copied and synchronized manually.
3. The paper and its metadata should be uploaded automatically to zenodo: every time I am copying and pasting things around I have off-by-one-character errors, pasting things in the wrong zenodo fields, etc...

After a cursory look at @whedon I am not sure that moving to that platform would address the above issues. OTOH I am totally incompetent in Ruby, so I may have missed the meat of the package ;)

[oliviaguest]

I am not an expert as to what @whedon gets done but I agree 100% with your points @otizonaizit. It's extremely frustrating (given I am aware automation is possible) to be copy-pasting stuff to update, e.g., http://rescience.github.io/read/.

[labarba]

I pushed an Editor-in-Chief guide, so you can now see what else we do with whedon on the command line, after a paper is accepted:
https://github.com/labarba/jose/blob/master/OJ_EiCguide.md

[khinsen]

@otizonaizit I agree with what you say - improving our source-code-to-PDF workflow is a separate and certainly more important issue. But that shouldn't stop us from considering other improvements.

[rougier]

I think I somehow fixed the automation part (including Zenodo upload) but it might still be rough on the edges. Using whedon could be an option but I've followed @labarba effort to adapt it for JOSE and it appeared to be not totally straighforward. But maybe @labarba efforts for JOSE could help for a smooth transition for us.

The other point I would like to fix is the pull request / import thing that is also quite painful for authors and editors. Maybe it would be simpler to let author develop code the way they want and we would only fork the repo once published (and request a mandatory DOI for the code, at least until we get a hash from the software heritage).

I intend to post a draft proposal for the new submission/review/editing process by next week hopefully but if someone has already some ideas or want to start...

Also (and ideally), we would need some kind of a configurable & automatic reminder mechanism. I'm always lurking around to check reviews are not too late but it is a bit time consuming...

[labarba]

The delay with getting JOSE started was for paying the technical debt in the JOSS web application and whedon bot. (There were places where the journal name was hard-coded, for example.) Now, all the infrastructure of The Open Journals is cleaned up to be usable by new journals.

The submission process in JOSS/JOSE is via the web app. See: https://peerj.com/articles/cs-147/#fig-1

The authors archive their software or other artifacts themselves, using Zenodo for example, and give us the DOI of that archive, which is entered into the metadata of the JOSS/JOSE paper.

[trallard]

Fair point @otizonaizit. I think what the original suggestion from @oliviaguest (and feel free to correct me if I am misinterpreting here) was to use/develop something similar to whedon to automate some of the repetitive tasks rather than doing a direct port or use whedon as is.

This way we could create a bot that would lift off some of the burdens from the rescience editors by automating the parts of the submission/review/editing processes that can be automated. I think that since a new review process is being drafted/devised soon (as per @rougier comment) it would be worth exploring this venue.