Rework mg5 docs

docs/source/external/mg5.rst

@@ -1,17 +1,8 @@
 MadGraph5_aMC\@NLO
 ==================
 
-.. toctree::
-   :maxdepth: 1
-   :caption: Contents:
-
-   mg5_launch
-   mg5_cuts
-   mg5_patches
-
-
-Runcard structure
------------------
+Pinecard structure
+------------------
 
 - The ``output.txt`` file (compulsory). This file contains the instructions to
   generate the source code for the relevant process. For details, please see
@@ -20,20 +11,54 @@ Runcard structure
   ``@OUTPUT@`` must be used to generate the directory containing the source
   files.
 
-- The ``launch.txt`` file (compulsory). This file contains the instructions to
-  run the relevant process, including the relevant physical parameters and cuts,
-  more info in :doc:`mg5_launch`.
-
 - The ``analysis.f`` file (compulsory). This Fortran file must fill the
   histograms from which the |hwu| files and
-  the PineAPPL grids are generated. Note that a single histogram must not
+  the |pineappl| grids are generated. Note that a single histogram must not
   contain more than 100 bins, otherwise |mg5| will crash. However,
   big histograms can be split up into multiple histograms, for which the runner
-  will merge the PineAPPL grids together.
+  will merge the |pineappl| grids together.
 
 - The ``*.patch`` file(s) (optional). These are one or more ``.patch`` files
   that are applied after |mg5| has generated the sources.
 
+launch.txt (compulsory)
+^^^^^^^^^^^^^^^^^^^^^^^
+This file contains the instructions to
+run the relevant process, including the relevant physical parameters and cuts.
+
+Theory parameters
+#################
+
+To insert the actual values of the theory parameters coming from the theorycard
+we provide a special syntax. You can use the names
+``@GF``, ``@MH@``, ``@MT@``, ``@MW@``, ``@MZ@``, ``@WH@``, ``@WT@``, ``@WW@``,
+and ``@WZ@``, which will be replaced with their numerical values upon generation.
+The names are the same as chosen by ``mg5_aMC``, but written in
+uppercase and surrounded with ``@``. For details about more parameters, please
+see the ``Template/NLO/Cards/run_card.dat`` file in |mg5|.
+
+Cuts
+####
+
+They are implemented in two steps:
+
+1. cuts relevant *variables* are defined
+2. cuts *code* is implemented
+
+A list of available codes and variables can be obtained from the
+`repository <https://github.com/NNPDF/pinefarm/tree/main/src/pinefarm/external/mg5>`_.
+
+Patches
+#######
+
+For instance, to use a dynamical scale, a patch modifying ``setscales.f`` file
+should be included in the directory. To create patches use the command ``diff
+-Naurb original new > patch.patch``. The patches are applied in an unspecified
+order, using ``patch -p1 ...``.
+
+A list of available patches can be obtained from the
+`repository <https://github.com/NNPDF/pinefarm/tree/main/src/pinefarm/external/mg5>`_.
+
 Additional metadata
 -------------------
 
@@ -42,10 +67,10 @@ Additional metadata
 - ``launch.txt``: contains the generated ``launch.txt`` script (after all
   substitutions have been done)
 - ``patch``: a list of patches' names, one per row (corresponding to those
-  described in :doc:`mg5_patches`)
+  described in Patches)
 - ``tau_min``: the minimum :math:`\tau` value set by the user
 - ``user_cuts``: user defined cuts and cuts values, one per row in the format
-  ``cut=value`` (cuts are those defined in :doc:`mg5_cuts`)
+  ``cut=value`` (cuts are those defined in Cuts)
 - ``mg5amc_repo`` and ``mg5amc_revno``: The
   repository and revision number of the |mg5| version that was
   used to generate the grid.
@@ -79,6 +104,3 @@ Output
   The final three columns give the per mille differences of the central, minimum, and
   maximum scale varied results. Ideally the first two columns are the same and
   the remaining columns are zero.
-- ``pineappl.convolute``: Output of ``pineappl convolute``
-- ``pineappl.orders``: Output of ``pineappl orders``
-- ``pineappl.pdf_uncertainty``: Output of ``pineappl pdf_uncertainty``

docs/source/external/yadism.rst

@@ -1,8 +1,8 @@
 Yadism
 ======
 
-Runcard structure
------------------
+Pinecard structure
+------------------
 
 - The ``observable.yaml`` file (compulsory). This file contains the description
   of the observable requested (kind and kinematics), together with further
@@ -18,5 +18,5 @@ Additional metadata
 Output
 ------
 
-- ``DATASET.yaml``: is the other |yadism| output format, fully human readable
+- ``<PINECARD>.yaml``: is the other |yadism| output format, fully human readable
   (but a bit verbose)