| Age | Commit message (Collapse) | Author | Lines |
|---|
|
[Compared to first submission to DSJ last week with 11436 words in raw PDF,
we have decreased the paper by ~1000 words to 10493 :-)]
As with the previous commits, the moment Boud changed the structure of
sentences, I was able to find the redundancies and remove them! This is a
fascinating feature of collaboration I had never felt before: it is so hard
to find redundancies in my own raw text, but even a minor correction by
someone else suddeny breaks my mental memories/barrier on the sentence,
allowing me to be more critical to it!
Anyway, besides such corrections, I fixed a few other things: 1) In the
DSJ's recently published papers, ther is no `~' between "Figure" and its
number. 2) I noticed that in `tex/src/figure-src-inputconf.tex' I was
actually using manually input strings for the filename, checksum and size!
This was contrary to the whole philosophy of Maneage(!), I must have rushed
and forgot! So LaTeX variables are now defined and used.
|
|
About 20 words less. The ArXiv URL is added - this adds no extra
length in words, and some readers will not be familiar with ArXiv
(although the COVID-19 pandemic has attracted attention to BiorXiv).
|
|
Increase by 5 words. We don't need to give a big warning here,
but "Permissions management" is meant to be a brief way of saying
that whether or not different users can really read/write/execute
in subdirectories will firstly depend on whether the user who
cloned Maneage has handled these permissions correctly and whether
s/he is able to allow others to edit in his/her subdirectories.
Comment: Users would have to check who else is logged in at the time,
who else is running jobs, and so on. On a supercomputer this might
make sense, to avoid unnecessary recompiles. Anyway, this edit
summary is not the place to discuss this...
|
|
Reduction by 15 words. "Branch" is fine as a verb, and "off"
is fine as a preposition; there's no need for a second preposition.
"We branched off the main forest path onto a smaller path".
|
|
Length reduction by about 15 words.
A semantically significant change is from `leading to more robust
scientific results` to `evolves in the case of exploratory
research papers, and better self-consistency in hypothesis
testing papers`.
I said this in a previous commit, but it can't hurt repeating:
In the covidian epoch (though not only), it is especially
important to distinguish bayesian type exploratory research
(typical in astronomy or searching for a good COVID-19 treatment
or vaccine) from hypothesis testing (clinical testing in
double-blind random access trials with clinical trials methods
published on a public registry prior to the trials taking
place). In the latter case, you want your results to be analysed
consistently with the plan published before the trials even
begin, and ideally you want them to be published (or at least
posted on the trial registry website) even if your results are
insignificant, to avoid a publication bias in favour of
significant results. Test homeopathy against placebos in 1000
independent experiments, analyse them all the same way, and 2-3
experiments will be significant at the 3 sigma level...
|
|
Reduction by about 7 words.
I added "internet security" as an extra reason for having all the
downloads in a single file. Modularity and minimal complexity in
themselves generally contribute to internet security, but in this
case, it's obvious that having all the communication with the
outside world managed through a single file makes internet security
management much simpler.
I replaced the "fake URL" by the real one, because at least in the
present format, the URL fits in nicely. So both `paper.tex` and
`tex/src/figure-src-inputconf.tex` are modified in this commit.
|
|
Reduction by about 20 words - minor rewording.
|
|
Idafen has helped in testing Maneage a lot during the last year and has
provided very useful feedback and suggestions.
|
|
Regarding Docker Konrad pointed out that "Linux has an excellent track
record for stability. It's more likely that the Docker itself becomes
incompatible with older containers. Docker isn't developed for
reproducibility after all".
So I tried to modify that paragraph to include this important point too. In
the process, I also shrank it a little more (without loosing anything
substantial), so it doesn't add to the paper's length.
|
|
After going through Boud's corrections, I thought it can be further
summarized without loosing any major point.
|
|
Reduction by 4 words. Minor rewording; removal of "Note that"
and "simply" (the opposite of "complicatedly"). If a checksum
is simple for a given user, then s/he already knows that; if s/he
doesn't yet know what a checksum is, then stating that it's simple
doesn't help very much. :)
|
|
Reduction of about 15 words.
The phrase "which does not need it" is removed. On its own, this is
a claim, not an explanation. If the reader is wondering why `paper.tex`
is not a produced file, then stating that the file is not needed will
not help very much. Looking at the diagram will show that `paper.tex`
is the overall article template; and the diagram strongly suggests
that values from initialize.tex, ..., are passed into verify.tex,
and from there into project.tex, which goes into paper.tex.
The phrase "files, possibly in another subMakefile" should really
be something like "files, possibly created by another subMakefile".
But this would add more words, and given that the user has full control
to modify and adapt the overall scheme (including making a mess of it),
we can safely drop the info that the scheme can be made more complicated. :)
|
|
Only 3 words are reduced in this commit, but I think the
improvements are worth it.
"Note that" and "It is worth mentioning" are phrases still quite
often used by academics (even in astronomy) that can be politely
described as "pontification" or informally as "empty blabla";
these add no meaning except "I am teaching you something and I
expect you to pay attention to what I am saying". :) There are
also less polite descriptions.
|
|
Minor rewording of 4.3 Project analysis - introduction.
Reduction of about 40 words.
4.2 `parallel` quote: s/http:/https:/
|
|
Today Konrad made the following suggestions after reading through the paper
(created from Commit 1ac5c12). Thanks a lot Konrad ;-). I tried to address
them all in this commit. Afterwards, while looking over the corrected
parts, some minor edits came up to me to remove redundant parts and add
extra points where it helps.
In particular to be able to print the International Phonetic Alphabet
(IPA), I had to include the LaTeX `TIPA' package, but it was interesting to
see that it was already available in the project as a dependency of another
package we loaded.
|
|
Tags are not a fixed piece of history (they can easily be moved and not
imported in a different repository), so they are only confusing in the
context of Maneage (where people should branch-off the main project). the
raw commit hashes are a much more robust way to store a precise moment in
history.
Before this commit, I removed all Tags from the main Git repositories of
Maneage and thus removed any mention of Tags with
`README-hacking.md'. Ofcourse, if a project decides to use tags is upto
them, but we won't implement it in the main branch.
|
|
Roberto Baena recently tried building a new project with Maneage and
provided the following suggestions to make it more clear for a new user:
1) In the part where we talk about creating a Git repository, we should
highlight that it must be empty. This is because some (for example Gitlab)
propose to include a `README' file. But if the project is not empty, Git
will not allow pushing to it.
2) The `(can be done later)' comment was removed from the "Delete dummy
parts") to avoid confusion about applying some of them, but not others: if
only some are done, it may cause problems in the build.
|
|
Until now, the message that we printed just before starting to build
software didn't actually print the current directory, but only `pwd'. With
this commit, this is fixed (it uses the `currentdir' variable that is
already found before).
|
|
Until now, the message that we printed just before starting to build
software didn't actually print the current directory, but only `pwd'. With
this commit, this is fixed (it uses the `currentdir' variable that is
already found before).
|
|
We recently fixed the problem of TeXLive that hard-codes the year of its
build in its installation directory. But the note on this problem was still
kept in `README-hacking.md'. That part is now removed.
Also, to help in following the checklist, it is now an ordered list.
|
|
Boud previously pointed out that that he couldn't find a reference to the
citation, so I added it as a link over "its FAQ" (since its described in
its `doc/citation-notice-faq.txt' file). I also removed the first part of
the quote which was not really necessary, the heart of the quote is the
latter part that still remains.
|
|
I tried to make it slightly shorter, but I felt that it is important to
keep the quote from GNU Parallel and in particular the financial aid it
asks for. It will help readers feel the gravity of the sitution for this
software author. The precise citation of the quote was given in the long
version.
|
|
This reduces the length by about 70 words.
The biggest change is to remove what looks like a citation from
`parallel'. I couldn't find the citation in GNU parallel
20161222-1 (Debian/stretch), nor with search engines.
I don't think that the quote is really so useful (even assuming
it's a valid quote from somewhere): citation practices are a mix
between ethics, preparation to convince referees, citing those who
are already cited frequently, and the practicality of searching for
and verifying references against the information for which they
are used. Showing that Maneage makes citation not only easy, but
more or less automatic, bypasses some of the compromises between
practicality and ethics.
|
|
Minor rewording; a reduction of about 12 words.
|
|
Minor edits - reduces about 17 words.
|
|
This commit reduces about 25 words from the 4.1 Maneage
orchestration, aka `make`, section.
|
|
This drops the word count in the introductory part of the Maneage
section by about 15 words.
|
|
Thanks to Boud's corrections, I see that the sentence can be confusing and
not convey the point I wanted to make properly, so I am clarifying it
here. The main point is that this principle complements the definition of
reproducibility, not the other principls.
|
|
These tiny language edits add 1 word in length.
|
|
Boud has contributed a lot to Maneage over the last few years and with the
last few commits he also contributed significantly to this paper, so I am
moving him to third author.
Thanks to Boud, I also remembered that even though I done the most
important parts of Maneage in Lyon, I hadn't added it as an affiliation for
myself, so I added it. Maneage became a separate project in Lyon.
Finally, I tried to decrease the length of the acknowledgments by adding
some abbreviations that were shared between various parts.
|
|
Unfortunately, adding in my name/affiliations/acknowledgments
adds about 90 words to the text. We don't really know if these
are counted by the editor in the 8000-word limit.
I changed `funded' to `funded/supported'. I only get funding from
one out of the three sources I acknowledge, but it's important to
acknowledge all three.
|
|
While looking over the PDF, a few small edits were made to be more clear.
|
|
Until now, throughout Maneage we were using the old name of "Reproducible
Paper Template". But we have finally decided to use Maneage, so to avoid
confusion, the name has been corrected in `README-hacking.md' and also in
the copyright notices.
Note also that in `README-hacking.md', the main Maneage branch is now
called `maneage', and the main Git remote has been changed to
`https://gitlab.com/maneage/project' (this is a new GitLab Group that I
have setup for all Maneage-related projects). In this repository there is
only one `maneage' branch to avoid complications with the `master' branch
of the projects using Maneage later.
|
|
The conflict was only on the list of existing tools and that was easily
corrected.
|
|
Following Boud's great corrections, I was able to futher summarize this
section, decreasing roughly 150 more words from this section.
|
|
Until now the list of existing tools was written in one line which made it
hard to read and follow, especially since we added links. It is now
expanded into a one-line per item which makes to no difference in the final
PDF.
|
|
Reduction by 15 words.
|
|
Reduction by 7 words.
For a regular GNU/Linux of other unix-like system user, the bit
about ISO C compilers even existing for Microsoft systems more or
less says "despite there being no point ever trying to do science
on a Microsoft system, you *could* hypothetically compile and run
any ISO C program on it". Interesting, but not directly of
interest to this user, who is unlikely to actually want to do it.
A Microsoft user who thinks that s/he can do science on a
Microsoft system will typically think "Microsoft is good, so of
course I can run anything I want on it". So the message here
could more likely be seen as provocative rather than useful,
since this user is unaware of the fundamental problems of
Microsoft as an authoritarian, manipulative, centralised
organisation providing bad software.
So either way, the parenthesis about Microsoft can be safely
removed given the space constraints.
|
|
Reduction by 5 words.
The term "exploratory research" is intended in the specific sense
listed at en.Wikipedia:
https://en.wikipedia.org/wiki/Exploratory_research
to distinguish it from hypothesis testing. The final phases of clinical
(medical) research, for example, to test whether a candidate SARS-CoV-2
vaccine is (i) effective and (ii) safe in homo sapiens, cannot accept the
exploratory methods that are acceptable in astronomy, or in other
exploratory research (which is acceptable in the early stages of medical
research).
Clinical trial registration is aimed at *preventing* scientists from
modifying their methods in a given project:
https://en.wikipedia.org/wiki/Clinical_trial_registration
|
|
One superfluous word was removed.
|
|
Minor wording changes - reduction by 10 words.
|
|
Minor wording improvements; reduction by 10 words.
|
|
For consistency, the principles should either all be nouns, or
all be adjectives. Most are nouns, so this commit switches the
adjectives to nouns.
|
|
Compression by about 40 words. Updating python2 to python3
is often nothing more than modifying print statements, so
removing this doesn't weaken the text by much.
Re-creation helps avoid thinking of watching movies, going to
the beach, reading a novel, when seeing the word "recreation":
https://en.wiktionary.org/wiki/recreation#Usage_notes
The matplotlib sentence was not so clear: now it's a bit shorter
and hopefully clearer.
|
|
Word-length reduction (8 words) of the first part of 3 Principles.
Change in meaning: we can argue that *results* are not part of
science, but science needs aims as well as methods; hypotheses
are needed too, but these overlap between the aims and
methods. So I put "primarily".
|
|
In this commit, the URLs for the 19 "earlier solutions" at the
beginning of "3 Principles" are recovered from
tex/src/paper-long.tex and put behind the package names
as clickable words.
To reduce the chance that these are interpreted as references,
"Project1 (yyy1), Project2 (yyy1)" is changed to "yyy1: Project1,
Project2". We cannot add full references because of the 8000-word
space constraint.
With a minor word improvement, this commit overall reduces the word
count very slightly, by 9, according to
pdftotext paper.pdf |wc paper.txt
before and after the commit.
|
|
Scalability is not just on the size of the project, but also its
complexity, so I added an `and/or complex' to the description of the
scalability principle.
|
|
Someone reading the principles section until now would think that IPOL is
an almosts perfect solution, and for its usecase it certainly is. However,
this is only because of the nature of its work: it only focuses on
algorithms, not usage/analysis which cannot be done in raw ISO C.
So with this commit, I added a new principle on Scalability and discussed
this limitation of IPOL there. To avoid simply lengthening the text, to add
this new principle, I had to remove/summarize some parts that seemed
redundant. In the process, I also removed some of the existing tools (at
the start of the principles section) that had several others in the same
time frame, I have already mentioned (through the "and many more") that
this list is not complete.
Also, the list of people to thank in the acknowledgments is now put in a
one-line per name to be more easily maintainable: Boud and Mohammad-reza
were added, and given that I have sent the paper to several other people
for feedback, I expect the list to get longer.
|
|
A few more minor language edits. For parseable vs parseable, see
https://en.wiktionary.org/wiki/parsable which recommends `parsable`
for formal usage.
|
|
These are mostly minor language edits. There is one significant fix: the
word `typically' in `a non-free software project typically' cannot be
distributed by the project. There is a whole range of licences between
strictly free software definition, strictly OSI open-source definition, and
fully closed source. For example, software with a no-commercial usage
licence (similar to CC-BY-NC) can be publicly redistributed on any server,
as long as there is no requirement of payment or no requirement of payment
that is "commercial" (according to lawyers' interpretation of when a
payment is commercial).
|
