Improve and update deprecated documentations

docs/README.md

@@ -12,8 +12,6 @@ Here is an alphabetically ordered list of all documentation:
 - [CLI reference](cli-reference.md): a reference for all parameters of the CLI.
 - [Changelog](../CHANGELOG.md): a list of additions and changes for all
   released and unreleased versions of PineAPPL.
-- [Grid repository](https://github.com/NNPDF/pineapplgrids/): pre-computed grids
-  for specific experimental setups.
 - [Installation](installation.md): installation instructions.
 - [Madgraph5_aMC@NLO](mg5_aMC.md): how to create PineAPPL grids with
   [Madgraph5_aMC@NLO](https://launchpad.net/mg5amcnlo/).
@@ -31,8 +29,13 @@ Here is an alphabetically ordered list of all documentation:
 
 ### Code examples
 
-Another way to learn using the APIs is to have a look/modify the
-[examples](../examples/).
+Another way to learn using the APIs is to have a look/modify the examples:
+
+- [C and C++](../examples/cpp/)
+- [Object-oriented C++](../examples/object-oriented-cpp/)
+- [Fortran](../examples/fortran/)
+- [Python](../examples/python/)
+- [Madgraph5_aMC@NLO](../examples/mg5amcnlo/)
 
 ## Developer documentation
 

docs/cli-reference.md

@@ -29,9 +29,9 @@ where `N` must be the exponent of the strong coupling (denoted with `as`) and
 example, in Drell–Yan lepton-pair production `a2,a2as1` selects the leading
 order (`a2`) and the next-to-leading order QCD (`a2as1`).
 
-## `PDFSET`: Specifying PDF members or entire PDF sets
+## `CONV_FUNS`: Specifying PDF members or entire PDF sets
 
-The parameter `PDFSET` that appears for all convolutional-type subcommands
+The parameter `CONV_FUNS` that appears for all convolutional-type subcommands
 (`channels`, `convolve`, etc.) must be one of the following strings:
 
 - `setname/member`: In this case `setname` must be a valid [LHAPDF] set name
@@ -50,10 +50,10 @@ The parameter `PDFSET` that appears for all convolutional-type subcommands
   `CT18NNLO` and `14001` corresponds to `CT18NNLO/1`.
 
 If an entire PDF set must be given for the calculation of PDF uncertainties,
-that means for for `pdfunc`, `plot` or `pull`, the member selection using `/0`,
+that means for `uncert`, `plot` or `pull`, the member selection using `/0`,
 `/1` can be used to show specific members instead of the central prediction.
-For instance `pineappl pdfunc ... NNPDF40_nnlo_as_01180` calculates the central
-value using the average over all replicas, whereas `pineappl pdfunc ...
+For instance `pineappl uncert ... NNPDF40_nnlo_as_01180` calculates the central
+value using the average over all replicas, whereas `pineappl uncert ...
 NNPDF40_nnlo_as_01180/0` uses the zeroth member. This is especially useful to
 show different replicas in plots.
 
@@ -63,9 +63,9 @@ multiple PDF sets. For example, `NNPDF31_nnlo_as_0118_luxqed=NNPDF31luxQED`
 instructs to use the the PDF set `NNPDF31_nnlo_as_0118_luxqed`, but it would be
 called `NNPDF31luxQED`.
 
-## `REMAPPING`: Remapping parameter specification
+## `LIMITS`: Remapping parameter specification
 
-This section specifies the `REMAPPING` parameter of `pineappl remap`.
+This section specifies the `LIMITS` parameter of `pineappl write --set-bins`.
 
 ### Motivation
 
@@ -77,7 +77,7 @@ For performance/simplicity reasons most Monte Carlo generators neither support
 *during generation*. To work around this problem a grid with a one-dimensional
 distribution with equally-sized bins can be generated instead, and afterwards
 the bins can be 'remapped' to an N-dimensional distribution using the limits
-specified with the `REMAPPING` string.
+specified with the `LIMITS` string.
 
 ### Reference
 
@@ -114,8 +114,8 @@ The remapping string uses the following special characters to achieve this
 
 Finally note that the differential cross sections are calculated using the bin
 sizes (the product of bin widths of each dimension) given by the remapping
-string. The option `--ignore-obs-norm` can be used to remove certain dimensions
-from the bin size determination, for example `'0,10,20;0,2,4' --ignore-obs-norm
+string. The option `--div-bin-norm-dims` can be used to remove certain dimensions
+from the bin size determination, for example `'0,10,20;0,2,4' --div-bin-norm-dims
 1` will normalize the bins with a size of `2` because the first dimension (with
 index `1`) will be ignored
 

docs/cli-tutorial.md

@@ -34,7 +34,7 @@ Now that you've got a grid, you can perform a convolution with a PDF set:
 We chose to use the default CT18 PDF set for this tutorial, because it's the
 shortest to type. If you get an error that reads
 
-    error: Invalid value for '<PDFSETS>...': The PDF set `CT18NNLO` was not found
+    error: Invalid value for '<CONV_FUNS>...': The PDF set `CT18NNLO` was not found
 
 install the PDF set with LHAPDF, or use a different PDF set—the numbers won't
 matter for the sake of the tutorial. If the command was successful, you should
@@ -122,22 +122,25 @@ following:
 
     Convolutes a PineAPPL grid with a PDF set
 
-    Usage: pineappl convolve [OPTIONS] <INPUT> <PDFSETS>...
+    Usage: pineappl convolve [OPTIONS] <INPUT> <CONV_FUNS>...
 
     Arguments:
-      <INPUT>       Path of the input grid
-      <PDFSETS>...  LHAPDF id(s) or name of the PDF set(s)
+      <INPUT>         Path of the input grid
+      <CONV_FUNS>...  LHAPDF id(s) or name of the PDF set(s)
 
     Options:
       -b, --bins <BINS>       Selects a subset of bins
       -i, --integrated        Show integrated numbers (without bin widths) instead of differential ones
       -o, --orders <ORDERS>   Select orders manually
+          --xir <XIR>         Set the variation of the renormalization scale [default: 1.0]
+          --xif <XIF>         Set the variation of the factorization scale [default: 1.0]
+          --xia <XIA>         Set the variation of the fragmentation scale [default: 1.0]
           --digits-abs <ABS>  Set the number of fractional digits shown for absolute numbers [default: 7]
           --digits-rel <REL>  Set the number of fractional digits shown for relative numbers [default: 2]
       -h, --help              Print help
 
 This explains that `pineappl convolve` needs at least two arguments, the first
-being the grid file, denoted as `<INPUT>` and a second argument `<PDFSETS>`,
+being the grid file, denoted as `<INPUT>` and a second argument `<CONV_FUNS>`,
 which determines the PDF set. Note that this argument has three dots, `...`,
 meaning that you're allowed to pass multiple PDF sets, in which case `pineappl`
 will perform the convolution with each PDF set, such that you can compare them
@@ -379,32 +382,33 @@ install the set first) as the PDF set:
 
 Let's calculate the scale and PDF uncertainties for our grid:
 
-    pineappl uncert --pdf --scale-env=7 LHCB_WP_7TEV.pineappl.lz4 NNPDF31_nnlo_as_0118_luxqed
+    pineappl uncert --conv-fun --scale-env=7 LHCB_WP_7TEV.pineappl.lz4 NNPDF31_nnlo_as_0118_luxqed
 
 This will show a table very similar to `pineappl convolve`:
 
-    b   etal    dsig/detal  PDF central    PDF     7pt-svar (env)
-         []        [pb]                    [%]           [%]
-    -+----+----+-----------+-----------+-----+----+-------+-------
-    0    2 2.25 7.7651327e2 7.7650499e2 -1.01 1.01   -3.69    2.64
-    1 2.25  2.5 7.1011428e2 7.1008027e2 -1.01 1.01   -3.67    2.69
-    2  2.5 2.75 6.1683947e2 6.1679433e2 -1.01 1.01   -3.67    2.76
-    3 2.75    3 4.9791036e2 4.9786461e2 -1.03 1.03   -3.64    2.78
-    4    3 3.25 3.7016249e2 3.7012355e2 -1.07 1.07   -3.60    2.80
-    5 3.25  3.5 2.5055318e2 2.5052366e2 -1.13 1.13   -3.55    2.81
-    6  3.5    4 1.1746882e2 1.1745148e2 -1.33 1.33   -3.48    2.80
-    7    4  4.5 2.8023753e1 2.8018010e1 -4.05 4.05   -3.40    2.74
+    b   etal    dsig/detal      NNPDF31_nnlo_as_0118_luxqed      7pt-svar (env)
+         []        [pb]       [pb]          [%]     [%]           [%]
+    -+----+----+-----------+-----------+--------+--------+-------+-------
+    0    2 2.25 7.7651327e2 7.7650499e2    -1.01     1.01   -3.69    2.64
+    1 2.25  2.5 7.1011428e2 7.1008027e2    -1.01     1.01   -3.67    2.69
+    2  2.5 2.75 6.1683947e2 6.1679433e2    -1.01     1.01   -3.67    2.76
+    3 2.75    3 4.9791036e2 4.9786461e2    -1.03     1.03   -3.64    2.78
+    4    3 3.25 3.7016249e2 3.7012355e2    -1.07     1.07   -3.60    2.80
+    5 3.25  3.5 2.5055318e2 2.5052366e2    -1.13     1.13   -3.55    2.81
+    6  3.5    4 1.1746882e2 1.1745148e2    -1.33     1.33   -3.48    2.80
+    7    4  4.5 2.8023753e1 2.8018010e1    -4.05     4.05   -3.40    2.74
 
 The first three columns are exactly the one that `pineappl convolve` shows. The
-next columns are the PDF central predictions, and negative and positive PDF
-uncertainties. These uncertainties are calculated using LHAPDF, so `pineappl`
-always uses the correct algorithm no matter what type of PDF sets you use:
-Hessian, Monte Carlo, etc. Note that we've chosen a PDF set with Monte Carlo
-replicas which means that the results shown in `dsig/detal` and `PDF central`
-aren't exactly the same. The first number is calculated from the zeroth replica
-of the set and the second number is the average of all replicas (except the
-zeroth). You'll notice that the PDF uncertainties are symmetric, which will not
-necessarily be the case with Hessian PDF sets, for instance.
+next columns are the convolution function's central predictions, and negative
+and positive uncertainties. These uncertainties are calculated using LHAPDF, so
+`pineappl` always uses the correct algorithm no matter what type of convolution
+functions you use: Hessian, Monte Carlo, etc. Note that we've chosen a PDF set
+with Monte Carlo replicas which means that the results shown in `dsig/detal` and
+the central prediction aren't exactly the same. The first number is calculated
+from the zeroth replica of the set and the second number is the average of all
+replicas (except the zeroth). You'll notice that the PDF uncertainties are
+symmetric, which will not necessarily be the case with Hessian PDF sets, for
+instance.
 
 The two remaining columns show the scale-variation uncertainty which is
 estimated from taking the envelope of a 7-point scale variation. By changing

docs/metadata.md

@@ -6,12 +6,19 @@ be read indiviually with `pineappl read --get <KEY> <GRID>`, and `pineappl read
 
 ## Known keys
 
-- `arxiv`
-- `description`
-- `hepdata`
-- `inspire`
-- `results`
-- `results_pdf`
+- `arxiv`: the arXiv identifier of the experimental measurement.
+- `description`: a short description of the process.
+- `hepdata`: the Digital Object Identifier (DOI) of the experimental data.
+- `initial_state_1`, `initial_state_2`: PDG Monte Carlo IDs of the initial-state hadrons.
+- `inspire`: the INSPIRE-HEP identifier of the experimental measurement.
+- `lumi_id_types`: the type of partonic luminosity identifiers used.
+- `mg5amc_repo`, `mg5amc_revno`: MadGraph5_aMC@NLO repository URL and revision number.
+- `nnpdf_id`: the NNPDF identifier of the dataset.
+- `pineappl_gitversion`: the version of PineAPPL used to generate the grid.
+- `results`: a table comparing PineAPPL results with the original Monte Carlo.
+- `results_pdf`: the PDF set used for the comparison in `results`.
+- `runcard`: the runcard used to generate the grid.
+- `runcard_gitversion`: the version of the runcard used.
 
 ## CLI-recognized keys
 
@@ -53,5 +60,7 @@ Ratios are denoted using `/`, and powers are denoted using `^2`
 These should contain the equivalent of `x1_label` with (La)TeX commands. If
 symbols from math mode are used, they must be enclosed with `$`.
 
-- `x1_label_tex`
+- `x1_label_tex` (and `x2_label_tex`, etc.)
 - `y_label_tex`
+- `y_unit`: used to append the unit to the y-axis label using the `siunitx` package syntax.
+- `x1_unit` (and `x2_unit`, etc.): used to append the unit to the x-axis label.

docs/mg5_aMC.md

@@ -1,4 +1,4 @@
 # How do I use Madgraph5_aMC@NLO to generate PineAPPL grids?
 
 A full example is available in the examples directory in form of a [bash
-script](../examples/mg5amcnlo/DY_14TEV.sh).
+script](../examples/mg5amcnlo/DY_14TEV_MG_3_5_7.sh).

examples/cpp/fill-custom-grid-deprecated.output

@@ -2,5 +2,5 @@ Generated drell-yan-rap-ll-custom-grid-deprecated.pineappl.lz4 containing a a ->
 
 Try running (PDF sets must contain non-zero photon PDF):
   - pineappl convolve drell-yan-rap-ll-custom-grid-deprecated.pineappl.lz4 NNPDF31_nnlo_as_0118_luxqed
-  - pineappl --silence-lhapdf plot drell-yan-rap-ll-custom-grid-deprecated.pineappl.lz4 NNPDF31_nnlo_as_0118_luxqed MSHT20qed_nnlo > plot_script.py
+  - pineappl plot drell-yan-rap-ll-custom-grid-deprecated.pineappl.lz4 NNPDF31_nnlo_as_0118_luxqed MSHT20qed_nnlo > plot_script.py
   - pineappl --help

examples/cpp/fill-grid-deprecated.cpp

@@ -250,7 +250,7 @@ int main() {
     std::cout << "Generated " << filename << " containing a a -> l+ l-.\n\n"
         "Try running (PDF sets must contain non-zero photon PDF):\n"
         "  - pineappl convolve " << filename << " NNPDF31_nnlo_as_0118_luxqed\n"
-        "  - pineappl --silence-lhapdf plot " << filename
+        "  - pineappl plot " << filename
         << " NNPDF31_nnlo_as_0118_luxqed MSHT20qed_nnlo > plot_script.py\n"
         "  - pineappl --help\n";
 }

examples/cpp/fill-grid-deprecated.output

@@ -2,5 +2,5 @@ Generated drell-yan-rap-ll-deprecated.pineappl.lz4 containing a a -> l+ l-.
 
 Try running (PDF sets must contain non-zero photon PDF):
   - pineappl convolve drell-yan-rap-ll-deprecated.pineappl.lz4 NNPDF31_nnlo_as_0118_luxqed
-  - pineappl --silence-lhapdf plot drell-yan-rap-ll-deprecated.pineappl.lz4 NNPDF31_nnlo_as_0118_luxqed MSHT20qed_nnlo > plot_script.py
+  - pineappl plot drell-yan-rap-ll-deprecated.pineappl.lz4 NNPDF31_nnlo_as_0118_luxqed MSHT20qed_nnlo > plot_script.py
   - pineappl --help

examples/cpp/fill-grid.cpp

@@ -243,7 +243,7 @@ int main() {
     std::cout << "Generated " << filename << " containing a a -> l+ l-.\n\n"
         "Try running (PDF sets must contain non-zero photon PDF):\n"
         "  - pineappl convolve " << filename << " NNPDF31_nnlo_as_0118_luxqed\n"
-        "  - pineappl --silence-lhapdf plot " << filename
+        "  - pineappl plot " << filename
         << " NNPDF31_nnlo_as_0118_luxqed MSHT20qed_nnlo > plot_script.py\n"
         "  - pineappl --help\n";
 }

examples/cpp/fill-grid.output

@@ -2,5 +2,5 @@ Generated drell-yan-rap-ll.pineappl.lz4 containing a a -> l+ l-.
 
 Try running (PDF sets must contain non-zero photon PDF):
   - pineappl convolve drell-yan-rap-ll.pineappl.lz4 NNPDF31_nnlo_as_0118_luxqed
-  - pineappl --silence-lhapdf plot drell-yan-rap-ll.pineappl.lz4 NNPDF31_nnlo_as_0118_luxqed MSHT20qed_nnlo > plot_script.py
+  - pineappl plot drell-yan-rap-ll.pineappl.lz4 NNPDF31_nnlo_as_0118_luxqed MSHT20qed_nnlo > plot_script.py
   - pineappl --help

examples/fortran/dyaa.f90

@@ -131,7 +131,7 @@ program dyaa
     print *, 'Generated DY-LO-AA-deprecated.pineappl.lz4 containing a a -> l+ l-.'
     print *, 'Try running (PDF sets must contain non-zero photon PDF):'
     print *, '  - pineappl convolve DY-LO-AA.pineappl.lz4 NNPDF31_nnlo_as_0118_luxqed'
-    print *, '  - pineappl --silence-lhapdf plot DY-LO-AA-deprecated.pineappl.lz4 NNPDF31_nnlo_as_0118_luxqed MSHT20qed_nnlo > plot_script.py'
+    print *, '  - pineappl plot DY-LO-AA-deprecated.pineappl.lz4 NNPDF31_nnlo_as_0118_luxqed MSHT20qed_nnlo > plot_script.py'
     print *, '  - pineappl --help'
 
     call pineappl_grid_delete(grid)

examples/fortran/dyaa.output

@@ -1,5 +1,5 @@
  Generated DY-LO-AA-deprecated.pineappl.lz4 containing a a -> l+ l-.
  Try running (PDF sets must contain non-zero photon PDF):
    - pineappl convolve DY-LO-AA.pineappl.lz4 NNPDF31_nnlo_as_0118_luxqed
-   - pineappl --silence-lhapdf plot DY-LO-AA-deprecated.pineappl.lz4 NNPDF31_nnlo_as_0118_luxqed MSHT20qed_nnlo > plot_script.py
+   - pineappl plot DY-LO-AA-deprecated.pineappl.lz4 NNPDF31_nnlo_as_0118_luxqed MSHT20qed_nnlo > plot_script.py
    - pineappl --help

examples/mg5amcnlo/DY_14TEV_MG_3_3_2.sh

@@ -370,7 +370,7 @@ mg5_aMC launch.txt
 # try to find pineappl
 if which pineappl 2> /dev/null; then
     # step 6: change the bin limits from 0,1,2,3,... to the actual values
-    pineappl write --remap '40,45,50,55,60,64,68,72,76,81,86,91,96,101,106,110,115,120,126,133,141,150,160,171,185,200,220,243,273,320,380,440,510,600,700,830,1000,1500,3000' ${dataset}/Events/run_01/amcblast_obs_0.pineappl "${grid}".tmp
+    pineappl write --set-bins '40,45,50,55,60,64,68,72,76,81,86,91,96,101,106,110,115,120,126,133,141,150,160,171,185,200,220,243,273,320,380,440,510,600,700,830,1000,1500,3000' ${dataset}/Events/run_01/amcblast_obs_0.pineappl "${grid}".tmp
 
     # step 7: add some metadata (used mainly by the plot script)
     pineappl write "${grid}".tmp "${grid}" \
@@ -389,8 +389,8 @@ if which pineappl 2> /dev/null; then
 Generated ${grid}.
 
 Try using:
-  - pineappl convolute ${grid} LHAPDF_SET_NAME
-  - pineappl --silence-lhapdf plot ${grid} LHAPDF_SET_NAME1 LHAPDF_SET_NAME2 ... > plot_script.py
+  - pineappl convolve ${grid} LHAPDF_SET_NAME
+  - pineappl plot ${grid} LHAPDF_SET_NAME1 LHAPDF_SET_NAME2 ... > plot_script.py
   - pineappl --help
 EOF
 else

examples/mg5amcnlo/DY_14TEV_MG_3_5_7.sh

@@ -374,7 +374,7 @@ mg5_aMC launch.txt
 # try to find pineappl
 if which pineappl 2> /dev/null; then
     # step 6: change the bin limits from 0,1,2,3,... to the actual values
-    pineappl write --remap '40,45,50,55,60,64,68,72,76,81,86,91,96,101,106,110,115,120,126,133,141,150,160,171,185,200,220,243,273,320,380,440,510,600,700,830,1000,1500,3000' ${dataset}/Events/run_01/amcblast_obs_0.pineappl "${grid}".tmp
+    pineappl write --set-bins '40,45,50,55,60,64,68,72,76,81,86,91,96,101,106,110,115,120,126,133,141,150,160,171,185,200,220,243,273,320,380,440,510,600,700,830,1000,1500,3000' ${dataset}/Events/run_01/amcblast_obs_0.pineappl "${grid}".tmp
 
     # step 7: add some metadata (used mainly by the plot script)
     pineappl write "${grid}".tmp "${grid}" \
@@ -393,8 +393,8 @@ if which pineappl 2> /dev/null; then
 Generated ${grid}.
 
 Try using:
-  - pineappl convolute ${grid} LHAPDF_SET_NAME
-  - pineappl --silence-lhapdf plot ${grid} LHAPDF_SET_NAME1 LHAPDF_SET_NAME2 ... > plot_script.py
+  - pineappl convolve ${grid} LHAPDF_SET_NAME
+  - pineappl plot ${grid} LHAPDF_SET_NAME1 LHAPDF_SET_NAME2 ... > plot_script.py
   - pineappl --help
 EOF
 else

examples/object-oriented-cpp/dyaa.cpp

@@ -214,7 +214,7 @@ int main() {
       "Generated %s containing a a -> l+ l-.\n\n"
       "Try running (PDF sets must contain non-zero photon PDF):\n"
       "  - pineappl convolve %s NNPDF31_nnlo_as_0118_luxqed\n"
-      "  - pineappl --silence-lhapdf plot %s NNPDF31_nnlo_as_0118_luxqed "
+      "  - pineappl plot %s NNPDF31_nnlo_as_0118_luxqed "
       "MSHT20qed_nnlo > plot_script.py\n"
       "  - pineappl --help\n",
       filename.c_str(), filename.c_str(), filename.c_str());

examples/object-oriented-cpp/output

@@ -53,5 +53,5 @@ Generated DY-LO-AA.pineappl.lz4 containing a a -> l+ l-.
 
 Try running (PDF sets must contain non-zero photon PDF):
   - pineappl convolve DY-LO-AA.pineappl.lz4 NNPDF31_nnlo_as_0118_luxqed
-  - pineappl --silence-lhapdf plot DY-LO-AA.pineappl.lz4 NNPDF31_nnlo_as_0118_luxqed MSHT20qed_nnlo > plot_script.py
+  - pineappl plot DY-LO-AA.pineappl.lz4 NNPDF31_nnlo_as_0118_luxqed MSHT20qed_nnlo > plot_script.py
   - pineappl --help

pineappl_cli/README.md

@@ -3,9 +3,20 @@
 
 # PineAPPL CLI
 
-This is the command-line interface (CLI) to
-[`pineappl`](https://crates.io/crates/pineappl).
+This is the command-line interface (CLI) to [`pineappl`](https://crates.io/crates/pineappl).
+
+# Documentation
+
+A good starting point to learn what `pineappl` can do is the [CLI tutorial].
+For more information, see:
+
+- [Installation](https://nnpdf.github.io/pineappl/docs/installation.html): installation
+  instructions.
+- [CLI tutorial](https://nnpdf.github.io/pineappl/docs/cli-tutorial.html): a tutorial
+  on how to use the `pineappl` CLI interface.
+- [CLI reference](https://nnpdf.github.io/pineappl/docs/cli-reference.html): a reference
+  for the different parameters of the CLI.
 
 # Installation
 
-Run `cargo install pineappl_cli` to install the `pineappl` binary.
+In a development mode, run `cargo install pineappl_cli` to install the `pineappl` binary.