From 0c882a44e43a95761ffecdeebb57f2709e6f96e5 Mon Sep 17 00:00:00 2001 From: Raul Infante-Sainz Date: Mon, 14 Sep 2020 15:49:24 +0100 Subject: Checking Xcode installation for macOS systems Until now, during the configure step it was checked if the host Operative System were GNU/Linux, and if not, we assumed it is macOS. However, it can be any other different OS! With this commit, now we explicity check if the system is GNU/Linux or Darwin (macOS). If it is not any of them, a warning message says to the user that the host system is different from which we have checked so far (and invite to contact us if there is any problem). In addition to this, if the system is macOS, now it checks if Xcode is already installed in the host system. If it is not installed, a warning message informs the user to do that in case a problem/crash in the configure step occurs. We have found that it is convenient to have Xcode installed in order to avoid some problems. --- reproduce/software/shell/configure.sh | 61 ++++++++++++++++++++++++++++++++++- 1 file changed, 60 insertions(+), 1 deletion(-) diff --git a/reproduce/software/shell/configure.sh b/reproduce/software/shell/configure.sh index bc43540..8a30f1a 100755 --- a/reproduce/software/shell/configure.sh +++ b/reproduce/software/shell/configure.sh @@ -212,13 +212,31 @@ if [ x$kernelname = xLinux ]; then # Don't forget to add the respective C++ compiler below (leave 'cc' in # the end). c_compiler_list="gcc clang cc" -else +elif [ x$kernelname = xDarwin ]; then host_cc=1 on_mac_os=yes # Don't forget to add the respective C++ compiler below (leave 'cc' in # the end). c_compiler_list="clang gcc cc" +else + on_mac_os=no + cat < Date: Thu, 24 Sep 2020 02:15:40 +0100 Subject: Gnuastro's analysis configuration files removed Until now, the core Maneage branch included some configuration files for Gnuastro's programs. This was actually a remnant of the distant past when Maneage didn't actually build its own software and we had to rely on the host's software versions. This file contained the configuration files specific to Gnuastro for this project and also had a feature to avoid checking the host's own configuration files. However, we now build all our software ourselves with fixed configuration files (for the version that is being installed and its version is stored). So those extra configuration files were just extra and caused confusion and problems in some scenarios. With this commit, those extra files are now removed. Also, two small issues are also addressed in parallel with this commit: - When running './project make clean', the 'hardware-parameters.tex' macro file (which is created by './project configure' is not deleted. - The project title is now written into the default output's PDF's properties (through 'hypersetup' in 'tex/src/preamble-header.tex') through the LaTeX macro. All these issues were found and fixed with the help of Samane Raji. --- README-hacking.md | 8 ++-- .../analysis/config/gnuastro/astbuildprog.conf | 16 -------- .../analysis/config/gnuastro/astconvertt.conf | 33 ----------------- .../analysis/config/gnuastro/aststatistics.conf | 36 ------------------ reproduce/analysis/config/gnuastro/gnuastro.conf | 43 ---------------------- reproduce/analysis/make/initialize.mk | 7 +--- reproduce/software/shell/configure.sh | 1 - tex/src/preamble-header.tex | 4 +- 8 files changed, 7 insertions(+), 141 deletions(-) delete mode 100644 reproduce/analysis/config/gnuastro/astbuildprog.conf delete mode 100644 reproduce/analysis/config/gnuastro/astconvertt.conf delete mode 100644 reproduce/analysis/config/gnuastro/aststatistics.conf delete mode 100644 reproduce/analysis/config/gnuastro/gnuastro.conf diff --git a/README-hacking.md b/README-hacking.md index a598373..afa9a1d 100644 --- a/README-hacking.md +++ b/README-hacking.md @@ -1254,11 +1254,9 @@ for the benefit of others. - *Configuration files*: If your research uses special programs as part of the processing, put all their configuration files in a devoted directory (with the program's name) within - `reproduce/software/config`. Similar to the - `reproduce/software/config/gnuastro` directory (which is put in - Maneage as a demo in case you use GNU Astronomy Utilities). It is - much cleaner and readable (thus less buggy) to avoid mixing the - configuration files, even if there is no technical necessity. + `reproduce/software/config`. It is much cleaner and readable (thus + less buggy) to avoid mixing the configuration files, even if there is + no technical necessity. - **Contents**: It is good practice to follow the following diff --git a/reproduce/analysis/config/gnuastro/astbuildprog.conf b/reproduce/analysis/config/gnuastro/astbuildprog.conf deleted file mode 100644 index 7adb4d1..0000000 --- a/reproduce/analysis/config/gnuastro/astbuildprog.conf +++ /dev/null @@ -1,16 +0,0 @@ -# BuildProgram's configuration file depends on the build and is installed -# along with the rest of Gnuastro. So we'll set any specific configuration -# we want here, then import those. -# -# Copyright (C) 2018-2020 Mohammad Akhlaghi -# -# Copying and distribution of this file, with or without modification, are -# permitted in any medium without royalty provided the copyright notice and -# this notice are preserved. This file is offered as-is, without any -# warranty. - -# To keep the program's compiled excutable file, comment this line. -deletecompiled 1 - -# Import the built configuration file -config .local/etc/astbuildprog.conf \ No newline at end of file diff --git a/reproduce/analysis/config/gnuastro/astconvertt.conf b/reproduce/analysis/config/gnuastro/astconvertt.conf deleted file mode 100644 index 770ac39..0000000 --- a/reproduce/analysis/config/gnuastro/astconvertt.conf +++ /dev/null @@ -1,33 +0,0 @@ -# Default parameters (System) for ConvertType. -# ConvertType is part of GNU Astronomy Utitlies. -# -# Use the long option name of each parameter followed by a value. The name -# and value should be separated by atleast one white-space character (for -# example ` '[space], or tab). Lines starting with `#' are ignored. -# -# For more information, please run these commands: -# -# $ astconvertt --help # Full list of options, short doc. -# $ astconvertt -P # Print all options and used values. -# $ info astconvertt # All options and input/output. -# $ info gnuastro "Configuration files" # How to use configuration files. -# -# Copyright (C) 2018-2020 Mohammad Akhlaghi -# -# Copying and distribution of this file, with or without modification, are -# permitted in any medium without royalty provided the copyright notice and -# this notice are preserved. This file is offered as-is, without any -# warranty. - -# Input: - -# Output: - quality 100 - widthincm 10.0 - borderwidth 1 - output jpg - -# Flux: - invert 0 - -# Common options diff --git a/reproduce/analysis/config/gnuastro/aststatistics.conf b/reproduce/analysis/config/gnuastro/aststatistics.conf deleted file mode 100644 index 90f985d..0000000 --- a/reproduce/analysis/config/gnuastro/aststatistics.conf +++ /dev/null @@ -1,36 +0,0 @@ -# Default parameters (System) for Statistics. -# Statistics is part of GNU Astronomy Utitlies. -# -# Use the long option name of each parameter followed by a value. The name -# and value should be separated by atleast one white-space character (for -# example ` '[space], or tab). Lines starting with `#' are ignored. -# -# For more information, please run these commands: -# -# $ aststatistics --help # Full list of options, short doc. -# $ aststatistics -P # Print all options and used values. -# $ info aststatistics # All options and input/output. -# $ info gnuastro "Configuration files" # How to use configuration files. -# -# Copyright (C) 2018-2020 Mohammad Akhlaghi -# -# Copying and distribution of this file, with or without modification, are -# permitted in any medium without royalty provided the copyright notice and -# this notice are preserved. This file is offered as-is, without any -# warranty. - -# Input image: - -# Sky and its STD settings - khdu 1 - meanmedqdiff 0.005 - outliersigma 10 - outliersclip 3,0.2 - smoothwidth 3 - sclipparams 3,0.1 - -# Histogram and CFP settings - numasciibins 70 - asciiheight 10 - numbins 100 - mirrordist 1.5 diff --git a/reproduce/analysis/config/gnuastro/gnuastro.conf b/reproduce/analysis/config/gnuastro/gnuastro.conf deleted file mode 100644 index 82cb100..0000000 --- a/reproduce/analysis/config/gnuastro/gnuastro.conf +++ /dev/null @@ -1,43 +0,0 @@ -# Default values for the common options to all the programs in GNU -# Astronomy Utitlies. -# -# IMPORTANT NOTE: The `lastconfig' option is very important in a -# reproducible environment. Because we don't want any of Gnuastro's -# programs to go into an un-controlled environment (user or system wide -# configuration files). -# -# The rest of this configuration file is taken from the default Gnuastro -# configuration from its source (`bin/gnuastro.conf'). -# -# Copyright (C) 2018-2020 Mohammad Akhlaghi -# -# Copying and distribution of this file, with or without modification, are -# permitted in any medium without royalty provided the copyright notice and -# this notice are preserved. This file is offered as-is, without any -# warranty. - -# Local project settings (`config' has to be before `lastconfig'). - config .gnuastro/gnuastro-local.conf - lastconfig 1 - -# Input: - hdu 1 - ignorecase 1 - searchin name - stdintimeout 100000 - -# Tessellation - tilesize 30,30 - numchannels 1,1 - remainderfrac 0.1 - workoverch 0 - interpmetric radial - interpnumngb 9 - interponlyblank 0 - -# Output: - tableformat fits-binary - -# Operating mode - quietmmap 0 - minmapsize 2000000000 diff --git a/reproduce/analysis/make/initialize.mk b/reproduce/analysis/make/initialize.mk index fca75f5..3a35ece 100644 --- a/reproduce/analysis/make/initialize.mk +++ b/reproduce/analysis/make/initialize.mk @@ -38,9 +38,6 @@ mtexdir = $(texdir)/macros bashdir = reproduce/analysis/bash pconfdir = reproduce/analysis/config installdir = $(BDIR)/software/installed -# --------- Delete for no Gnuastro --------- -gconfdir = reproduce/analysis/config/gnuastro -# ------------------------------------------ @@ -239,7 +236,7 @@ clean: clean-mmap # features like ignoring the listing of a file with `!()' that we # are using afterwards. shopt -s extglob - rm -rf $(BDIR)/tex/macros/!(dependencies.tex|dependencies-bib.tex) + rm -rf $(BDIR)/tex/macros/!(dependencies.tex|dependencies-bib.tex|hardware-parameters.tex) rm -rf $(BDIR)/!(software|tex) $(BDIR)/tex/!(macros|$(texbtopdir)) rm -rf $(BDIR)/tex/build/!(tikz) $(BDIR)/tex/build/tikz/* rm -rf $(BDIR)/software/preparation-done.mk @@ -254,8 +251,8 @@ distclean: clean # `rm' program. So for this recipe, we'll use the host system's # `rm', not our own. $$sys_rm -rf $(BDIR) + $$sys_rm -f $(pconfdir)/LOCAL.conf $$sys_rm -f Makefile .gnuastro .local .build - $$sys_rm -f $(pconfdir)/LOCAL.conf $(gconfdir)/gnuastro-local.conf diff --git a/reproduce/software/shell/configure.sh b/reproduce/software/shell/configure.sh index 8a30f1a..646f101 100755 --- a/reproduce/software/shell/configure.sh +++ b/reproduce/software/shell/configure.sh @@ -1257,7 +1257,6 @@ ln -s "$tikzdir" tex/tikz # --------- Delete for no Gnuastro --------- rm -f .gnuastro -ln -s "$topdir"/reproduce/analysis/config/gnuastro .gnuastro # ------------------------------------------ diff --git a/tex/src/preamble-header.tex b/tex/src/preamble-header.tex index 9353afc..42bb409 100644 --- a/tex/src/preamble-header.tex +++ b/tex/src/preamble-header.tex @@ -73,8 +73,8 @@ \hypersetup { pdfauthor={YOUR NAME}, - pdfsubject={A SHORT DESCRIPTION OF THE WORK}, - pdftitle={THE TITLE OF THIS PROJECT}, + pdfsubject={\projecttitle}, + pdftitle={\projecttitle}, pdfkeywords={SOME, KEYWORDS, FOR, THE, PDF} } -- cgit v1.2.1 From b677efb04387964f6a143fe891ca3351e664ecf9 Mon Sep 17 00:00:00 2001 From: Mohammad Akhlaghi Date: Fri, 2 Oct 2020 01:12:35 +0100 Subject: TexLive's xstring package is now necessary After a fresh build of Maneage with a newly downloaded TeXLive, I noticed that it is complaining about not finding 'xstring.sty', apparently some package that depeneded on it is no longer including it itself! It is thus now added to the packages that are built by Maneage's TeXLive. --- reproduce/software/config/texlive-packages.conf | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/reproduce/software/config/texlive-packages.conf b/reproduce/software/config/texlive-packages.conf index c53e170..ff0664e 100644 --- a/reproduce/software/config/texlive-packages.conf +++ b/reproduce/software/config/texlive-packages.conf @@ -16,9 +16,9 @@ # the basic installation scheme that we used to install tlmgr, they will be # ignored in the `tlmgr install' command, but will be used later when we # want their versions. -texlive-packages = tex fancyhdr ec newtx fontaxes xkeyval etoolbox xcolor \ - setspace caption footmisc datetime fmtcount titlesec \ - preprint ulem biblatex biber logreq pgf pgfplots fp \ - courier tex-gyre txfonts times csquotes kastrup \ +texlive-packages = tex fancyhdr ec newtx fontaxes xkeyval etoolbox xstring \ + xcolor setspace caption footmisc datetime fmtcount \ + titlesec preprint ulem biblatex biber logreq pgf pgfplots \ + fp courier tex-gyre txfonts times csquotes kastrup \ trimspaces pdftexcmds pdfescape letltxmacro bitset \ mweights -- cgit v1.2.1 From 04bda5a85b879523188579c1a2bb8af8907d85f8 Mon Sep 17 00:00:00 2001 From: Boud Roukema Date: Fri, 9 Oct 2020 12:33:58 +0200 Subject: Update README-hacking.md with elaphrocentre ArXiv:2010.03742 This commit updates README-hacking.md with the URIs for the 'elaphrocentre' galaxy formation pipeline paper arXiv:2010.03742. This makes three papers currently in the peer review pipeline: arXiv:2006.03018, arXiv:2007.11779, and arXiv:2010.03742, each chronologically corresponding to various stages of the review process. --- README-hacking.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/README-hacking.md b/README-hacking.md index afa9a1d..8d737ab 100644 --- a/README-hacking.md +++ b/README-hacking.md @@ -180,13 +180,22 @@ evolving rapidly, so some details will differ between the different versions. The more recent papers will tend to be the most useful as good working examples. - - Roukema ([2020](https://arxiv.org/abs/2007.11779), + - Peper & Roukema ([2020](https://arxiv.org/abs/2010.03742), + arXiv:2010.03742): The live version of the controlled source is [at + Codeberg](https://codeberg.org/boud/elaphrocentre); the main input + dataset, a software snapshot, the software tarballs, the project + outputs and editing history are available at + [zenodo.4062461](https://zenodo.org/record/4062461); and the + archived git history is available at + [swh:1:dir:c4770e81288f340083dd8aa9fe017103c4eaf476](https://archive.softwareheritage.org/swh:1:dir:c4770e81288f340083dd8aa9fe017103c4eaf476). + + - Roukema ([2020](https://arxiv.org/abs/2007.11779), arXiv:2007.11779): The live version of the controlled source is [at Codeberg](https://codeberg.org/boud/subpoisson); the main input dataset, a software snapshot, the software tarballs, the project outputs and editing history are available at [zenodo.3951152](https://zenodo.org/record/3951152); and the - archived git history is also available at + archived git history is available at [swh:1:dir:fcc9d6b111e319e51af88502fe6b233dc78d5166](https://archive.softwareheritage.org/swh:1:dir:fcc9d6b111e319e51af88502fe6b233dc78d5166). - Akhlaghi et al. ([2020](https://arxiv.org/abs/2006.03018), -- cgit v1.2.1 From 2b39a67c571d1b6ea2375f65be6bf55831e4eaac Mon Sep 17 00:00:00 2001 From: Mohammad Akhlaghi Date: Sun, 18 Oct 2020 14:37:16 +0100 Subject: Recipes for final initialize and verify targets not on stdout The LaTeX macro files for these two subMakefiles are created on every run of './project make'. So their commands are also printed every time and hardly ever will a normal user want to modify or change these. So to avoid populating the standard output of a Maneaged project with all these extra lines every time (possibly getting mixed with the important analysis or LaTeX outputs), an '@' has been placed at the start of the recipes. With an '@' at the start of the recipe, Make is instructed to not print the commands it wants to run in the standard output. --- reproduce/analysis/make/initialize.mk | 7 +++++-- reproduce/analysis/make/verify.mk | 8 ++++++-- 2 files changed, 11 insertions(+), 4 deletions(-) diff --git a/reproduce/analysis/make/initialize.mk b/reproduce/analysis/make/initialize.mk index 3a35ece..7217f0c 100644 --- a/reproduce/analysis/make/initialize.mk +++ b/reproduce/analysis/make/initialize.mk @@ -478,8 +478,11 @@ print-copyright = \ # actually exists, it is also aded as a `.PHONY' target above. $(mtexdir)/initialize.tex: | $(mtexdir) - # Version and title of project. - echo "\newcommand{\projecttitle}{$(metadata-title)}" > $@ + # Version and title of project. About the starting '@': since these + # commands are run every time with './project make', it is annoying + # to print them on the standard output every time. With the '@', + # make will not print the commands that it runs in this recipe. + @echo "\newcommand{\projecttitle}{$(metadata-title)}" > $@ echo "\newcommand{\projectversion}{$(project-commit-hash)}" >> $@ # Calculate the latest Maneage commit used to build this diff --git a/reproduce/analysis/make/verify.mk b/reproduce/analysis/make/verify.mk index b3d62f2..fc76b96 100644 --- a/reproduce/analysis/make/verify.mk +++ b/reproduce/analysis/make/verify.mk @@ -114,8 +114,12 @@ verify-dep = $(subst verify,,$(subst paper,,$(makesrc))) verify-check = $(subst initialize,,$(verify-dep)) $(mtexdir)/verify.tex: $(foreach s, $(verify-dep), $(mtexdir)/$(s).tex) - # Make sure that verification is actually requested. - if [ x"$(verify-outputs)" = xyes ]; then + # Make sure that verification is actually requested, the '@' at the + # start of the recipe is added so Make doesn't print the commands + # on the standard output because this recipe is run on every call + # to the project and can be annoying (get mixed in the middle of + # the analysis outputs or the LaTeX outputs). + @if [ x"$(verify-outputs)" = xyes ]; then # Make sure the temporary output doesn't exist (because we want # to append to it). We are making a temporary output target so if -- cgit v1.2.1 From 9cfb8d30a7e0fc92dc60f4dad30efc7231b363dc Mon Sep 17 00:00:00 2001 From: Mohammad Akhlaghi Date: Fri, 13 Nov 2020 19:11:18 +0000 Subject: README.md: added commands to delete all Docker images Until now we had described the basic commands on how to create and use Docker images, but we hadn't mentioned how you can delete them. With this commit the commands necessary for deleting Docker images have also been added at the bottom of the section on Docker. --- README.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/README.md b/README.md index aadfcef..e9de293 100644 --- a/README.md +++ b/README.md @@ -414,6 +414,18 @@ command). docker cp CONTAINER:/file/path/within/container /host/path/target ``` +#### Deleting all Docker images + +After doing your tests/work, you may no longer need the multi-gigabyte +files images, so its best to just delete them. To do this, just run the two +commands below to first stop all running containers and then to delete all +the images: + +```shell +docker ps -a -q | xargs docker rm +docker images -a -q | xargs docker rmi -f +``` + -- cgit v1.2.1 From fcc77a774f2e34bd9ed6ca4ea0f5577cba967f58 Mon Sep 17 00:00:00 2001 From: Mohammad Akhlaghi Date: Sun, 15 Nov 2020 13:28:57 +0000 Subject: Building final PDF: pdf-build-final has to be given an explicit yes Until now, when the 'pdf-build-final' configuration variable (defined in 'reproduce/analysis/config/pdf-build.conf') was given any string a PDF would be built. This was very confusing, because people could put a 'no' and the PDF would still be built! With this commit, only when this variable has a value of 'yes' will the PDF be built. If given any other string (or no string at all), it will not produce a PDF. This issue was reported by Zahra Sharbaf. --- reproduce/analysis/config/pdf-build.conf | 10 +++++----- reproduce/analysis/make/paper.mk | 16 ++++++++-------- reproduce/analysis/make/top-make.mk | 4 ++-- 3 files changed, 15 insertions(+), 15 deletions(-) diff --git a/reproduce/analysis/config/pdf-build.conf b/reproduce/analysis/config/pdf-build.conf index e2d59cc..48585b4 100644 --- a/reproduce/analysis/config/pdf-build.conf +++ b/reproduce/analysis/config/pdf-build.conf @@ -3,13 +3,13 @@ # # During the project's early phases, it is usually not necessary to build # the PDF file (which makes a lot of output lines on the command-line and -# can make it hard to find the commands and possible errors (and their -# outputs). Also, in some cases, only the produced results may be of +# can make it hard to find the analysis commands and possible errors (and +# their outputs). Also, in some cases, only the produced results may be of # interest and not the final PDF, so LaTeX (and its necessary packages) may -# not be installed. +# not be installed at all. # -# If this variable is given any string, a PDF will be made with -# LaTeX. Otherwise, a notice will just printed that for now, no PDF will be +# If 'pdf-build-final' is given the value 'yes', a PDF will be made with +# LaTeX. Otherwise, a notice will just printed that, no PDF will be # created. # # Copyright (C) 2018-2020 Mohammad Akhlaghi diff --git a/reproduce/analysis/make/paper.mk b/reproduce/analysis/make/paper.mk index 906b4d9..28f44a9 100644 --- a/reproduce/analysis/make/paper.mk +++ b/reproduce/analysis/make/paper.mk @@ -37,14 +37,14 @@ # completed. # # Note that if you don't want the final PDF and just want the processing -# and file outputs, you can remove the value of `pdf-build-final' in -# `reproduce/analysis/config/pdf-build.conf'. +# and file outputs, you can give any value other than 'yes' to +# 'pdf-build-final' in `reproduce/analysis/config/pdf-build.conf'. $(mtexdir)/project.tex: $(mtexdir)/verify.tex # If no PDF is requested, or if LaTeX isn't available, don't # continue to building the final PDF. Otherwise, merge all the TeX # macros into one for building the PDF. - @if [ -f .local/bin/pdflatex ] && [ x"$(pdf-build-final)" != x ]; then + @if [ -f .local/bin/pdflatex ] && [ x"$(pdf-build-final)" = xyes ]; then # Put a LaTeX input command for all the necessary macro files. # 'hardware-parameters.tex' is created in 'configure.sh'. @@ -59,11 +59,11 @@ $(mtexdir)/project.tex: $(mtexdir)/verify.tex echo "LaTeX-built PDF paper will not be built." echo if [ x$(more-on-building-pdf) = x1 ]; then - echo "To do so, make sure you have LaTeX within the project (you" - echo "can check by running './.local/bin/latex --version'), _AND_" - echo "make sure that the 'pdf-build-final' variable has a value." - echo "'pdf-build-final' is defined in: " - echo "'reproduce/analysis/config/pdf-build.conf'." + echo "To build the PDF, make sure you have LaTeX within the " + echo "project (you can check by running " + echo "'./.local/bin/latex --version'), _AND_ make sure that " + echo "the 'pdf-build-final' variable has a value of 'yes', it " + echo "is defined in: 'reproduce/analysis/config/pdf-build.conf'." echo echo "If you don't have LaTeX within the project, please re-run" echo "'./project configure -e' when you have internet access." diff --git a/reproduce/analysis/make/top-make.mk b/reproduce/analysis/make/top-make.mk index 9a26f22..140b026 100644 --- a/reproduce/analysis/make/top-make.mk +++ b/reproduce/analysis/make/top-make.mk @@ -62,8 +62,8 @@ include reproduce/software/config/LOCAL.conf # ----------------------------- # # If you are just interested in the processing and don't want to build the -# PDF, you can skip the creatation of the final PDF by removing the value -# of `pdf-build-final' in `reproduce/analysis/config/pdf-build.conf'. +# PDF, you can skip the creation of the final PDF by giving a value of +# `yes' to `pdf-build-final' in `reproduce/analysis/config/pdf-build.conf'. ifeq (x$(reproducible_paper_group_name),x$(GROUP-NAME)) all: paper.pdf else -- cgit v1.2.1 From c312f4e0e826e292d753c0d19fd5f96ed351fb94 Mon Sep 17 00:00:00 2001 From: Mohammad Akhlaghi Date: Sat, 28 Nov 2020 22:18:36 +0000 Subject: README-hacking.md: updated paper to cite for using Maneage Until now, we were asking the users of Maneage to cite the first paper that used its primoridal version (arXiv:1505:01664). But there is now a paper that fully describes the concept (arXiv:2006.03018). With this commit, in the 'citation' section of 'README-hacking.md' we now ask to cite the new paper. --- README-hacking.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/README-hacking.md b/README-hacking.md index 8d737ab..d944fb0 100644 --- a/README-hacking.md +++ b/README-hacking.md @@ -249,10 +249,9 @@ working examples. Citation -------- -A paper to fully describe Maneage has been submitted. Until then, if you -used it in your work, please cite the paper that implemented its first -version: Akhlaghi & Ichikawa -([2015](http://adsabs.harvard.edu/abs/2015ApJS..220....1A), ApJS, 220, 1). +If you use Maneage in your project please cite Akhlaghi et +al. ([2020](https://arxiv.org/abs/2006.03018), arXiv:2006.03018). It has +been submitted and is under peer review. Also, when your paper is published, don't forget to add a notice in your own paper (in coordination with the publishing editor) that the paper is -- cgit v1.2.1 From 6ca2fbf925d14fff862889840913e3c89ea8048a Mon Sep 17 00:00:00 2001 From: Mohammad Akhlaghi Date: Mon, 30 Nov 2020 23:50:38 +0000 Subject: IMPORTANT: organizational improvements in Maneage TeX sources 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. --- paper.tex | 266 +++++++++++------------------ project | 17 +- reproduce/analysis/make/paper.mk | 17 +- tex/src/preamble-header.tex | 89 ---------- tex/src/preamble-maneage-default-style.tex | 215 +++++++++++++++++++++++ tex/src/preamble-maneage.tex | 35 ++++ tex/src/preamble-necessary.tex | 70 -------- tex/src/preamble-project.tex | 75 ++++++++ tex/src/preamble-style.tex | 152 ----------------- 9 files changed, 450 insertions(+), 486 deletions(-) delete mode 100644 tex/src/preamble-header.tex create mode 100644 tex/src/preamble-maneage-default-style.tex create mode 100644 tex/src/preamble-maneage.tex delete mode 100644 tex/src/preamble-necessary.tex create mode 100644 tex/src/preamble-project.tex delete mode 100644 tex/src/preamble-style.tex diff --git a/paper.tex b/paper.tex index 3a2c2f6..ac61cad 100644 --- a/paper.tex +++ b/paper.tex @@ -12,46 +12,33 @@ %% `tex/preamble-pgfplots.tex' for more. \newcommand{\makepdf}{} -%% (OPTIONAL) CONVENIENCE VARIABLE: Only relevant when -%% 'tex/src/preamble-necessary.tex' is included (in particular the small -%% patch relating to '\highlightchanges'). In there, Maneage defines two -%% macros: `\tonote' and `\new'. When '\highlightchanges' is defined (value -%% is irrelevant), the text in those two macros becomes colored (in the -%% former, the text becomes dark red, in the latter it becomes dark -%% green). When not defined, text in the former isn't printed in the output -%% at all, and text in the latter becomes the same color as the rest of the -%% text. This is useful in cases that you need to distribute drafts and you -%% want to hightlight the new parts and add notes in the middle of the text -%% only for discussion, and build a clean PDF without any such highlights -%% without modifying the text. -\newcommand{\highlightchanges}{} - -%% VALUES FROM ANALYSIS (NUMBERS AND STRINGS): these are automatically -%% generated by the analysis phase of the project. The files loaded by -%% 'project.tex' only contain macro definitions (with '\newcommand') and -%% nothing else. So they won't interfere with any LaTeX style and can be -%% safely used in any pre-defined style. +%% VALUES FROM ANALYSIS (NUMBERS AND STRINGS): this file is automatically +%% generated at the end of the processing and includes LaTeX macros +%% (defined with '\newcommand') for various processing outputs to be used +%% within the paper. \input{tex/build/macros/project.tex} -%% CUSTOM PREAMBLES FOR DEMO: You can remove them if you are using a -%% specific journal style, or don't need features like BibLaTeX (advanced -%% bibliography management) or PGFPlots (for drawing plots within LaTeX -%% directly from tables of data). If you don't need them, you can also -%% delete their files from your branch to keep the 'tex/src' directory on -%% your branch clean. -\input{tex/src/preamble-style.tex} -\input{tex/src/preamble-header.tex} -\input{tex/src/preamble-biblatex.tex} -\input{tex/src/preamble-pgfplots.tex} -\input{tex/src/preamble-necessary.tex} +%% MANEAGE-ONLY PREAMBLE: this file contains LaTeX constructs that are +%% provided by Maneage (for example enabling or disabling of highlighting +%% from the './project' script). They are not style-related. +\input{tex/src/preamble-maneage.tex} + +%% PROJECT-SPECIFIC PREAMBLE: This is where you can include any LaTeX +%% setting for customizing your project. +\input{tex/src/preamble-project.tex} + + + + %% PROJECT TITLE: The project title should also be printed as metadata in %% all output files. To avoid inconsistancy caused by manually typing it, %% the title is defined with other core project metadata in %% 'reproduce/analysis/config/metadata.conf'. That value is then written in -%% the '\projectitle' LaTeX macro by -%% 'reproduce/analysis/make/initialize.mk' and is directly used here. So -%% please set your project's title in 'metadata.conf' (ideally with other +%% the '\projectitle' LaTeX macro which is available in 'project.tex' (that +%% was loaded above). +% +%% Please set your project's title in 'metadata.conf' (ideally with other %% basic project information) and re-run the project to have your new %% title. If you later use a different LaTeX style, please use the same %% '\projectitle' in it (after importing 'tex/build/macros/project.tex' @@ -62,7 +49,8 @@ %% including author name, or paper info, see %% `tex/src/preamble-header.tex'. Note that if you plan to use a journal's %% LaTeX style file, you will probably set the authors in a different way, -%% feel free to change them here, this part is not related to the analysis. +%% feel free to change them here, this is just basic style and varies from +%% project to project. \author[1]{Your name} \author[2]{Coauthor one} \author[1,3]{Coauthor two} @@ -86,25 +74,13 @@ %% Project abstract and keywords. \includeabstract{ - - Welcome to Maneage (\emph{Man}aging data lin\emph{eage}) and reproducible - papers/projects, for a review of the basics of this system, please see - \citet{maneage}. You are now ready to configure Maneage and implement - your own research in this framework. Maneage contains almost all the - elements that you will need in a research project, and adding any missing - parts is very easy once you become familiar with it. For example it - already has steps to downloading of raw data and necessary software - (while verifying them with their checksums), building the software, and - processing the data with the software in a highly-controlled - environment. But Maneage is not just for the analysis of your project, - you will also write your paper in it (by replacing this text in - \texttt{paper.tex}): including this abstract, figures and - bibliography. If you design your project with Maneage's infra-structure, - don't forget to add a notice and clearly let the readers know that your - work is reproducible, we should spread the word and show the world how - useful reproducible research is for the sciences, also don't forget to - cite and acknowledge it so we can continue developing it. This PDF was - made with Maneage, commit \projectversion{}. + Welcome to Maneage (\emph{Man}aging data lin\emph{eage}) and reproducible papers/projects, for a review of the basics of this system, please see \citet{maneage}. + You are now ready to configure Maneage and implement your own research in this framework. + Maneage contains almost all the elements that you will need in a research project, and adding any missing parts is very easy once you become familiar with it. + For example it already has steps to downloading of raw data and necessary software (while verifying them with their checksums), building the software, and processing the data with the software in a highly-controlled environment. + But Maneage is not just for the analysis of your project, you will also write your paper in it (by replacing this text in \texttt{paper.tex}): including this abstract, figures and bibliography. + If you design your project with Maneage's infra-structure, don't forget to add a notice and clearly let the readers know that your work is reproducible, we should spread the word and show the world how useful reproducible research is for the sciences, also don't forget to cite and acknowledge it so we can continue developing it. + This PDF was made with Maneage, commit \projectversion{}. \vspace{0.25cm} @@ -123,60 +99,39 @@ %% Start of main body. \section{Congratulations!} -Congratulations on running the raw template project! You can now follow the -``Customization checklist'' in the \texttt{README-hacking.md} file, -customize this template and start your exciting research project over -it. You can always merge Maneage back into your project to improve its -infra-structure and leaving your own project intact. If you haven't already -read \citet{maneage}, please do so before continuing, it isn't long -(just 7 pages). - -While you are writing your paper, just don't forget to \emph{not} use -numbers or fixed strings (for example database urls like \url{\wfpctwourl}) -directly within your \LaTeX{} source. Put them in configuration files and -after using them in the analysis, pass them into the \LaTeX{} source -through macros in the same subMakefile that used them. For some already -published examples, please see -\citet{maneage}\footnote{\url{https://gitlab.com/makhlaghi/maneage-paper}}, -\citet{infantesainz20}\footnote{\url{https://gitlab.com/infantesainz/sdss-extended-psfs-paper}} -and -\citet{akhlaghi19}\footnote{\url{https://gitlab.com/makhlaghi/iau-symposium-355}}. Working -in this way, will let you focus clearly on your science and not have to -worry about fixing this or that number/name in the text. - -Once your project is ready for publication, there is also a ``Publication -checklist'' in \texttt{README-hacking.md} that will guide you in the steps -to do for making your project as FAIR as possible (Findable, Accessibile, -Interoperable, and Reusable). - -The default \LaTeX{} structure within Maneage also has two \LaTeX{} macros -for easy marking of text within your document as \emph{new} and -\emph{notes}. For example, \new{this text has been marked as \texttt{new}.} -\tonote{While this one is marked as \texttt{tonote}.} Please try commenting -the line that defines \texttt{highlightchanges} in \texttt{paper.tex} (by -adding a `\texttt{\%}' at the start of the line or simply deleting the -line). You will then notice that the line that was marked as \texttt{new} -will become black (totally blend in with the rest of the text) and the one -marked \texttt{tonote} will not be in the final PDF. You can thus use -\texttt{highlightchanges} to easily make copies of your research for -existing coauthors (who are just interested in the new parts or notes) and -new co-authors (who don't want to be distracted by these issues in their -first time reading). - -Figure \ref{squared} shows a simple plot as a demonstration of creating -plots within \LaTeX{} (using the {\small PGFP}lots package). The minimum -value in this distribution is $\deletememin$, and $\deletememax$ is the -maximum. Take a look into the \LaTeX{} source and you'll see these numbers -are actually macros that were calculated from the same dataset (they will -change if the dataset, or function that produced it, changes). - -The individual {\small PDF} file of Figure \ref{squared} is available under -the \texttt{tex/tikz/} directory of your build directory. You can use this -PDF file in other contexts (for example in slides showing your progress or -after publishing the work). If you want to directly use the {\small PDF} -file in the figure without having to let {\small T}i{\small KZ} decide if -it should be remade or not, you can also comment the \texttt{makepdf} macro -at the top of this \LaTeX{} source file. +Congratulations on running the raw template project! You can now follow the ``Customization checklist'' in the \texttt{README-hacking.md} file, customize this template and start your exciting research project over it. +You can always merge Maneage back into your project to improve its infra-structure and leaving your own project intact. +If you haven't already read \citet{maneage}, please do so before continuing, it isn't long (just 7 pages). + +While you are writing your paper, just don't forget to \emph{not} use numbers or fixed strings (for example database urls like \url{\wfpctwourl}) directly within your \LaTeX{} source. +Put them in configuration files and after using them in the analysis, pass them into the \LaTeX{} source through macros in the same subMakefile that used them. +For some already published examples, please see \citet{maneage}\footnote{\url{https://gitlab.com/makhlaghi/maneage-paper}}, \citet{infantesainz20}\footnote{\url{https://gitlab.com/infantesainz/sdss-extended-psfs-paper}} and \citet{akhlaghi19}\footnote{\url{https://gitlab.com/makhlaghi/iau-symposium-355}}. +Working in this way, will let you focus clearly on your science and not have to worry about fixing this or that number/name in the text. + +Once your project is ready for publication, there is also a ``Publication checklist'' in \texttt{README-hacking.md} that will guide you in the steps to do for making your project as FAIR as possible (Findable, Accessibile, Interoperable, and Reusable). + +The default \LaTeX{} structure within Maneage also has two \LaTeX{} macros for easy marking of text within your document as \emph{new} and \emph{notes}. +To activate them, please use the \texttt{--highlight-new} or \texttt{--highlight-notes} options with \texttt{./project make}. + +For example if you run \texttt{./project make --highlight-new}, then \new{this text (that has been marked as \texttt{new}) will show up as green in the final PDF}. +If you run \texttt{./project make --highlight-notes} then you will see a note following this sentence that is written in red and has square brackets around it (it is invisible without this option). +\tonote{This text is written within a \texttt{tonote} and is invisible without \texttt{--highlight-notes}.} +You can also use these two options together to both highlight the new parts and add notes within the text. + +Another thing you may notice from the \LaTeX{} source of this default paper is there is one line per sentence (and one sentence in a line). +Of course, as with everything else in Maneage, you are free to use any format that you are most comfortable with. +The reason behind this choice is that this source is under Git version control and that Git also primarily works on lines. +In this way, when a change in a setence is made, git will only highlight/color that line/sentence we have found that this helps a lot in viewing the changes. +Also, this format helps in reminding the author when the sentence is getting too long! +Here is a tip when looking at the changes of narrative document in Git: use the \texttt{--word-diff} option (for example \texttt{git diff --word-diff}, you can also use it with \texttt{git log}). + +Figure \ref{squared} shows a simple plot as a demonstration of creating plots within \LaTeX{} (using the {\small PGFP}lots package). +The minimum value in this distribution is $\deletememin$, and $\deletememax$ is the maximum. +Take a look into the \LaTeX{} source and you'll see these numbers are actually macros that were calculated from the same dataset (they will change if the dataset, or function that produced it, changes). + +The individual {\small PDF} file of Figure \ref{squared} is available under the \texttt{tex/tikz/} directory of your build directory. +You can use this PDF file in other contexts (for example in slides showing your progress or after publishing the work). +If you want to directly use the {\small PDF} file in the figure without having to let {\small T}i{\small KZ} decide if it should be remade or not, you can also comment the \texttt{makepdf} macro at the top of this \LaTeX{} source file. \begin{figure}[t] \includetikz{delete-me-squared}{width=\linewidth} @@ -185,57 +140,39 @@ at the top of this \LaTeX{} source file. demonstration.} \end{figure} -Figure \ref{image-histogram} is another demonstration of showing images -(datasets) using PGFPlots. It shows a small crop of an image from the -Wide-Field Planetary Camera 2 (that was installed on the Hubble Space -Telescope from 1993 to 2009). As another more realistic demonstration of -reporting results with Maneage, here we report that the mean pixel value in -that image is $\deletemewfpctwomean$ and the median is -$\deletemewfpctwomedian$. The skewness in the histogram of Figure -\ref{image-histogram}(b) explains this difference between the mean and -median. The dataset is visualized here as a black and white image using the -\textsf{Convert\-Type} program of GNU Astronomy Utilities (Gnuastro). The -histogram and basic statstics were generated with Gnuastro's -\textsf{Statistics} program. - -{\small PGFP}lots\footnote{\url{https://ctan.org/pkg/pgfplots}} is a great -tool to build the plots within \LaTeX{} and removes the necessity to add -further dependencies, just to create the plots. There are high-level -libraries like Matplotlib which also generate plots. However, the problem -is that they require \emph{many} dependencies, for example see Figure 1 of -\citet{alliez19}. Installing these dependencies from source, is not easy -and will harm the reproducibility of your paper in the future. - -Furthermore, since {\small PGFP}lots builds the plots within \LaTeX{}, it -respects all the properties of your text (for example line width and fonts -and etc). Therefore the final plot blends in your paper much more -nicely. It also has a wonderful -manual\footnote{\url{http://mirrors.ctan.org/graphics/pgf/contrib/pgfplots/doc/pgfplots.pdf}}. +Figure \ref{image-histogram} is another demonstration of showing images (datasets) using PGFPlots. +It shows a small crop of an image from the Wide-Field Planetary Camera 2 (that was installed on the Hubble Space Telescope from 1993 to 2009). +As another more realistic demonstration of reporting results with Maneage, here we report that the mean pixel value in that image is $\deletemewfpctwomean$ and the median is $\deletemewfpctwomedian$. +The skewness in the histogram of Figure \ref{image-histogram}(b) explains this difference between the mean and median. +The dataset is visualized here as a black and white image using the \textsf{Convert\-Type} program of GNU Astronomy Utilities (Gnuastro). +The histogram and basic statstics were generated with Gnuastro's \textsf{Statistics} program. + +{\small PGFP}lots\footnote{\url{https://ctan.org/pkg/pgfplots}} is a great tool to build the plots within \LaTeX{} and removes the necessity to add further dependencies, just to create the plots. +There are high-level libraries like Matplotlib which also generate plots. +However, the problem is that they require \emph{many} dependencies, for example see Figure 1 of \citet{alliez19}. +Installing these dependencies from source, is not easy and will harm the reproducibility of your paper in the future. + +Furthermore, since {\small PGFP}lots builds the plots within \LaTeX{}, it respects all the properties of your text (for example line width and fonts and etc). +Therefore the final plot blends in your paper much more nicely. +It also has a wonderful manual\footnote{\url{http://mirrors.ctan.org/graphics/pgf/contrib/pgfplots/doc/pgfplots.pdf}}. \begin{figure}[t] \includetikz{delete-me-image-histogram}{width=\linewidth} - \captionof{figure}{\label{image-histogram} (a) An example image - of the Wide-Field Planetary Camera 2, on board the Hubble Space - Telescope from 1993 to 2009. This is one of the sample images from the - FITS standard webpage, kept as examples for this file format. (b) - Histogram of pixel values in (a).} + \captionof{figure}{\label{image-histogram} (a) An example image of the Wide-Field Planetary Camera 2, on board the Hubble Space Telescope from 1993 to 2009. + This is one of the sample images from the FITS standard webpage, kept as examples for this file format. + (b) Histogram of pixel values in (a).} \end{figure} \section{Notice and citations} -To encourage other scientists to publish similarly reproducible papers, -please add a notice close to the start of your paper or in the end of the -abstract clearly mentioning that your work is fully reproducible. One -convention we have adopted until now is to put the Git checkum of the -project as the last word of the abstract, for example see -\citet{akhlaghi19}, \citet{infantesainz20} and \citet{maneage} - -Finally, don't forget to cite \citet{maneage} and acknowledge the -funders mentioned below. Otherwise we won't be able to continue working on -Maneage. Also, just as another reminder, before publication, don't forget -to follow the ``Publication checklist'' of \texttt{README-hacking.md}. +To encourage other scientists to publish similarly reproducible papers, please add a notice close to the start of your paper or in the end of the abstract clearly mentioning that your work is fully reproducible. +One convention we have adopted until now is to put the Git checkum of the project as the last word of the abstract, for example see \citet{akhlaghi19}, \citet{infantesainz20} and \citet{maneage} + +Finally, don't forget to cite \citet{maneage} and acknowledge the funders mentioned below. +Otherwise we won't be able to continue working on Maneage. +Also, just as another reminder, before publication, don't forget to follow the ``Publication checklist'' of \texttt{README-hacking.md}. %% End of main body. @@ -243,27 +180,16 @@ to follow the ``Publication checklist'' of \texttt{README-hacking.md}. \section{Acknowledgments} -\new{Please include the following two paragraphs in the Acknowledgement - section of your paper. Maneage was developed in parallel with Gnuastro, - so it benefited from the same grants. If you don't use Gnuastro in your - final/customized project, please remove it from the paragraph below, only - mentioning the reproducible paper template.} - -This project was developed in the reproducible framework of Maneage -\citep[\emph{Man}aging data lin\emph{eage},][latest Maneage commit of - \maneageversion, and built on an {\machinearchitecture} machine with - {\machinebyteorder} byte-order]{maneage}. Maneage has been -funded partially by the following grants: Japanese Ministry of Education, -Culture, Sports, Science, and Technology (MEXT) PhD scholarship to -M. Akhlaghi and its Grant-in-Aid for Scientific Research (21244012, -24253003). The European Research Council (ERC) advanced grant -339659-MUSICOS. The European Union (EU) Horizon 2020 (H2020) research and -innovation programmes No 777388 under RDA EU 4.0 project, and Marie -Sk\l{}odowska-Curie grant agreement No 721463 to the SUNDIAL ITN. The State -Research Agency (AEI) of the Spanish Ministry of Science, Innovation and -Universities (MCIU) and the European Regional Development Fund (ERDF) under -the grant AYA2016-76219-P. The IAC project P/300724, financed by the MCIU, -through the Canary Islands Department of Economy, Knowledge and Employment. +\new{Please include the following two paragraphs in the Acknowledgement section of your paper. + Maneage was developed in parallel with Gnuastro, so it benefited from the same grants. + If you don't use Gnuastro in your final/customized project, please remove it from the paragraph below, only mentioning the reproducible paper template.} + +This project was developed in the reproducible framework of Maneage \citep[\emph{Man}aging data lin\emph{eage},][latest Maneage commit of \maneageversion, and built on an {\machinearchitecture} machine with {\machinebyteorder} byte-order]{maneage}. +Maneage has been funded partially by the following grants: Japanese Ministry of Education, Culture, Sports, Science, and Technology (MEXT) PhD scholarship to M. Akhlaghi and its Grant-in-Aid for Scientific Research (21244012, 24253003). +The European Research Council (ERC) advanced grant 339659-MUSICOS. +The European Union (EU) Horizon 2020 (H2020) research and innovation programmes No 777388 under RDA EU 4.0 project, and Marie Sk\l{}odowska-Curie grant agreement No 721463 to the SUNDIAL ITN. +The State Research Agency (AEI) of the Spanish Ministry of Science, Innovation and Universities (MCIU) and the European Regional Development Fund (ERDF) under the grant AYA2016-76219-P. +The IAC project P/300724, financed by the MCIU, through the Canary Islands Department of Economy, Knowledge and Employment. %% Tell BibLaTeX to put the bibliography list here. \printbibliography diff --git a/project b/project index 61463ec..d75a9ce 100755 --- a/project +++ b/project @@ -41,8 +41,10 @@ make_targets= software_dir= clean_texdir=0 prepare_redo=0 +highlightnew=0 all_highlevel=0 existing_conf=0 +highlightnotes=0 scriptname="./project" minmapsize=10000000000 @@ -118,10 +120,14 @@ Configure and Make options: -j, --jobs=INT Number of threads to build/run the software. -?, --help Print this help list. -Make options: +Make (analysis) options: -d, --debug=FLAGS Print various types of debugging information. -p, --prepare-redo Re-do preparation (only done automatically once). +Make (final PDF) options: + --highlight-new Highlight '\new' parts of text as green. + --highlight-notes Show '\tonote' regions as red text in PDF. + Mandatory or optional arguments to long options are also mandatory or optional for any corresponding short options. @@ -205,6 +211,10 @@ do # # Note that Make's `debug' can take values, but when called without any # value, it is like giving it a value of `a'): + --highlight-new) highlightnew=1; shift;; + --highlight-new=*) on_off_option_error --highlight-new;; + --highlight-notes) highlightnotes=1; shift;; + --highlight-notes=*) on_off_option_error --highlight-notes;; -d|--debug) if [ x"$2" = x ]; then debug=a; shift; else debug="$2"; check_v debug "$debug"; shift;shift; fi;; -d=*|--debug=*) debug="${1#*=}"; check_v debug "$debug"; shift;; @@ -370,8 +380,9 @@ controlled_env() { # Remove all existing environment variables (with `env -i') and only # use some pre-defined environment variables, then build the project. envmake=".local/bin/env -i HOME=$bdir sys_rm=$(which rm) $gopt" - envmake="$envmake .local/bin/make --no-builtin-rules" - envmake="$envmake --no-builtin-variables -f $1" + envmake="$envmake highlightnew=$highlightnew" + envmake="$envmake highlightnotes=$highlightnotes .local/bin/make" + envmake="$envmake --no-builtin-rules --no-builtin-variables -f $1" if ! [ x"$debug" = x ]; then envmake="$envmake --debug=$debug"; fi # Set the number of jobs. Note that for the `configure.sh' script the diff --git a/reproduce/analysis/make/paper.mk b/reproduce/analysis/make/paper.mk index 28f44a9..fc10699 100644 --- a/reproduce/analysis/make/paper.mk +++ b/reproduce/analysis/make/paper.mk @@ -48,10 +48,23 @@ $(mtexdir)/project.tex: $(mtexdir)/verify.tex # Put a LaTeX input command for all the necessary macro files. # 'hardware-parameters.tex' is created in 'configure.sh'. - rm -f $(mtexdir)/project.tex + projecttex=$(mtexdir)/project.tex + rm -f $$projecttex for t in $(subst paper,,$(makesrc)) hardware-parameters; do - echo "\input{tex/build/macros/$$t.tex}" >> $(mtexdir)/project.tex + echo "\input{tex/build/macros/$$t.tex}" >> $$projecttex done + + # Possibly highlight the '\new' parts of the text. + if [ x"$(highlightnew)" = x1 ]; then + echo "\newcommand{\highlightnew}{}" >> $$projecttex + fi + + # Possibly show the text within '\tonote'. + if [ x"$(highlightnotes)" = x1 ]; then + echo "\newcommand{\highlightnotes}{}" >> $$projecttex + fi + + # The paper shouldn't be built. else echo echo "-----" diff --git a/tex/src/preamble-header.tex b/tex/src/preamble-header.tex deleted file mode 100644 index 42bb409..0000000 --- a/tex/src/preamble-header.tex +++ /dev/null @@ -1,89 +0,0 @@ -%% The headers: title, authors, top of pages and section title formatting -%% of the final LaTeX file are configured here. -% -%% Copyright (C) 2018-2020 Mohammad Akhlaghi -% -%% This file is free software: you can redistribute it and/or modify it -%% under the terms of the GNU General Public License as published by the -%% Free Software Foundation, either version 3 of the License, or (at your -%% option) any later version. -% -%% This file is distributed in the hope that it will be useful, but WITHOUT -%% ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or -%% FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License -%% for more details. -% -%% You should have received a copy of the GNU General Public License along -%% with this file. If not, see . - - - - - -%% General page header settings. -\usepackage{fancyhdr} -\pagestyle{fancy} -\lhead{\footnotesize{\scshape Draft paper}, {\footnotesize nnn:i (pp), Year Month day}} -\rhead{\scshape\footnotesize YOUR-NAME et al.} -\cfoot{\thepage} -\setlength{\voffset}{0.75cm} -\setlength{\headsep}{0.2cm} -\setlength{\footskip}{0.75cm} -\renewcommand{\headrulewidth}{0pt} - - - - - -%% Specific style for first page. -\fancypagestyle{firststyle} -{ - \lhead{\footnotesize{\scshape Draft paper}, nnn:i (pp), YYYY Month day\\ - \scriptsize \textcopyright YYYY, Your name. All rights reserved.} - \rhead{\footnotesize \footnotesize \today, \currenttime\\} -} - - - - - -%To set the style of the titles: -\usepackage{titlesec} -\titleformat{\section} - {\centering\normalfont\uppercase} - {\thesection.} - {0em} - { } -\titleformat{\subsection} - {\centering\normalsize\slshape} - {\thesubsection.} - {0em} - { } -\titleformat{\subsubsection} - {\centering\small\slshape} - {\thesubsubsection.} - {0em} - { } - - - - - -% Basic Document information that goes into the PDF meta-data. -\hypersetup -{ - pdfauthor={YOUR NAME}, - pdfsubject={\projecttitle}, - pdftitle={\projecttitle}, - pdfkeywords={SOME, KEYWORDS, FOR, THE, PDF} -} - - - - - -%% Title and author information -\usepackage{authblk} -\renewcommand\Authfont{\small\scshape} -\renewcommand\Affilfont{\footnotesize\normalfont} -\setlength{\affilsep}{0.2cm} diff --git a/tex/src/preamble-maneage-default-style.tex b/tex/src/preamble-maneage-default-style.tex new file mode 100644 index 0000000..665c846 --- /dev/null +++ b/tex/src/preamble-maneage-default-style.tex @@ -0,0 +1,215 @@ +%% General paper's style settings. +% +%% This preamble can be completely ignored when including this TeX file in +%% another style. This is done because this LaTeX build is meant to be an +%% initial/internal phase or part of a larger effort, so it has a basic +%% style defined here as a preamble. To ignore it, uncomment or delete the +%% respective line in `paper.tex'. +% +%% Copyright (C) 2019-2020 Mohammad Akhlaghi +% +%% This file is free software: you can redistribute it and/or modify it +%% under the terms of the GNU General Public License as published by the +%% Free Software Foundation, either version 3 of the License, or (at your +%% option) any later version. +% +%% This file is distributed in the hope that it will be useful, but WITHOUT +%% ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +%% FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +%% for more details. +% +%% You should have received a copy of the GNU General Public License along +%% with this file. If not, see . + + + + + +%% Font. +\usepackage[T1]{fontenc} +\usepackage{newtxtext} +\usepackage{newtxmath} + + + + + +%% Print size +\usepackage[a4paper, includeheadfoot, body={18.7cm, 24.5cm}]{geometry} + + + + + +%% Set the distance between the columns if two columns: +\setlength{\columnsep}{0.75cm} + + + + + +% To allow figures to take up more space on the top of the page: +\renewcommand{\topfraction}{.99} +\renewcommand{\bottomfraction}{.7} +\renewcommand{\textfraction}{.05} +\renewcommand{\floatpagefraction}{.99} +\renewcommand{\dbltopfraction}{.99} +\renewcommand{\dblfloatpagefraction}{.99} +\setcounter{topnumber}{1} +\setcounter{bottomnumber}{0} +\setcounter{totalnumber}{2} +\setcounter{dbltopnumber}{1} + + + + + +%% Color related settings: +\usepackage{xcolor} +\color{black} % Text color +\definecolor{DarkBlue}{RGB}{0,0,90} + + + + + + +% figure and figure* ordering correction: +\usepackage{fixltx2e} + + + + + +%% For editing the caption appearence. The `setspace' package defines +%% the `stretch' variable. `abovecaptionskip' is the distance between +%% the figure and the caption. +\usepackage{setspace, caption} +\captionsetup{font=footnotesize, labelfont={color=DarkBlue,bf}, skip=1pt} +\captionsetup[figure]{font={stretch=1, small}} +\setlength{\abovecaptionskip}{3pt plus 1pt minus 1pt} +\setlength{\belowcaptionskip}{-1.25em} + + + + + + +%% To make the footnotes align: +\usepackage[hang]{footmisc} +\setlength\footnotemargin{10pt} + + + + + +%For including time in the title: +\usepackage{datetime} + + + + + +%To make links to webpages and include document information in the +%properties of the PDF +\usepackage[ + colorlinks, + urlcolor=blue, + citecolor=blue, + linkcolor=blue, + linktocpage]{hyperref} +\renewcommand\UrlFont{\rmfamily} + + + + + +%% Define the abstract environment +\renewenvironment{abstract} + {\vspace{-0.5cm}\small% + \list{}{% + \setlength{\leftmargin}{2cm}% + \setlength{\rightmargin}{\leftmargin}% + }% + \item\relax} + {\endlist} + + + + + +%% To keep the main page's code clean. +\newcommand{\includeabstract}[1]{% +\twocolumn[% + \begin{@twocolumnfalse}% + \maketitle% + \begin{abstract}% + #1% + \end{abstract}% + \vspace{1cm}% + \end{@twocolumnfalse}% + ]% +} + + + + + +%% Basic header style +%% ------------------ +% +%% The steps below are to use the necessary LaTeX packages to get the demo +%% Maneage paper running with a reasonably looking, custom paper style. If +%% you are using a custom journal style, feel free to delete these. + +%% General page header settings. +\usepackage{fancyhdr} +\pagestyle{fancy} +\lhead{\footnotesize{\scshape Draft paper}, {\footnotesize nnn:i (pp), Year Month day}} +\rhead{\scshape\footnotesize YOUR-NAME et al.} +\cfoot{\thepage} +\setlength{\voffset}{0.75cm} +\setlength{\headsep}{0.2cm} +\setlength{\footskip}{0.75cm} +\renewcommand{\headrulewidth}{0pt} + +%% Specific style for first page. +\fancypagestyle{firststyle} +{ + \lhead{\footnotesize{\scshape Draft paper}, nnn:i (pp), YYYY Month day\\ + \scriptsize \textcopyright YYYY, Your name. All rights reserved.} + \rhead{\footnotesize \footnotesize \today, \currenttime\\} +} + +%To set the style of the titles: +\usepackage{titlesec} +\titleformat{\section} + {\centering\normalfont\uppercase} + {\thesection.} + {0em} + { } +\titleformat{\subsection} + {\centering\normalsize\slshape} + {\thesubsection.} + {0em} + { } +\titleformat{\subsubsection} + {\centering\small\slshape} + {\thesubsubsection.} + {0em} + { } + +% Basic Document information that goes into the PDF meta-data. +\hypersetup +{ + pdfauthor={YOUR NAME}, + pdfsubject={\projecttitle}, + pdftitle={\projecttitle}, + pdfkeywords={SOME, KEYWORDS, FOR, THE, PDF} +} + +%% Title and author information +\usepackage{authblk} +\renewcommand\Authfont{\small\scshape} +\renewcommand\Affilfont{\footnotesize\normalfont} +\setlength{\affilsep}{0.2cm} diff --git a/tex/src/preamble-maneage.tex b/tex/src/preamble-maneage.tex new file mode 100644 index 0000000..81d8535 --- /dev/null +++ b/tex/src/preamble-maneage.tex @@ -0,0 +1,35 @@ +%% Preamble for Maneage-related features. +% +%% Copyright (C) 2020 Mohammad Akhlaghi +% +%% This LaTeX file is part of Maneage. Maneage is free software: you can +%% redistribute it and/or modify it under the terms of the GNU General +%% Public License as published by the Free Software Foundation, either +%% version 3 of the License, or (at your option) any later version. +% +%% Maneage is distributed in the hope that it will be useful, but WITHOUT +%% ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +%% FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +%% for more details. See . + + + + + +%% Highlighting +%% ------------ +% +%% Maneage feature for highlighting changes they can be set activated +%% directly on the command-line with the '--highlight-new' or +%% '--highlight-notes' options +\ifdefined\highlightnew +\newcommand{\new}[1]{\textcolor{green!50!black}{#1}} +\else +\newcommand{\new}[1]{\textcolor{black}{#1}} +\fi + +\ifdefined\highlightnotes +\newcommand{\tonote}[1]{\textcolor{red!60!black}{[#1]}} +\else +\newcommand{\tonote}[1]{{}} +\fi diff --git a/tex/src/preamble-necessary.tex b/tex/src/preamble-necessary.tex deleted file mode 100644 index bf74c8b..0000000 --- a/tex/src/preamble-necessary.tex +++ /dev/null @@ -1,70 +0,0 @@ -%% Necessary (independent of style) macros for this project. -%% -%% These are a set of packages that have been commonly necessary in most -%% LaTeX usages. However, if any are not needed in your work, please feel -%% free to remove them. -% -%% Copyright (C) 2018-2020 Mohammad Akhlaghi -% -%% This file is free software: you can redistribute it and/or modify it -%% under the terms of the GNU General Public License as published by the -%% Free Software Foundation, either version 3 of the License, or (at your -%% option) any later version. -% -%% This file is distributed in the hope that it will be useful, but WITHOUT -%% ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or -%% FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License -%% for more details. -% -%% You should have received a copy of the GNU General Public License along -%% with this file. If not, see . - - - - - -%% For highlighting updates. When this is set, text marked as \new -%% will be colored in dark green and text that is marked wtih \tonote -%% will be marked in dark red. -\ifdefined\highlightchanges -\newcommand{\new}[1]{\textcolor{green!60!black}{#1}} -\newcommand{\tonote}[1]{\textcolor{red!60!black}{[#1]}} -\else -\newcommand{\new}[1]{\textcolor{black}{#1}} -\newcommand{\tonote}[1]{{}} -\fi - - - - - -% Better than verbatim for displaying typed text. -\usepackage{alltt} - - - - - -% For arithmetic opertions within LaTeX -\usepackage[nomessages]{fp} - - - - - -%To add a code font to the text: -\usepackage{courier} - - - - - -%To add some enumerating styles -\usepackage{enumerate} - - - - - -%Including images if necessary -\usepackage{graphicx} diff --git a/tex/src/preamble-project.tex b/tex/src/preamble-project.tex new file mode 100644 index 0000000..4206801 --- /dev/null +++ b/tex/src/preamble-project.tex @@ -0,0 +1,75 @@ +%% Necessary macros for this project. +%% +%% These are a set of packages that have been commonly necessary in most +%% LaTeX usages. However, if any are not needed in your work, please feel +%% free to remove them. +% +%% Copyright (C) 2018-2020 Mohammad Akhlaghi +%% Copyright (C) YYYY Your Name +% +%% This file is free software: you can redistribute it and/or modify it +%% under the terms of the GNU General Public License as published by the +%% Free Software Foundation, either version 3 of the License, or (at your +%% option) any later version. +% +%% This file is distributed in the hope that it will be useful, but WITHOUT +%% ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +%% FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +%% for more details. +% +%% You should have received a copy of the GNU General Public License along +%% with this file. If not, see . + + + + + +%% Packages you need in your project +%% --------------------------------- +% +%% Here you can add/remove any custom LaTeX package that you need for this +%% project that aren't provided by the journal's style. + +% Better than verbatim for displaying typed text. +\usepackage{alltt} + +% For arithmetic opertions within LaTeX +\usepackage[nomessages]{fp} + +%To add a code font to the text: +\usepackage{courier} + +%To add some enumerating styles +\usepackage{enumerate} + +%Including images if necessary +\usepackage{graphicx} + + + + + +%% BibLaTeX or PGFPlots templates +%% ------------------------------ +% +%% These are ready-made customizations of these two commonly used packages +%% that you can use as a template for your own project: BibLaTeX (advanced +%% bibliography management) or PGFPlots (for drawing plots within LaTeX +%% directly from tables of data). If you don't use them, you can just +%% delete these two lines and also delete their files from your branch (to +%% keep the 'tex/src' directory on your branch clean). +\input{tex/src/preamble-biblatex.tex} +\input{tex/src/preamble-pgfplots.tex} + + + + + +%% Style of default paper (DELETE IF USING JOURNAL STYLES) +%% ------------------------------------------------------- +% +%% This is primarily defined for the default Maneage paper style. So when +%% you later import your journal's style, delete this line (and these +%% comments). Also delete the file (to keep your project source branch +%% clean from files you don't need/use). +\input{tex/src/preamble-maneage-default-style.tex} diff --git a/tex/src/preamble-style.tex b/tex/src/preamble-style.tex deleted file mode 100644 index c07837f..0000000 --- a/tex/src/preamble-style.tex +++ /dev/null @@ -1,152 +0,0 @@ -%% General paper's style settings. -% -%% This preamble can be completely ignored when including this TeX file in -%% another style. This is done because this LaTeX build is meant to be an -%% initial/internal phase or part of a larger effort, so it has a basic -%% style defined here as a preamble. To ignore it, uncomment or delete the -%% respective line in `paper.tex'. -% -%% Copyright (C) 2019-2020 Mohammad Akhlaghi -% -%% This file is free software: you can redistribute it and/or modify it -%% under the terms of the GNU General Public License as published by the -%% Free Software Foundation, either version 3 of the License, or (at your -%% option) any later version. -% -%% This file is distributed in the hope that it will be useful, but WITHOUT -%% ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or -%% FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License -%% for more details. -% -%% You should have received a copy of the GNU General Public License along -%% with this file. If not, see . - - - - - -%% Font. -\usepackage[T1]{fontenc} -\usepackage{newtxtext} -\usepackage{newtxmath} - - - - - -%% Print size -\usepackage[a4paper, includeheadfoot, body={18.7cm, 24.5cm}]{geometry} - - - - - -%% Set the distance between the columns if two columns: -\setlength{\columnsep}{0.75cm} - - - - - -% To allow figures to take up more space on the top of the page: -\renewcommand{\topfraction}{.99} -\renewcommand{\bottomfraction}{.7} -\renewcommand{\textfraction}{.05} -\renewcommand{\floatpagefraction}{.99} -\renewcommand{\dbltopfraction}{.99} -\renewcommand{\dblfloatpagefraction}{.99} -\setcounter{topnumber}{1} -\setcounter{bottomnumber}{0} -\setcounter{totalnumber}{2} -\setcounter{dbltopnumber}{1} - - - - - -%% Color related settings: -\usepackage{xcolor} -\color{black} % Text color -\definecolor{DarkBlue}{RGB}{0,0,90} - - - - - - -% figure and figure* ordering correction: -\usepackage{fixltx2e} - - - - - -%% For editing the caption appearence. The `setspace' package defines -%% the `stretch' variable. `abovecaptionskip' is the distance between -%% the figure and the caption. -\usepackage{setspace, caption} -\captionsetup{font=footnotesize, labelfont={color=DarkBlue,bf}, skip=1pt} -\captionsetup[figure]{font={stretch=1, small}} -\setlength{\abovecaptionskip}{3pt plus 1pt minus 1pt} -\setlength{\belowcaptionskip}{-1.25em} - - - - - - -%% To make the footnotes align: -\usepackage[hang]{footmisc} -\setlength\footnotemargin{10pt} - - - - - -%For including time in the title: -\usepackage{datetime} - - - - - -%To make links to webpages and include document information in the -%properties of the PDF -\usepackage[ - colorlinks, - urlcolor=blue, - citecolor=blue, - linkcolor=blue, - linktocpage]{hyperref} -\renewcommand\UrlFont{\rmfamily} - - - - - -%% Define the abstract environment -\renewenvironment{abstract} - {\vspace{-0.5cm}\small% - \list{}{% - \setlength{\leftmargin}{2cm}% - \setlength{\rightmargin}{\leftmargin}% - }% - \item\relax} - {\endlist} - - - - - -%% To keep the main page's code clean. -\newcommand{\includeabstract}[1]{% -\twocolumn[% - \begin{@twocolumnfalse}% - \maketitle% - \begin{abstract}% - #1% - \end{abstract}% - \vspace{1cm}% - \end{@twocolumnfalse}% - ]% -} -- cgit v1.2.1 From ac8eee90b1580fb566ee5b84fef9acb4ed437c01 Mon Sep 17 00:00:00 2001 From: Mohammad Akhlaghi Date: Tue, 1 Dec 2020 11:43:04 +0000 Subject: Default paper: macros available for date of commits cited Until now, Maneage only provided the commit hashes (of the project and Maneage) as LaTeX macros to use in your paper. However, they are too cryptic and not really human friendly (unless you have access to the Git history on a computer). With this commit, to make things easier for the readers, the date of both commits are also available as LaTeX macros for use in the paper. The date of the Maneage commit is also included in the acknowledgements. Also, the paragraph above the acknowledgements has been updated with better explanation on why adding this acknowledgement in the science papers is good/necessary. --- paper.tex | 11 +++++++---- reproduce/analysis/make/initialize.mk | 6 +++++- 2 files changed, 12 insertions(+), 5 deletions(-) diff --git a/paper.tex b/paper.tex index ac61cad..63ba4fc 100644 --- a/paper.tex +++ b/paper.tex @@ -180,11 +180,13 @@ Also, just as another reminder, before publication, don't forget to follow the ` \section{Acknowledgments} -\new{Please include the following two paragraphs in the Acknowledgement section of your paper. - Maneage was developed in parallel with Gnuastro, so it benefited from the same grants. - If you don't use Gnuastro in your final/customized project, please remove it from the paragraph below, only mentioning the reproducible paper template.} +\new{Please include the following paragraph in the Acknowledgement section of your paper. + In order to get more funding to continue working on Maneage, we need to to cite it and its funding institutions in your papers. + Also note that at the start, it includes version and date information for the most recent Maneage commit you merged with (which can be very helpful for others) as well as very basic information about your CPU architecture (which was extracted during configuration). + This CPU information is very important for reproducibility because some software may not be buildable on other CPU architectures, so it is necessary to publish CPU information with the results and software versions.} -This project was developed in the reproducible framework of Maneage \citep[\emph{Man}aging data lin\emph{eage},][latest Maneage commit of \maneageversion, and built on an {\machinearchitecture} machine with {\machinebyteorder} byte-order]{maneage}. +This project was developed in the reproducible framework of Maneage \citep[\emph{Man}aging data lin\emph{eage},][latest Maneage commit \maneageversion{}, from \maneagedate]{maneage}. +The project was built on an {\machinearchitecture} machine with {\machinebyteorder} byte-order, see Appendix \ref{appendix:software} for the used software and their versions. Maneage has been funded partially by the following grants: Japanese Ministry of Education, Culture, Sports, Science, and Technology (MEXT) PhD scholarship to M. Akhlaghi and its Grant-in-Aid for Scientific Research (21244012, 24253003). The European Research Council (ERC) advanced grant 339659-MUSICOS. The European Union (EU) Horizon 2020 (H2020) research and innovation programmes No 777388 under RDA EU 4.0 project, and Marie Sk\l{}odowska-Curie grant agreement No 721463 to the SUNDIAL ITN. @@ -199,6 +201,7 @@ The IAC project P/300724, financed by the MCIU, through the Canary Islands Depar %% Mention all used software in an appendix. \section{Software acknowledgement} +\label{appendix:software} \input{tex/build/macros/dependencies.tex} %% Finish LaTeX diff --git a/reproduce/analysis/make/initialize.mk b/reproduce/analysis/make/initialize.mk index 7217f0c..3649fd2 100644 --- a/reproduce/analysis/make/initialize.mk +++ b/reproduce/analysis/make/initialize.mk @@ -482,7 +482,9 @@ $(mtexdir)/initialize.tex: | $(mtexdir) # commands are run every time with './project make', it is annoying # to print them on the standard output every time. With the '@', # make will not print the commands that it runs in this recipe. - @echo "\newcommand{\projecttitle}{$(metadata-title)}" > $@ + @d=$$(git show -s --format=%aD HEAD | awk '{print $$2, $$3, $$4}') + echo "\newcommand{\projectdate}{$$d}" > $@ + echo "\newcommand{\projecttitle}{$(metadata-title)}" >> $@ echo "\newcommand{\projectversion}{$(project-commit-hash)}" >> $@ # Calculate the latest Maneage commit used to build this @@ -494,4 +496,6 @@ $(mtexdir)/initialize.tex: | $(mtexdir) # after cloning from a fork that didn't include it!). In this # case, we'll just return the string a clear string. v=$$(git describe --always --long maneage) || v=maneage-ref-missing + d=$$(git show -s --format=%aD $$v | awk '{print $$2, $$3, $$4}') + echo "\newcommand{\maneagedate}{$$d}" >> $@ echo "\newcommand{\maneageversion}{$$v}" >> $@ -- cgit v1.2.1