From 83063f62859287defc6da525a8e7cb5b728e4fbe Mon Sep 17 00:00:00 2001 From: Mohammad Akhlaghi Date: Thu, 4 Jun 2020 13:25:30 +0100 Subject: README.md, separated scenarios of building from tarball The previous explanation was not too clear and simply following it was confusing. The issue was that with the tarball you have three scenarios: 1) only build the PDF using existing figures. 2) only build the PDF, but build the figures yourself, 3) build the full Maneaged project. Hopefully this distinction is now more clear from the README.md file. --- README.md | 83 +++++++++++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 60 insertions(+), 23 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index fc4c267..b5d3115 100644 --- a/README.md +++ b/README.md @@ -18,10 +18,10 @@ command on your browser, and download the project's source (there is a button to download a compressed tarball of the project). If you have received this source from arXiv, please see the respective section below. -IMPORTANT NOTE: If you want to build using a distributed tarball that isn't -under Git's version control, see the points below under building project -tarball, a few minor modifications need to be made before starting the -project configuration and build. +*IMPORTANT NOTE*: If you want to build using a distributed tarball that +isn't under Git's version control, see the points below under building +project tarball, a few minor modifications need to be made before starting +the project configuration and build. ```shell $ git clone https://gitlab.com/makhlaghi/maneage-paper @@ -88,6 +88,11 @@ requiring root/administrator permissions. + + + + + ### Building project tarball (possibly from arXiv) If the paper is also published on arXiv, it is highly likely that the @@ -99,10 +104,15 @@ PDF without actually using the './project' command! You can directly run 'latex' on this directory and the paper will be built with no analysis (all necessary built products are already included). -1. If the arXiv code for the paper is 1234.56789, then the downloaded - source will be called `1234.56789` (no special identification - suffix). However, it is actually a `.tar.gz` file. So take these steps - to unpack it to see its contents. + + +#### Only building PDF using tarball (no analysis) + +1. If you got the tarball from arXiv and the arXiv code for the paper + is 1234.56789, then the downloaded source will be called + `1234.56789` (no special identification suffix). However, it is + actually a `.tar.gz` file. So take these steps to unpack it to see + its contents. ```shell $ arxiv=1234.56789 @@ -112,15 +122,53 @@ necessary built products are already included). $ tar xf ../$arxiv.tar.gz ``` -2. arXiv removes the executable flag from the files (for its own - security). So before following the standard procedure of projects - described in the sections above, its necessary to set the executable - flag of the main project management file with this command: +2. No matter how you got the tarball, if you just want to build the PDF + paper from the tarball, simply run the command below. Note that this + won't actually install any software or do any analysis, it will just use + your host operating system to build the PDF and assums you already have + all the necessary LaTeX packages. + + ```shell + $ make # Build PDF in tarball without doing analysis + ``` + +3. If you want to re-build the figures from scratch, you need to make the + following corrections to the paper's main LaTeX source (`paper.tex`): + uncomment (remove the starting `%`) of the line containing + `\newcommand{\makepdf}{}`. See the comments above it for more + information. + + + +#### Building full project from tarball (custom software and analysis) + +Since the tarball is mainly geared to only building only the final PDF, a +few small tweaks are necessary to build the full project from scratch +(download necessary software and data, build them and run the analysis and +finally create the final paper). + +1. If you got the tarball from arXiv, before following the standard + procedure of projects described at the top of the file above (using the + './project' script), its necessary to set its executable flag. arXiv + removes the executable flag from the files (for its own security). ```shell $ chmod +x project ``` +2. Make the following change in two of the LaTeX files so LaTeX attempts to + build the figures from scratch (to make the tarball, it was configured + to avoid building the figures, just using the ones that came with the + tarball). + + - `paper.tex`: uncomment (remove the starting `%`) of the line + containing `\newcommand{\makepdf}{}`. See the comments above it for + more information. + + - `tex/src/preamble-pgfplots.tex`: set the `tikzsetexternalprefix` + variable value to `tikz/`, so it looks like this: + `\tikzsetexternalprefix{tikz/}`. + 3. Remove extra files. In order to make sure arXiv can build the paper (resolve conflicts due to different versions of LaTeX packages), it is sometimes necessary to copy raw LaTeX package files in the tarball @@ -134,17 +182,6 @@ necessary built products are already included). COPYING paper.tex project README-hacking.md README.md reproduce tex ``` -4. To build the figures from scratch, you need to make the following - corrections to the LaTeX source files below. - - 4.1: `paper.tex`: uncomment (remove the starting `%`) of the line - containing `\newcommand{\makepdf}{}`. See the comments above it - for more information. - - 4.2: `tex/src/preamble-pgfplots.tex`: set the `tikzsetexternalprefix` - variable value to `tikz/`, so it looks like this: - `\tikzsetexternalprefix{tikz/}`. - -- cgit v1.2.1