| Age | Commit message (Collapse) | Author | Lines |
|---|
|
This is the version of the project that will be published in Computing in
Science and Engineering (CiSE), Volume 23, Issue 3, Pages 82--91.
|
|
After going through Boud's corrections and edits in the previous commit, I
thought some minor clarifications would be necessary, and they are
implemented in this commit.
Also, in preparation for submission to the journal, the top-level software
heritage ID has been corrected to the latest commit on Software Heritage.
|
|
This commit makes several copyediting changes to the appendices and to the
supplement.tex introduction to the appendices.
The ArXiv unofficially increased upload limit of 50 Mb comes from a tweet:
https://nitter.fdn.fr/arxiv/status/1286381643893268483 (archive:
https://archive.today/PdxhT) but not listed on official ArXiv pages. So it
seems safer not to quote a value. The very old value was 0.5 Mb - out of
respect to people with low bandwidth, especially scientists in poor
countries. Tweets are generally not acceptable as "reliable sources" in
en.Wikipedia.
|
|
David made suggested some minor edits that are now implemented (most
importantly that he would not like to be associated with an ORCID ID).
I also "saved" a new Zenodo DOI for the final submission of this paper to
Zenodo, but "after" obtaining the page number information and other minor
things.
|
|
Until now the appendix only touched upon the archival aspects of scholarly
research producs (data, code, narrative). To help in clarity, the context
of this section has been improved, giving more explanations and examples.
|
|
After Boud posted a notice about Maneage in an online forum [1], Rémi
Rampin and Vicky Rampin (from the ReproZip project) replied with some notes
about our review of ReproZip in Appendix B. We are very grateful to both
Rémi and Vicky for looking into it and for their comments, their
contribution has been gratefully acknowledged with this commit.
The relevant comments are listed below and have been addressed in this
commit (see the 'diff' of this commit).
- [Rémi Rampin] ReproZip can capture the build step if you want it to,
it's just another command. So if you want to trace "make" and "pip
install" etc before tracing your actual experiment, you will have all
that build information.
- [Rémi Rampin] Bundle size is easily fixed by not putting terabyte-sized
data in the bundle, which is done by editing a simple configuration
file.
- [Vicky Rampin] Not all the files in the bundle are compiled/binary files
[in relation to the old sentence "ReproZip just copies the
binary/compiled files used in a project"].
[1] https://framapiaf.org/@boud/106296894758145705
|
|
This commit contains minor fixes in Appendix B.
ReproZip: As Vicky Rampin points out [1], ReproZip typically also
includes non-binary files, so I removed "just" and improved
the wording.
Popper: the Popper URL that we gave is obsolete; at Wayback
Machine it redirects to getpopper.io [2], so I've updated this;
and I've fixed up the wording ('off of' only exists in US
English).
[1] https://octodon.social/@VickyRampin/106298214313216228
[2] https://web.archive.org/web/20210425223605/http://falsifiable.us/
|
|
|
|
This commit adds a few extremely brief and incomplete paragraphs
on archiving, including URLs, as what is now subsection D of
Appendix A.
|
|
A few days, CiSE gave us a proof of the edited text and formatted
PDF. After comparing the edited text with our text, I noticed some minor
editorial issues that have been corrected in this commit. The parts that
were wrong (or could be improved in the proof) have been listed and will be
submitted to the journal.
In particular, following the recommendation from the editor, the
biographies were extended with a full listing of each author's affiliation,
I also added our ORCID IDs in the biographies.
|
|
The most basic way to resolve a Software Heritage identifier (SWHID) is to
prefix it with 'https://archive.softwareheritage.org'. However, Roberto Di
Cosmo informed me that SWHIDs are also resolved by 'n2t.net' and
'identifiers.org'.
With this commit, on the first occurance of an SWHID, I added some
explanation of how to resolve it by adding 'http://n2t.org' (since it was
the shorter option).
Some further minor edits were made:
- In the manuscript submission information, instead of "published on
IEEE", I wrote "first published online". The journal name is available
on the top of every page and doesn't include "IEEE", so this hopefully
avoids some confusion for people who don't know CiSE is published by
IEEE.
- The URL with the link to Ubuntu images was moved to footnotes to help
the readablity and better type-setting of the paragraph. A minor edit
was then made in that paragraph to shrink the paragraph by two words
that had occupied a whole line in its end.
- The first comment line in the second listing (Git commands to start a
new branch from Maneage) was slightly edited to avoid the term 'main'
(which could be confused with the branch name after 'git checkout -b
main').
- In the acknowledgements, the paragraph on Maneage commit/branch
information was moved at the top so the people and institutions are
acknowledged immediately after each other.
- Some minor edits were made in the Spanish acknowledgements to fit with
new project names.
|
|
Until now, the SWHIDs were not accessible in the print version of the
paper, they were only hidden as hyper-links within the PDF for readers to
click on. This is not a robust way to use the fruits of Software Heritage
and was kindly highlighted by Roberto Di Cosmo (principle investigator of
Software Heritage) after a first look at the paper.
With this commit, following the recommendation of Roberto, all the URLs are
corrected to print the raw SWHID as a footnote (for example
'swh:1:dir:...', for directories, or 'swh:1:cnt:...', for
contents/files). The click-able link of the SWHID also contains the context
(for example "origin" and etc).
In the process I noticed that the paper submission/acceptance info was not
filled and was also a footnote (which would not be seen if not cited). So
this information (received, accepted and published on IEEE) is now taken
just under the author list on the first page heading.
|
|
The DOI of the paper has been minted by IEEE, so as a step to finalize this
paper, it has been added to the REAMEME.md and the header of all PDF
pages. Along with the DOI in the header, the arXiv and Zenodo links are
also added to the header (they are small, and won't bother the reading).
|
|
Some minor conflicts (all expected from the commit messages in the Maneage
branch) occurred but were easily fixed.
|
|
The email notice of the final acceptance of this paper in CiSE has been
included in the project and the stylistic points that were raised by the
editor in chief (EiC) have also been implemented. The most important points
were:
- Including citations within the text structure (as if they would be
footnotes), so things like "see \cite{...}" should have been changed.
- Hyperlinks should be printed as footnotes (because the journal gets
actually printed).
Also, to avoid the second listing breaking between pages, it has been moved
to after the next paragraph.
|
|
Being immutable doesn't necessary mean that something is always present, so
an "always present" was also added for the reason we recommend a Git
hash. The end of the sentence was also slightly summarized to allow the
extra few words.
The re-wording of the conclusion of Active papers, was great! I just
changed the "likely" to "possible", because as Konrad mentioned in Commit
a63900bc5a8, he is now using Guix.
|
|
These are minor last minute copyedits for recently added text,
e.g. a git hash is not literally a timestamp.
|
|
The AMIGA team at the Instituto Astrofísica Andalucía (IAA) are very active
proponents of reproducibility. They had already provided very constructive
comments after my visit there and many subsequent interactions. So until
now, the whole team's contributions were acknowledged.
Since the last submission, several of the team members were able to kindly
invest the time in reading the paper and providing very useful comments
which are now being implemented. As a result, I was able to specifically
thank them in the paper's acknowledgments (Thanks a lot AMIGA!). Below, I
am listing the points in the order that is shown in 'git log -p -1' for
this commit.
- Javier Moldón: "PM is not defined. First appearance in the first page".
Thanks for noticing this Javier, it has been corrected.
- Javier Moldón: "In Section III. PROPOSED CRITERIA FOR LONGEVITY and
Appendix B, you mention the FAIR principles as desirable properties of
research projects and solutions, respectively which is good, but may
bring confusion. Although they are general enough, FAIR principles are
specifically for scientific data, not scientific software. Currently,
there is an initiative promoted by the Research Data Alliance (RDA),
among others, to create FAIR principles adapted to research software, and
it is called FAIR4RS (FAIR for Research Software). More information here:
https://www.rd-alliance.org/groups/fair-4-research-software-fair4rs-wg. In
2020 there was a kick-off meeting to divide the work in 4 WG. There is
some more information in this talk:
https://sorse.github.io/programme/workshops/event-016/. I have been
following the work of WG1, and they are about the finish the first
document describing how to adapt the FAIR principles to software. Even if
all this is still work in progress, I think the paper would benefit from
mentioning the existence of this effort and noticing the diferences
between Data and Software FAIR definitions."
Thanks for highlighting this Javier, a footnote has been added for this
(hopefully faithfully summarizing it into one sentence due to space
limitations).
- Sebastian Luna Valero: "Would it be a good idea to define long-term as a
period of time; for example, 5 years is a lot in the field of computer
science (i.e. in terms of hardware and software aging), but maybe that is
not the case in other domains (e.g. Astronomy)."
Thanks Sebastian, in section 2, we do give longevity of the various
"tools" in rough units of years (this was also a suggestion by a
referee). But of course the discussion there is very generic, so going
into finer detail would probably be too subjective and bore the reader.
- Sebastian Luna Valero: "Why do you use git commit eeff5de instead of git
tags or releases for Maneage? Shown for example in the abstract of the
paper: "This paper is itself written with Maneage (project commit
eeff5de)."
Thanks for raising this important point, a sentence has been added to
explain why hashes are objective and immutable for a given history, while
tags can easily be removed or changed, or not cloned/pushed at all.
- Susana Sanchez Exposito: "We think interoperability with other research
projects would be important, do you have any plans to make maneage
interoperable with, for example, the Common Workflow Language (CWL)?".
Thanks a lot for raising this point Susana. Indeed, in the future I
really do hope we can invest enough resources on this. In the discussion,
I had already touched upon research objects as one method for
interoperability, there was also a discussion on such generic standards
in Appendix A.D.10. But to further clarify this point (given its
importance), I mentioned CWL (and also the even more generic CWFR) in the
discussion.
- Sebastian Luna Valero: "Regarding Apache Taverna, please see:"
https://github.com/apache/incubator-taverna-engine/blob/master/README.md
Thanks a lot for this note Sebastian! I didn't know this! I wrote this
section (and visited their webpage) before their "vote"! It was a
surprize to see that their page had changed. I have modified the
explanation of Taverna to mention that it has been "retired" and use the
Github link instead.
- Sebastian Luna Valero: "Page 21: 'logevity' should be 'longevity'."
Thanks a lot for noticing this! It has been corrected :-).
- Javier Moldón: "There is a nice diagram in Johannes Köster's article on
data processing with snakemake that I find very interesting to show some
key aspects of data workflows: see Fig 1 in
https://www.authorea.com/users/165354/articles/441233-sustainable-data-analysis-with-snakemake "
This is indeed a nice diagram! I tried to cite it, but as of today, this
link is not a complete paper (with no abstract and many empty section
titles). If it was complete, I would certainly have cited it in
Snakemake's discussion.
- Javier Moldón: "Regarding the problem mentioned in the introduction about
PM not precisely identified all software versions, I would like to
mention that with Snakemake, even if the analysis are usually constructed
using other package managers such as conda, or containers, you don't need
to depend on online servers or poorly-documented software versions, as
you can now encapsulate an analysis in a tarball containing all the
software needed. You still have long-term dependency problems (as you
will need to install snakemake itself, and a particular OS), but at least
you can keep the exact software versions for a particular platform."
Thanks for highlighting this Javier. This is indeed better than nothing,
we have already discussed the dangers of this "black box" approach of
archiving binaries in many contexts, and many package managers have
it. So while I really appreciate the point (I didn't know this), to avoid
lengthening the paper, I think its fine to not mention it in the paper.
|
|
Konrad had kindly gone through the paper and the appendices with very good
feedback that is now being addressed in the paper (thanks a lot Konrad!):
- IPOL recently also allows Python code. So the respective parts of the
description of IPOL have been updated. To address the dependency issue, I
also added a sentence that only certain dependencies (with certain
versions) are acceptable.
- On Active Papers (AP: which is written by Konrad) corrections were made
based on the following parts of his comments:
- "The fundamental issue with ActivePapers is its platform dependence on
either Java or Python, neither of which is attractive."
- "The one point which is overemphasized, in my opinion, is the necessity
to download large data files if some analysis script refers to it. That
is true in the current implementation (which I consider a research
prototype), but not a fundamental feature of the approach. Implementing
an on-demand download strategy is not particularly complicated, it just
needs to be done, and it wasn't a priority for my own use cases."
- "A historical anecdote: you mention that HDF View requires registering
for download. This is true today, but wasn't when I started
ActivePapers. Otherwise I'd never have built on HDF5. What happened is
that the HDF Group, formerly part of NCSA and thus a public research
infrastructure, was turned into a semi-commercial entity. They have
committed to keeping the core HDF5 library Open Source, but not any of
the tooling around it. Many users have moved away from HDF5 as a
consequence. The larger lesson is that Richard Stallman was right: if
software isn't GPLed, then you never know what will happen to it in the
future."
- On Guix, some further clarification was added to address Konrad's quote
below (with a link to the blog-post mentioned there). In short, I
clarified that I mean storing the Guix commit hash with any respective
high-level analysis change is the extra step.
- "I also looked at the discussion of Nix and Guix, which is what I am
mainly using today. It is mostly correct as well, the one exception
being the claim that 'it is up to the user to ensure that their created
environment is recorded properly for reproducibility in the
future'. The environment is *recorded* in all detail,
automatically. What requires some effort is extracting a human-readable
description of that environment. For Guix, I have described how to do
this in a blog post
(https://guix.gnu.org/en/blog/2020/reproducible-computations-with-guix/),
and in less detail in a recent CiSE paper
(https://hal.archives-ouvertes.fr/hal-02877319). There should
definitely be a better user interface for this, but it's no more than a
user interface issue. What is pretty nice in Guix by now is the user
interface for re-creating an environment, using the "guix time-machine"
subcommand."
- The sentence on Software Heritage being based on Git was reworded to fit
this comment of Konrad: "The plural sounds quite optimistic. As far as I
know, SWH is the only archive of its kind, and in view of the enormous
resources and long-time commitments it requires, I don't expect to see a
second one."
- When introducing hashes, Konrad suggested the following useful paper that
shows how they are used in content-based storage:
DOI:10.1109/MCSE.2019.2949441
- On Snakemake, Konrad had the following comment: "[A system call in Python
is] No slower than from bash, or even from any C code. Meaning no slower
than Make. It's the creation of a new process that takes most of the
time." So the point was just shifted to the many quotations necessary for
calling external programs and how it is best suited for a Python-based
project.
In addition some minor typos that I found during the process are also
fixed.
|
|
Until now, important LaTeX packages like 'caption' (for managing figure
captions), 'hyperref' (for managing links) and 'xcolor' (for managing
colors) were being loaded inside the optional
'tex/src/preamble-maneagge-defualt-style.tex' file. We recommend to remove
this file from loading when you use custom journal sytels. However, these
packages will often be necessary after loading special journal styles also.
With this commit, these packages are now loaded into LaTeX as part of the
'tex/src/preamble-project.tex' file. This file is in charge of LaTeX
settings that are custom to the project and independent of its style.
Several other small corrections are made with this commit:
- I noticed that './project make texclean' crashes if no PDF exists in the
working directory! So a '-f' was added to the 'rm' command of the
'texclean' rule.
- As part of the LaTeX Hyperref, we can set general metadata or properties
for the PDF (that aren't written into the printable PDF, but into the
file metadata). They can be viewed in many PDF viewers as PDF
properties. Until now, we were only using the '\projecttitle' macro here
to write the paper's title. However, thanks to the recently added
'reproduce/analysis/config/metadata.conf', we now have a lot of useful
information that can also go here. So the 'metadata-copyright-owner' is
now used to define the PDF author, and the project's
'metadata-git-repository' and commit hash are written into the PDF
subject. But to import these, it was necessary to define them as LaTeX
macros, hence the addition of these macros in 'initialize.mk'.
- Some extra packages that aren't necessary to build the default PDF were
removed in 'preamble-project.tex'.
|
|
With the submission of the revision (which highlighted all the relevant
parts to the points the referees raised in the submitted PDF) it is no
longer necessary to highlight these parts.
If we get another revision request, we can add new '\new' parts for
highlighting.
|
|
This commit makes some minor fixes following the hardwired non-numerical
solution to the cross-referencing issue between the main article and the
supplement, such as fixing "lineage like lineage" and missing closing
parentheses.
From Mohammad: while re-basing the commit over the 'master' branch, I also
added Boud'd name at the top of the copyright holders of the appendices.
|
|
Since the addition of the appendix bibliography we hadn't checked the 'make
dist' command, as a result the PDF couldn't be built. With this commit, in
the 'dist' rule, we are now also copying 'appendix.bbl' and the created
tarball could build the PDF properly. Also the 'peer-review' directory is
now also included in the tarball created by './project make dist'.
I also found a small typo in the description of Occam (an 'a' was missing)
and fixed it.
|
|
In preparation for the submission of the revised manuscript, I went through
the full paper and appendices one last time. The second appendix (reviewing
existing reproducible solutions) in particular needed some attention
because some of the tools weren't properly compared with the criteria.
In the paper, I was also able to remove about 30 words, and bring our own
count (which is an over-estimation already) to below 6250.
|
|
After his previous two commits, we discussed some of the points and I am
making these edits following those. In particular the last statement about
Madagascar "could have been more useful..." was changed to simply mention
that mixing workflow with analysis is against the modularity principle. We
should not judge its usefulness to the community (which is beyond our scope
and would need an official survey).
A few other minor edits were done here and there to clarify some of the
points.
|
|
With this commit, I have corrected some minor typos of this appendix.
They are very minor corrections.
|
|
With this commit, I have corrected some minor typos of this appendix.
In addition to that, I also put empty lines to separate subsections and
subsubsections appropiately.
|
|
I ran a simple Emacs spell check over the main body and the two
appendices. All discovered typos have been fixed.
|
|
With this commit, I have corrected some minor typos of this appendix. In
addition to that, I also put empty lines to separate subsections and
subsubsections appropiately (5 lines and 1 line, respectively).
|
|
Having entered 2021, it was necessary to update the years of all the
copyright statements.
|
|
There were only three very small conflicts that have been fixed.
|
|
Until now, in the appendices we were simply using '\ref' to refer to
different parts of the published paper. However, when built in
'--supplement' mode, the main body of the paper is a separate PDF and
having links to a separate PDF is not impossible, but far too complicated.
However, having the links adds to the richness of the text and helps point
readers to specific parts of the paper.
With this commit, there is a LaTeX conditional anywhere in the appendices
that we want to refer the reader to sections/figures in the main body. When
building a separate PDF, the resepective section/figure is cited in a
descriptive mode (like "Seciton discussing longevity of tools"). However,
when the appendices go into the same PDF as the main body, the '\ref's
remain.
|
|
Having added/modified text in the supplements, Boud is now a copyright
holder of this file too.
I also added 2021 to the copyright years of paper.tex and supplement.tex.
|
|
This commit does some minor copyediting, especially of the
introduction to the supplement. There's no point complaining to
the reader about the word limit of the journal: s/he is not
interested in that. This is not the right place for discussing
journal policy. The need for summarising content and focussing on
key elements of a cohesive argument is fundamental in a world of
information overload. A&A/MNRAS/ApJ/PRD letters are generally
much worse than normal articles in terms of reproducibility
because they have to omit so many details that the reader has
to read the full articles to really know what is done. But the
reality is that letters get read a lot, because they're short
and snappy.
|
|
In the abstract the repeated benefits of Maneage (which are also mentioned
in the criteria) were removed to fit into CiSE's online submission
guidelines. In Section II (Longevity of existing tools), the paragraph that
itemized the following paragrahs as a numbered list has been removed with
the sentence that repeatedly states the importance of reproducibility in
the sciences and some branches of the industry.
With these changes our approximate automatic count has 6277 words. This is
still very slightly larger than the 6250 word limit of the
journal. However, this count is a definite over-estimation (including many
things like page titles and page numberings from the raw PDF to text
conversion). So the actual count for the journal publication should be less
than this.
A few other tiny corrections were made:
- The year of the paper and copyright in 'README.md' was set to 2021. The
copyright of the rest of the files will be set to 2021 after the next
merge with Maneage soon (the years of core infrastructure copyrights has
already been corrected there).
- Mohammadreza's name was added in 'README.md'.
- The line to import the "necessity" appendix has been commented in the
version to have the full paper in one PDF (to be upladed to arXiv or
Zenodo).
- The supplement PDF now starts with '\appendices' so the sections have
the same labels as the single-PDF version.
|
|
Until now the supplement had no introduction for a random reader to see the
purpose of this "Web extra" supplement.
With this commit, an abstract has been added.
|
|
Until now, the build strategy of the paper was to have a single output PDF
that either contains (1) the full paper with appendices in the same paper
(2) only the main body of the paper with no appencies.
But the editor in chief of CiSE recently recommended publishing the
appendices as supplements that is a separate PDF (on its webpage). So with
this commit, the project can make either (1) a single PDF (containing both
the main body and the appendices) that will be published on arXiv and will
be the default output (this is the same as before). (2) two PDFs: one that
is only the main body of the paper and another that is only the appendices.
Since the appendices will be printed as a PDF in any case now, the old
'--no-appendix' option has been replaced by '--supplement'. Also, the
internal shell/TeX variable 'noappendix' has been renamed to
'separatesupplement'.
|
|
Having entered 2021, it was necessary to update the copyright years at the
top of the source files. We recommend that you do this for all your
project-specific source files also.
|
|
As recommended by Lorena Barba (editor in chief of CiSE), we should prepare
the appendices as a separate "Supplement" for the journal. But we also want
them to be appendices within the paper when built for arXiv.
As a first step, with this commit, each appendix has been put in a separate
'tex/src/appendix-*.tex' file and '\input' into the paper. We will then be
able to conditionally include them in the PDF or not.
Also, as recommended by Lorena, the general "necessity for reproducible
research" appendix isn't included (possibly going into the webpage later).
|
|
This commit makes many small wording fixes, mainly to Appendix A.
It also insert "quotes" around some of the titles fields in
'tex/src/references.tex', since otherwise capitalisation is lost (DNA
becomes Dna; 'of Reinhart and Rogoff' becomes 'of reinhart and rogoff'; and
so on). I didn't do this for all titles, because some Have All Words
Capitalised, which blocks the .bib file from choosing a consistent style.
|
|
Some minor edits were made to the paper to shorten it. In particular the
example of IPOL was removed from the main body of the paper, and we'll just
rely on the more extensive review of IPOL in the appendix. I also updated
the referee report to account for the new Appendix A that is just an
extended introduction.
Also, I noticed that the Menke+20 paper that we replicate here has recently
been published in the iScience journal. So its bibliography was updated
from the bioarXiv information to the journal information.
Also, the number of words (after removing abstract and captions and
accounting for figures) is now only printed when the project is built with
'--no-appendix'. This was done because this information is
extra/annoying/unnecessary for the case where there is an appendix.
|
|
In the first/long draft of this work, we had a good introduction on the
necessity of reproducibility. But we were forced to remove it because of
word-count limits. Having moved a major portion of the previous work into
the appendices, I thought it would be good to put that introduction as a
first appendix also, focused on the necessity for reproducibile research.
|
|
Some minor conflicts that came up during the merge were fixed.
|
|
This only concerns the TeX sources in the default branch. In case you don't
use them, there should only be a clean conflict in 'paper.tex' (that is
obvious and easy to fix). Conflicts may only happen in some of the
'tex/src/preamble-*.tex' files if you have actually changed them for your
project. But generally any conflict that does arise by this commit with
your project branch should be very clear and easy to fix and test.
In short, from now on things will even be easier: any LaTeX configuration
that you want to do for your project can be done in
'tex/src/preamble-project.tex', so you don't have to worry about any other
LaTeX preamble file. They are either templates (like the ones for PGFPlots
and BibLaTeX) or low-level things directly related to Maneage. Until now,
this distinction wasn't too clear.
Here is a summary of the improvements:
- Two new options to './project make': with '--highlight-new' and
'--highlight-notes' it is now possible to activate highlighting on the
command-line. Until now, there was a LaTeX macro for this at the start
of 'paper.tex' (\highlightchanges). But changing that line would change
the Git commit hash, making it hard for the readers to trust that this
is the same PDF. With these two new run-time options, the printed commit
hash will not changed.
- paper.tex: the sentences are formatted as one sentence per line (and one
line per sentence). This helps in version controlling narrative and
following the changes per sentence. A description of this format (and
its advantages) is also included in the default text.
- The internal Maneage preambles have been modified:
- 'tex/src/preamble-header.tex' and 'tex/src/preamble-style.tex' have
been merged into one preamble file called
'tex/src/preamble-maneage-default-style.tex'. This helps a lot in
simply removing it when you use a journal style file for example.
- Things like the options to highlight parts of the text are now put in
a special 'tex/src/preamble-maneage.tex'. This helps highlight that
these are Maneage-specific features that are independent of the style
used in the paper.
- There is a new 'tex/src/preamble-project.tex' that is the place you
can add your project-specific customizations.
|
|
Until now, the Maneage-only features of LaTeX where mixed with
'tex/src/preamble-project.tex' (which is reserved for project-specific
things). But we want to move the highlighting features (that have started
here) into the core Maneage branch, so its best for these Maneage-specific
features to be in a Maneage-specific preamble file.
With this commit, a hew 'tex/src/preamble-maneage.tex' has been created for
this purpose and the highlighting modes have been put in there. In the
process, I noticed that 'tex/src/preamble-project.tex' doesn't have a
copyright! This has been corrected.
|
|
This commit makes the numbered links to references such as [13]
[14] [15] in the appendices clickable in the pdf. The solution
was to call the "\newcites" command from the "multilibs" package
*after* loading "hyperref".
First do "rm -fv .build/tex/build/*.bbl .build/tex/build/*.aux"
and then "./project make" a few times.
|
|
A new directory has been added at the top of the project's source called
'peer-review'. The raw reviews of the paper by the editors and referees has
been added there as '1-review.txt'. All the main points raised by the
referees have been listed in a numbered list and addressed (mostly) in
'1-answers.txt'. The text of the paper now also includes all the
implemented answers to the various points.
|
|
Until now, the core Maneage 'paper.tex' had a '\highlightchanges' macro
that defines two LaTeX macros: '\new' and '\tonote'.
When '\highlightchanges' was defined, anything that was written within
'\new' became dark green (highlighting new things that have been
added). Also, anything that was written in '\tonote' was put within a '[]'
and became dark red (to show that there is a note here that should be
addressed later).
When '\highlightchanges' wasn't defined, anything within the '\new' element
would be black (like the rest of the text), and the things in '\tonote'
would not be shown at all.
Commenting the '\newcommand{\highlightchanges}{}' line within 'paper.tex'
(to toggle the modes above) would create a different Git hash and has to be
committed.
But this different commit hash could create a false sense in the reader
that other things have also been changed and the only way they could
confirm was to actually go and look into the project history (which they
will not usually have time to do, and thus won't be able to trust the two
modes of the text).
Also, the added highlights and the note highlights were bundeled together
into one macro, so you couldn't only have one of them.
With this commit, the choice of highlighting either one of the two is now
done as two new run-time options to the './project' script (which are
passed to the Makefiles, and written into the 'project.tex' file which is
loaded into 'paper.tex'). In this way, we can generate two PDFs with the
same Git commit (project's state): one with the selected highlights and
another one without it.
This issue actually came up for me while implementing the changes here: we
need to submit one PDF to the journal/referees with highlights on the added
features. But we also need to submit another PDF to arXiv and Zenodo
without any highlights. If the PDFs have different commit hashes, the
referees may associate it with other changes in any part of the work. For
example https://oadoi.org/10.22541/au.159724632.29528907 that mentions
"Another version of the manuscript was published on arXiv: 2006.03018",
while the only difference was a few words in the abstract after the journal
complained on the abstract word-count of our first submission (where the
commit hashes matched with arXiv/Zenodo).
|
|
With the optional appendices added recently to the paper, it was important
to go through them and make them more fitting into the paper.
|
|
Given the referee reports, after discussing with the editors of CiSE, we
decided that it is important to include the complete appendix we had before
that included a thorough review of existing tools and methods. However, the
appendix will not be published in the paper (due to the strict word-count
limit). It will only be used in the arXiv/Zenodo versions of the paper.
This actually created a technical problem: we want the commit hash of the
project source to remain the same when the paper is built with an appendix
or without it.
To fix this problem the choice of including an appendix has gone into the
'project' script as a run-time option called '--no-appendix'. So by default
(when someone just runs './project make'), the PDF will have an appendix,
but when we want to submit to the journal, or when the appendix isn't
needed for a certain reason, we can use this new option. The appendix also
has its own separate bibliography.
Some other corrections made in this commit:
1. Some new references were added that had an '_' in their source, they
were corrected in 'references.tex'.
2. I noticed that 'preamble-style.tex' is not actually used in this paper,
so it has been deleted.
|
