Differences

This shows you the differences between two versions of the page.

--- developers:link_shortcuts [2017/08/18 13:23] – [MathJax] Xavier Gonze
+++ developers:link_shortcuts [2019/10/24 02:41] (current) – removed Matteo Giantomassi
@@ Line 1: / Line 1: @@
-====== Shortcuts for Web links ======
-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, [[http://docs.mathjax.org/en/latest/mathjax.html|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.
-===== Syntax =====
-The [[wiki:syntax#links|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.
-===== Simple allowed internal links =====
-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 [[http://www.abinit.org/doc/helpfiles/for-v8.4/input_variables/html_automatically_generated/varbas.html#ecut|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 [[http://www.abinit.org/doc/helpfiles/for-v8.4/users/bibliography.html#Amadon2008|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 [[http://www.abinit.org/doc/helpfiles/for-v8.4/users/bibliography.html#Gonze2016|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.
-===== Internal links with a namespace =====
-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>
-===== External links =====
-As for dokuwiki, some [[wiki:syntax#external|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>
-===== MathJax =====
-Formulas written in LaTeX are interpreted automatically (at visualization time) thanks to the
-[[http://docs.mathjax.org/en/latest/mathjax.html|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 %%\b%%egin{equation} and %%\e%%nd{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}$$