This page concerns the YAML files in ~abinit/doc/*/origin_files, that are processed by the script ~abinit/doc/generate_doc.py to automatically generate HTML files in ~abinit/doc/*/generated_files.

Thanks to this processing, it has been possible to introduce shortcuts to ease the writing of many different hyperlinks in these YAML files. Also, MathJax for equations in LaTeX is activated, and the (few) specificities of its usage in the ABINIT doc are explained in the section MathJax of the present document.

The DokuWiki syntax is used, with two pairs of brackets and possible separators (:,# and |).
In the simple case, this gives

[[name]]

but, more generally

[[namespace:name#section|text]]

where namespace, section and text are optional (in such case, the adequate separator should not be mentioned). The namespace is not echoed in the Web page, while if a “text” is given, it will supercede the echo of the name in the Web page (see examples below).
Limitation : do not use parentheses within the pair of double brackets, the whole expression will not be recognized.

When an internal link is recognized, the dokuwiki item is replaced by the adequate HTML link by the script generate_doc.py.
Example :

[[ecut]] becomes <a href="../../input_variables/generated_files/varbas.html#ecut>ecut</a>

This will point to ecut.

There are a couple of names immediately recognized by generate_doc.py :

• as “ecut” above, the name of an abinit input variable (provided it is mentioned in abinit_vars.yml);
• the name of a bibliographical reference (provided it is mentioned in abiref.bib);
• the path to a file in a ~abinit/tests/*/Input directory;
• the path to a reference output file in a ~abinit/tests/tuto*/Refs directory.

Examples :

[[Amadon2008]] becomes <a href="../../bibliography/generated_files/bibliography.html#Amadon2008>[Amadon2008]</a>

this will point to Amadon2008.

[[Gonze2016|The last generic ABINIT article]] becomes <a href="../../bibliography/generated_files/bibliography.html#Gonze2016>The last generic ABINIT article</a>

this will point to The last generic ABINIT article (note the use of the | separator !).

[[tests/v1/Input/t01.in]] becomes <a href="../../tests/v1/Input/t01.in>~abinit/tests/v1/Input/t01.in</a>

The script generate_doc.py does a bit of formatting in these examples: it keeps one pair of square brackets in the case of a bibliographic reference, and add “~abinit/” in the case of a path.

Other internal links can be recognized thanks a namespace. A first set of allowed internal namespaces are “lesson”, “topic”, “help”, “bib”, “theorydoc”, and “varset”. In such cases, provided there is a corresponding generated HTML file in one of the ~abinit/doc/*/generated_files subdirectories, that has a name that start with the namespace and end with the name, the link will be established.

Examples :

  
[[lesson:gw1]] becomes <a href="../../tutorial/generated_files/lesson_gw1.html>gw1</a>

[[topic:PIMD#1|Introduction]] becomes <a href="../../topics/generated_file/topic_PIMD.html#1>Introduction</a>

Actually, using the real name of the file without suffix, e.g. lesson_gw1 will also be recognized, although this real name is echoed, instead of the name withouth namespace.

[[lesson_gw1]] becomes <a href="../../tutorial/generated_files/lesson_gw1.html>lesson_gw1</a>

There is an added formatting by generate_doc.py, in the case of the help files: [[help_codename]] is echoed “codename help file” :

[[help_abinit]] becomes <a href="../../tutorial/generated_files/help_abinit.html>abinit help file</a>

Also, the input variables for anaddb, optic and aim(bader) will be recognized if they are used with the namespaces “anaddb”, “optic” and “aim”. For the latter input variables, one has thus also the choice between the syntax [[executable:input_variable_name]] or [[input_variable_name@executable]]. For example [[anaddb:dipdip]] or [[dipdip@anaddb]]. In the first case, only dipdip is echoed, while in the second case, dipdip@anaddb is echoed.

[[anaddb:dipdip]] becomes <a href="../../input_variables/generated_files/varset_anaddb.html>dipdip</a>

[[dipdip@anaddb]] becomes <a href="../../input_variables/generated_files/varset_anaddb.html>dipdip@anaddb</a>

As for dokuwiki, some external links are also recognized. The following case are treated :

• a link that starts with “www.”
• the namespaces “http”, “https”, “ftp”, “file”.

Examples :

  
[[www.abinit.org]] becomes <a href="http://www.abinit.org">www.abinit.org</a>

[[https://wiki.abinit.org|The ABINIT Wiki] becomes <a href="https://wiki.abinit.org">The ABINIT Wiki</a>

Formulas written in LaTeX are interpreted automatically (at visualization time) thanks to the MathJax on-the-flight processor. For the ABINIT documentation, the conventions are :

• \$…\$ yields an “onlinecite” translation of the LaTeX formula;
• \$\$…\$\$ yields display mode, the LaTeX formula being rendered on one dedicated line;
• to have your equations numbered, use the display mode above and (inside the markers) declare your equation with the standard \begin{equation}$$ and $$\end{equation}

• when a \$ sign is inside a <pre> … </pre> HTML section, MathJax does not interpret it
• to prevent a real \$ to be interpreted, use \\\$

Examples :

$|\phi \ angle$
$$|\phi \ angle$$
$$\begin{equation} |\phi \ angle \end{equation}$$