aboutsummaryrefslogtreecommitdiff
AgeCommit message (Collapse)AuthorLines
2021-04-17Imported recent work in Maneage, minor conflicts fixedMohammad Akhlaghi-62/+144
Some minor conflicts (all expected from the commit messages in the Maneage branch) occurred but were easily fixed.
2021-04-17IMPORTANT: print-general-metadata new name for print-copyrightMohammad Akhlaghi-77/+115
Summary: - Use the new name of this variable in your Makefiles. - In 'metadata.conf', remove fixed URL prefixes for DOIs ('https://doi.org/') or arXiv ('https://arxiv.org/abs'). Until now, the Make variable that would print the general metadata (of whole project) into each to-be-published dataset was called 'print-copyright'! But it now does much more than simply printing the copyright, it will also print a lot of metadata like arXiv ID, Zenodo DOI and etc into plain-text outputs. The out-dated name could thus be misleading and cause confusions. With this commit, the variable is therefore called 'print-general-metadata'. After merging your project with the Maneage branch, please replace any usage of 'print-copyright' to 'print-general-metadata'. Also with this commit, 'README-hacking.md' mentions 'metadata.conf' and 'print-general-metadata' in the "Publication checklist" section and reminds you to keep the first up to date, and use the second in your to-be-published datasets.
2021-04-17Finally published journal DOI addedMohammad Akhlaghi-73/+72
In the project's 'metadata.conf', we also have an option to store the journal DOI of the project (that will later be printed in the output file products). So now that the paper's DOI has been set by the journal, it was time to add it in the project too. While looking at the usage of the metadata, I noticed that the "Publication checklist" of 'README-hacking.md' didn't talk about it. In fact, the part about putting metadata went into a lot of detail without even mentioning the generic 'print-general-metadata' variable (previously called 'print-copyright') that is created in 'initialize.mk'. So I removed those extra points and just recommended using this variable for plain-text files and putting similar info in other formats. Some other minor changes were made: - The metadata now doesn't need the fixed 'https://doi.org/' prefix (to make it consistent with the arXiv identifier). Inside 'initialize.mk', there are now two variables called 'doi-prefix-url' and 'arxiv-prefix-url' that contain the fixed prefix. - The 'print-copyright' name was clearly outdated for all the extra metadata that this variable created (including the copyright). So its name was changed to 'print-general-metadata'. The generic Maneage changes will be taken into Maneage after this (they were tested here).
2021-04-17Added final review resultMohammad Akhlaghi-0/+147
In the previous commit, I had forgot to put a '-f' before the 'git add'! Becauase '.txt' files are set to be ignored in Git by default (they are marked in '.gitignore'). With this commit this file is now added into the project history.
2021-04-09Implemented EiC (Lorena Barba) comments, and added final reviewMohammad Akhlaghi-139/+138
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.
2021-04-09Minor corrections on previous copyeditMohammad Akhlaghi-2/+2
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.
2021-04-09Minor copyeditsBoud Roukema-3/+3
These are minor last minute copyedits for recently added text, e.g. a git hash is not literally a timestamp.
2021-04-09Corrected Roberto's affiliation and emailMohammad Akhlaghi-3/+4
Roberto has recently moved to a new position as professor in the Universidad Internacional de La Rioja. With this commit, his short bio and email address have thus been updated in the main paper to reflect this.
2021-04-09Changed all gitlab.com URLs to git.maneage.orgMohammad Akhlaghi-6/+6
Until now, we were primarily linking people to the Gitlab fork of this paper. However, since this paper is part of Maneage, its main repository is on Maneage's own server at http://git.maneage.org/paper-concept.git With this commit therefore, all the gitlab.com URLs have been corrected to owr own Git server. While looking into Git-related points, I also noticed that in the demo code listing showing how to clone Maneage and start a new project, we were using Git's old/depreciated 'master' name. Git (and almost all common repositories) now use 'main' as the default branch name, so this has also been corrected here.
2021-04-09Acknowledged Peter WittenburgMohammad Akhlaghi-1/+2
I attended one of Peter Wittenburg's talks in the context of RDA on the Canonical Workflow Frameworks for Research (CWFR). Afterwards I got in touch with him about Maneage and this paper. He kindly read the paper was very supportive of it with positive/encouraging feedback. It was thanks to that discussion that I added CWFR in the discussion (in the previous commit). But since that commit was focused on IAA's suggestions, I am acknowledging Peter here.
2021-04-09Comments by IAA's AMIGA team implementedMohammad Akhlaghi-14/+29
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.
2021-04-09Comments by Konrad Hinsen implementedMohammad Akhlaghi-25/+44
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.
2021-03-28Configuration: corrected check of group nameMohammad Akhlaghi-11/+11
When built in 'group' mode, the write permissions of all created files will be activated for a certain group of users in the host operating system. The user specifies the name of the group with the '--group' option at configure time. At the very start, the './project' script checks to see if the given group name actually exists or not (to avoid hard-to-debug errors popping up later). Until now, the checking 'sg' command (that was used to build the project with group-writable permissions) would always fail due to the excessive number of redirections. Therefore, it would always print the error message and abort. With this commit, the output of 'sg' is no longer re-directed (which also helps users in debuggin). If the group does actually exist, it will just print a small statement saying so, and if it fails, the error message is printed. This fixed the problem, allowing maneage to be built in group-mode. I also noticed that the variable name keeping the group name ('reproducible_paper_group_name') used the old name for the project (which was "Reproducible paper template"! So it has been changed/corrected to 'maneage_group_name'.
2021-03-26Initialization: removed other Gnuastro-specific featuresMohammad Akhlaghi-8/+3
In the previous commit, some Gnuastro-specific initializations were removed but a few more cases remained that are removed with this commit.
2021-03-26./project: unused --minmapsize option is removedMohammad Akhlaghi-6/+0
Until now, the './project' script included an '--minmapsize' option which is an option to one of the original programs that was used in Maneage (Gnuastro). Such an option doesn't exist in many other programs, so it is not a suitable option for the generic Maneage project (and can just cause confusion). It was also not used in any part of Maneage any more! With this commit, this option is removed from the core Maneage './project' script and if any project uses it, they can implement it in their own branch.
2021-03-24Maneage installation: removed TCL as a dependency of SWIGMohammad Akhlaghi-1/+2
Until now the SWIG software would use the host operating system's packages to find the TCL configuraiton (which we don't install yet in Maneage). In particular, you can see the error during its configuration here: .... checking for pkg-config... pkg-config checking for Tcl configuration... found /usr/lib/tclConfig.sh /usr/lib/tclConfig.sh: line 2: dpkg-architecture: command not found /usr/lib//tcl8.6/tclConfig.sh: line 2: dpkg-architecture: com. not found With this commit, TCL has been disabled when building SWIG with the '--without-tcl' option. Later, when we add TCL in Maneage, we can remove this option.
2021-03-20Configuration: nullability-completeness warnings suppressedRaul Infante-Sainz-3/+13
With a recent update of macOS systems (macOS Big Sur 11.2.3 and Xcode 12.4), there are many warnings when building C programs (for example the simple program we compile to check the compiler, or some of the software like `gzip'). It prints hundreds of warning lines for every source file that are irrelevant for our builds, but really clutters the output. With this commit, these warnings are disabled by adding `-Wno-nullability-completeness' to the 'CPPFLAGS' environment variable. This has also been added to the very first check of the C compiler in the configure step.
2021-03-20Configuration: --debug option available in this phase alsoRaul Infante-Sainz-13/+40
Until now, each time there was a problem in the configuration of Maneage'd projects and debugging was necessary, we had to take the following changes: - Run the configuration on a single thread ('-j1') to see the building of only the problematic software. - Disable the Zenodo check manually by commenting those parts of 'reproduce/software/shell/configure.sh'. Because the internet connection wastes a few seconds and is thus very annoying during repeated runs! - Manually remove the '-k' option that was passed to Make (when building the software). With the '-k', Make keeps going with the execution of other targets if something crashes and this usually causes confusions during the debugging. Doing the manual changes within the code was both very annoying and prone to errors (forgetting to correct it!). With this commit, the existing '--debug' option has been generalized to the software configuration phase of Maneage also. Until now, it was only available in the analysis phase (and would directly be passed to the 'make' command that would run the analysis). When this option is used, and the project is in the software configuration phase, the Zenodo check won't be done, it will use one single thread ('-j1'), and it will stop the execution as soon as an error occurs (Make is not run with '-k').
2021-02-12Installation: minor correction in links to system librariesMohammad Akhlaghi-2/+6
Until now when making a link to the system's 'dl' and 'pthread' libraries we were simply linking the installed location on the system (in '/usr/lib'). However, in some systems, these may themselves be links to other locations and this could cause linking problems. With this commit, we now use 'realpath' to extract the absolute address of the final file that the libraries may link to, and directly link to them. A minor cosmetic correction was also made in the build rule for CFITSIO: the long line was broken into two!
2021-01-12Default LaTeX preamble: some packages moved to preamble-project.texMohammad Akhlaghi-70/+42
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'.
2021-01-10make dist: removing temp files moved after project-specific filesMohammad Akhlaghi-6/+7
Until now, when you ran './project make dist', first it would delete the temporary files (like files ending in '~' or '.swp' created by some editors), then it had a place to add project-specific operations for the distribution. However, in the process of cleaning the temporary files, it would 'cd' into the directory that would later be packaged. So project-specific operations would first have to 'cd' back into the top source directory. This was prone to hard-to-find bugs. With this commit, to avoid the problem the project-specific operations are now placed before the cleaning phase. This is also technically good because in the project-specific operations there may also be temporary files that shouldn't go into the distribution tarball.
2021-01-09Imported recent changes in Maneage, minor single conflict fixedMohammad Akhlaghi-81/+213
There was a single conflict in the comments of one part of 'configure.sh' that has been fixed. There was also a single place that needed to convert 'BDIR' to 'badir' in this project (so after the merge, it also built easily).
2021-01-09IMPORTANT: analysis outputs written in BDIR/analysisMohammad Akhlaghi-66/+211
Until now, the build directory contained a 'software/' directory (that hosted all the built software), a 'tex/' subdirectory for the final building of the paper, and many other directories containing intermediate/final data of the specific project. But this mixing of built software and data is against our modularity and minimal complexity principles: built software and built data are separate things and keeping them separate will enable many optimizations. With this commit, the build directory of the core Maneage branch will only contain two sub-directories: 'software/' and 'analysis/'. The 'software/' directory has the same contents as before and is not touched in this commit. However, the 'analysis/' directory is new and everything created in the './project make' phase of the project will be created inside of this directory. To facilitate easy access to these top-level built directories, two new variables are defined at the top of 'initialize.mk': 'badir', which is short for "built-analysis directory" and 'bsdir', which is short for "built-software directory". HOW TO IMPLEMENT THIS CHANGE IN YOUR PROJECT. It is easy: simply replace all occurances of '$(BDIR)' in your project's subMakefiles (except the ones below) to '$(badir)'. To confirm if everything is fine before building your project from scratch after merging, you can run the following command to see where 'BDIR' is used and confirm the only remaning cases. $ grep -r BDIR reproduce/analysis/* --> make/verify.mk: innobdir=$$(echo $$infile | sed -e's|$(BDIR)/||g'); \ --> make/initialize.mk:badir=$(BDIR)/analysis --> make/initialize.mk:bsdir=$(BDIR)/software --> make/initialize.mk: $$sys_rm -rf $(BDIR) --> make/top-prepare.mk:all: $(BDIR)/software/preparation-done.mk 'BDIR' should only be present in lines of the files above. If you see '$(BDIR)' used anywhere else, simply change it to '$(badir)'. Ofcourse, if your project assumes BDIR in other contexts, feel free to keep it, it will not conflict. If anything un-expected happens, please post a comment on the link below (you need to be registered on Savannah to post a comment): https://savannah.nongnu.org/task/?15855 One consequence of this change is that the 'analysis/' subdirectory can be optionally mounted on a separate partition. The need for this actually came up for some new users of Maneage in a Docker image. Docker can fix portability problems on systems that we haven't yet supported (even Windows!), or had a chance to fix low-level issues on. However, Docker doesn't have a GUI interface. So to see the built PDF or intermediate data, it was necessary to copy the built data to the host system after every change, which is annoying during working on a project. It would also need two copies of the source: one in the host, one in the container. All these frustrations can be fixed with this new feature. To describe this scenario, README.md now has a new section titled "Only software environment in the Docker image". It explains step-by-step how you can make a Docker image to only host the built software environment. While your project's source, software tarballs and 'BDIR/analysis' directories are on your host operating system. It has been tested before this commit and works very nicely.
2021-01-07Removed all \new highlights after submission of reviewMohammad Akhlaghi-73/+70
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.
2021-01-07Minor copyedits in appendices, e.g. parenthesesBoud Roukema-5/+7
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.
2021-01-05Configuration: GNU Binutils linking bug on some systems fixedMohammad Akhlaghi-1/+1
Until now, when building GNU Binutils on GNU Linux operating systems, we would simply put a link to the host's core C library components (the '*crt*' files). However, the symbolic link wasn't "forced"! So if it already existed in the build directory, it would crash. With this commit a '-f' option has been added to the 'ln' command and this fixed the problem. This bug was reported by Zahra Sharbaf.
2021-01-05appendix.bbl is now included in make dist tarballMohammad Akhlaghi-5/+8
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.
2021-01-05Polished main paper and appendices after a full re-readMohammad Akhlaghi-210/+263
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.
2021-01-04Edits in the answers to the referee reportMohammad Akhlaghi-262/+305
Given the new appendix/supplement structure, it was necessary to go through the answers and correct them. I also generally edited them and added a top-level letter to the editors (to directly copy-paste into the webpage).
2021-01-04Imported recent updates in Maneage, no conflictsMohammad Akhlaghi-24/+70
There weren't any conflicts in this merge; either technical conflicts that can be found by Git, or logical conflicts (that will cause a crash in the project).
2021-01-04Building of Less program now uses patchelf to ensure good linkingMohammad Akhlaghi-0/+3
After correctly setting Less to depend on 'ncurses', I noticed its still not linking to Maneage's 'ncurses', but pointing to my host system's 'ncurses' (that happens to have the same version! So it would crash on a system with a different version). This shows that like some other software, we need to manually correct the RPATH inside Less. With this command, the necessary call to 'patchelf' has been added and with it, the installed 'less' command properly linked to Maneage's internal build of 'ncurses'.
2021-01-04README-hacking.md: edits and improvements to publication checklistMohammad Akhlaghi-23/+40
After going through the publication checklist, some edits were made to make things more clear. Also, an item was added to remind the project author that the commit hashes on the uploaded data files should be the same.
2021-01-04README.md: summary Dockerfile with all necessary lines in one stepMohammad Akhlaghi-0/+26
Until now, the description in 'README.md' to build the Dockerfile in 'README.md' had one item per line, thoroughly describing the reason behind that line. But in many cases, the user is already familiar with Docker (or has already read through the items) and just wants to have the Dockerfile ready fast. In these cases, all those extra explanations are annoying. With this commit, an item '0' has been added at the start of the item list for summary. It only contains the necessary Dockerfile contents with no extra explanation.
2021-01-04Building of less software depends on ncursesMohammad Akhlaghi-1/+1
Until now, the 'less' software package (used to view large files easily on the command-line and used by Git for things like 'git diff' or 'git log') only depended on 'patchelf' (which is a very low-level software). However, as Boud reported in bug #59811 [1], building less would crash with an error saying "Cannot find terminal libraries" in some systems (including the proposed Docker image of 'README.md' which I confirmed afterwards). Looking into the 'configure' script of 'less', I noticed that 'less' is actually just checking for some functions provided by the ncurses library! With this commit, 'less' depends on 'ncurses'. I was able to confirm that with this change, 'less' successfully builds within the Docker image. [1] https://savannah.nongnu.org/bugs/?59811
2021-01-04Edits on points raised by RaulMohammad Akhlaghi-10/+12
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.
2021-01-04Very minor corrections to the necessity appendixRaul Infante-Sainz-13/+18
With this commit, I have corrected some minor typos of this appendix. They are very minor corrections.
2021-01-04Minor corrections to the existing solutions appendixRaul Infante-Sainz-87/+104
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.
2021-01-03Spell check on main body and appendicesMohammad Akhlaghi-52/+44
I ran a simple Emacs spell check over the main body and the two appendices. All discovered typos have been fixed.
2021-01-03Minor corrections to the existing tools appendixRaul Infante-Sainz-138/+139
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).
2021-01-03Minor corrections to the main body textRaul Infante-Sainz-26/+26
With this commit, I had a look at the paper and correct some minor typos. When possible, I tried to simplify some phrases to have less number of words. To do that, I added some hypens when I considered it could be necessary/possible.
2021-01-03Updated copyrights of project-specific copyrightsMohammad Akhlaghi-10/+10
Having entered 2021, it was necessary to update the years of all the copyright statements.
2021-01-03Imported recent updates in Maneage, minor conflicts fixedMohammad Akhlaghi-126/+210
There were only three very small conflicts that have been fixed.
2021-01-03No links to main body in the appendices in --supplement modeMohammad Akhlaghi-9/+50
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.
2021-01-03Added Boud as copyright holder of supplement.texMohammad Akhlaghi-7/+8
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.
2021-01-03Minor copyeditingBoud Roukema-10/+10
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.
2021-01-03Cleaned abstract and Section II to fit word limitMohammad Akhlaghi-21/+18
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.
2021-01-03Added abstract for supplementMohammad Akhlaghi-1/+13
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.
2021-01-02Supplement (containing appendices) optionally built separatelyMohammad Akhlaghi-70/+214
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'.
2021-01-02./project make: new texclean targetMohammad Akhlaghi-1/+7
Until now there was only a 'clean' (to delete all files created during the 'make' phase) and the 'distclean' (to delete all files during configuration and make). But sometimes we don't want to delete all the files created during the full 'make' phase, we only want to delete the files that were created by LaTeX for building the paper. Witht this commit, a new target has been added for this job. You can now run the following command for this job: ./project make texclean Only the files in '$(BDIR)/tex/build' will be deleted (and the 'tikz' directory under that location is recreated, ready for a future build).
2021-01-02Copyright year updated in all source filesMohammad Akhlaghi-87/+87
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.