<< ReproducibilityCourse

---

How to branch off your own version of a Maneage template

Make some changes and commit them locally

• Start with your directory set up of a research paper that already works, such as gevcurvest .
  1. Do ./project make to check that the pdf is still produced correctly.
  2. Make some changes. To start with, you can make some trivial edits. Once you're ready for more serious edits, scroll down.
  3. Test them and store a log file, just in case: ./project make |& tee log.2 if you want your log file to be called log.2
  4. If there's a failure:
     • investigate the log file, try to understand what went wrong. You have full control of all the plain text files of the full pipeline, so read and search through them using less, grep, and other related tools. If you're unfamiliar with less and grep, then try info less and info grep. Even if you're familiar with grep, you can probably learn some more, so try info grep anyway.
     • Try to tr * Start with your directory set up of a research paper that already works, such as gevcurvest .
  5. Do ./project make to check that the pdf is still produced correctly.
  6. Make some changes.
  7. Test them and store a log file, just in case: ./project make |& tee log.2 if you want your log file to be called log.2
  8. If there's a failure:
     • investigate the log file, try to understand what went wrong. You have full control of all the plain text files of the full pipeline, so read and search through them using less, grep, and other related tools. If you're unfamiliar with less and grep, then try info less and info grep. Even if you're familiar with grep, you can probably learn some more, so try info grep anyway.
     • Try to trace the bug yourself, but also ask on irc/matrix, email, by reading the README* files, and by looking at Maneage Support, Bug and Task trackers.
     • Also ask the lecturer for help ;).
  9. If there's no failure, or after fixing the bug:
     • Start or improve your knowledge of git with: man gittutorial
     • Create your own branch in a logical sense e.g. git branch mybranch
     • Change your logical location (in the git sense) to your own branch: git checkout mybranch
       • Use commands such as git log --stat or git log --all --graph --oneline to check the git evolution.
     • Commit any modified files with e.g. git commit -a
       • If you don't like the default editor, then set your git config editor, e.g. with git config --get core.editor to check your current editor, and git config --set core.editor 'emacs -nw' if you want your editor to be emacs -nw
     • Use commands such as git log --stat or git log --all --graph --oneline to check the git evolution. You should see that your commit is in the mathematical graph of the evolution of the set of files.ace the bug yourself, but also ask on irc/matrix, email, by reading the README* files, and by looking at Maneage Support, Bug and Task trackers.
     • Also ask the lecturer for help ;).
  10. If there's no failure, or after fixing the bug:
      • Start or improve your knowledge of git with: man gittutorial
      • Create your own branch in a logical sense e.g. git branch mybranch
      • Change your logical location (in the git sense) to your own branch: git checkout mybranch
        • Use commands such as git log --stat or git log --all --graph --oneline to check the git evolution.
      • Commit any modified files with e.g. git commit -a
        • If you don't like the default editor, then set your git config editor, e.g. with git config --get core.editor to check your current editor, and git config --set core.editor 'emacs -nw' if you want your editor to be emacs -nw
      • Use commands such as git log --stat or git log --all --graph --oneline to check the git evolution. You should see that your commit is in the mathematical graph of the evolution of the set of files.

What changes should you make?

Delete the core old stuff

Commit 7ea27bd3 on the reproducibility-course-how branch shows an example of deleting the core old stuff. It should give you a nice simplified pdf.

• Remove the current workflow - the science steps of the sequence - except for the beginning and end:
  • To do this, edit the makesrc definition of reproduce/analysis/make/top-make.mk (This is what is currently written as Add `XXXXXX`, as a new line, to the values in `makesrc` of the top-level `Makefile`. in README-hacking.md .)
  • WARNING: Use editor settings that conserve tab characters, i.e. that do not convert them to spaces. The initial tab in the lines of a make rule is crucially important.
  • Remove the strings init-N-body , run-simulations and analyse-plot from the definition of makesrc
• Disable verification of the results of the project, because we're making a fresh project:
  • Edit the reproduce/analysis/config/verify-outputs.conf - remove "yes" (or replace "yes" by "no" or comment out the line)
• Now try ./project make |& tee log.3 .
  • This will fail, because the removal of the analyse-plot.mk step implies that the output file .build/analysis/tex/macros/analyse-plot.tex is ignored.
    • Why does this fail? Based on line numbers and the logic of commit d18ce51c7c:
      • project (this is a shell script - not a makefile)
        • To see what ./project make does, see the project script: line 204 calls func_operation_set which starts on line 190 and should set operation=make because the variable operation is empty until that line.
        • line 454 leads to line 520 which leads to line 540 where top-make.mk is called.
        • lines 428 + 429 of project show that top-make.mk is called with the Maneage version of bash, i.e. the key part of the command on line 540 is effectively .local/bin/make -f reproduce/analysis/make/top-make.mk
      • top-make.mk
        • Since .local/bin/make -f reproduce/analysis/make/top-make.mk does not state a target, the first rule (typically: target: prerequisites followed by indented shell commands) will be executed. In this case line 68 is a rule for the target all with prerequisite gevcurvtest.pdf and a zero-length list of shell commands (ignore the 'else' case)
        • Lines 113 to 118 of top-make.mk define the string analyse-plot as the 4th word of the (make level) variable makesrc
        • The final line of top-make-mk says that all words s in the variable makesrc have to have corresponding .mk files included. Since analyse-plot is the 4th word of makesrc, this line tries to include initialize.mk, init-N-body.mk, ..., analyse-plot.mk, verify.mk, paper.mk. If we remove the word analyse-plot from top-make.mk, then analyse-plot.mk will not be included when we type ./project make.
      • paper.mk
        • Where is the rule for gevcurvtest.pdf ? It's in the included file paper.mk on line 207, which has one command to execute, after checking that paper-full.pdf exists or is older than gevcurvtest.pdf .
        • The rule for paper-full.pdf on line 219 of paper.mk requires $(texbdir)/paper-full.tex to exist and be older than paper-full.pdf .
        • A clue to the specific error caused by removing the string analyse-plot from makesrc is on line 245 of paper.mk , since $(texbdir)/paper-full.tex requires $(mtexdir)/project.tex as a prerequisite. The rule for creating project.tex is has a description starting at line 26, a target and prerequisite on line 47, and three key lines from 58 to 60. Since we have removed analyse-plot from makesrc, the string \input{tex/build/macros/analyse-plot.tex} will not be added to the project.tex file (>> $$projecttex appends to project.tex). How is the project.tex file used?
      • paper.tex
        • The file paper.tex in the top directory has line 32 that includes tex/build/macros/project.tex . If you do cat tex/build/macros/project.tex (it's a very small file) you will see that \input{tex/build/macros/analyse-plot.tex} is absent. Thus, when you run paper.tex through latex and you have not yet deleted the old content, you are trying to use the LaTeX \newcommand macros defined in tex/build/macros/analyse-plot.tex , but this file is not included, so the LaTeX command is undefined.
        • Comment: The directory tex/build is in reality a symbolic link. The directory .build is also a symbolic link. Alternative paths to
          • tex/build/macros/analyse-plot.tex and tex/build/macros/project.tex are
          • .build/analysis/tex/macros/analyse-plot.tex and .build/analysis/tex/macros/project.tex , respectively.
• Edit paper.tex removing most of the main content that is not yours. Leave in some content as temporary examples, and put some markers such as \textbf{NOTMYSTUFF} on content that you leave in place so that you don't accidentally leave it in place in your own paper.
  • Try ./project make |& tee log.4 and do fixes to paper.tex until you again can produce a very minimal template pdf.

Add some minimal new stuff

Commit 611cb9e53 on the reproducibility-course-how branch shows an example of adding some minimal new stuff. It should give you a nice simplified pdf that now shows a result from a simple calculation in the abstract.

• Do git log --stat to read the commit description describing the changes:
  • A new makefile examplemake.mk was added.
  • examplemake was added to top-make.mk
  • paper.tex was edited to include the TeX string \FinalResult
• You will need to learn something about several of the powerful shell tools that you have available using info COMMAND and experimenting, or if you like,
  • WikipediaEn:make%20%28software%29
  • WikipediaEn:sed
  • WikipediaEn:tr%20%28Unix%29
  • WikipediaEn:AWK
  • WikipediaEn:printf%20%28Unix%29

-- BoudRoukema - 01 Apr 2025, 08 April 2025+