mirror of https://gitlab.com/QEF/q-e.git
139 lines
4.0 KiB
Plaintext
139 lines
4.0 KiB
Plaintext
---------------------------------
|
|
*** README file for HELPDOC ***
|
|
---------------------------------
|
|
|
|
|
|
1. HELPDOC PURPOSE
|
|
|
|
Short: transform INPUT_*.def into INPUT_*.xml|html|txt
|
|
|
|
HELPDOC is a small utility (located in ../dev-tools/) that
|
|
transforms INPUT_*.def files into INPUT_*.txt and INPUT_*.xml
|
|
files, and the latter are accordingly transformed into HTML format.
|
|
|
|
The idea is to enhance/replace the plain ascii descriptions of
|
|
input file syntax (i.e. INPUT_* files) with more structured and
|
|
descriptive format yielding an enhanced documentation + better
|
|
input syntax definition.
|
|
|
|
|
|
|
|
--
|
|
2. SOFTWARE REQUIREMENTS
|
|
|
|
Helpdoc depends on tclsh, tcllib, and xsltproc. For example, to
|
|
install these packages in GNU/Linux Debian-based distributions,
|
|
execute as root (or sudo):
|
|
|
|
apt-get install tcl tcllib xsltproc
|
|
|
|
or, on RedHat-based distributions, the analogous command
|
|
|
|
yum install tcl tcllib xsltproc
|
|
|
|
--
|
|
3. SYNTAX OF *.def FILES
|
|
|
|
Perhaps the first choice for a markup would be XML, yet its markup
|
|
is not very practical from typing point of view. Therefore *.def
|
|
files use a markup that involves less typing (i.e. like wiki's use
|
|
more practical markup than HTML).
|
|
|
|
Consider an XML example:
|
|
|
|
<var name="etot_conv_thr" type="REAL">
|
|
<default> 1.0D-4 </default>
|
|
<info>
|
|
convergence threshold on total energy (a.u) for ionic ...
|
|
</info>
|
|
</var>
|
|
|
|
The DEF markup (*.def) is more compact---involves less syntactic
|
|
sugar---but is otherwise equally well-defined:
|
|
|
|
var etot_conv_thr -type REAL {
|
|
default { 1.0D-4 }
|
|
info {
|
|
convergence threshold on total energy (a.u) for ionic ...
|
|
}
|
|
}
|
|
|
|
Full correspondence between XML and DEF markup is:
|
|
|
|
XML: <element attribute="value"> ... </element>
|
|
DEF: element -attribute value { ... }
|
|
|
|
Technically, DEF files are Tcl-scripts (hence they use the Tcl
|
|
syntax).
|
|
|
|
|
|
3.1 Differences between DEF and XML:
|
|
|
|
* some elements must have a name attribute (e.g. variable and namelist
|
|
must always have a name). For such elements the markup is simplified
|
|
from "element -name ident ..." to "element ident ..."
|
|
(i.e. -name is skipped).
|
|
|
|
|
|
* attributes must be specified on a single line:
|
|
|
|
# this is OK
|
|
elem1 -attr1 value1 -attr2 value2 { ... }
|
|
|
|
# this is BAD
|
|
elem1 -attr1 value1
|
|
-attr2 value2 { ... }
|
|
|
|
# but this is OK (because of line-continuation character "\")
|
|
elem1 -attr1 value1 \
|
|
-attr2 value2 { ... }
|
|
|
|
|
|
* separator between elements is either newline character or
|
|
semicolon (;). E.g.:
|
|
|
|
# this is OK
|
|
element1 -attribute1 value1 { ... }; element2 -attribute2 value2 { ... }
|
|
|
|
# this is BAD
|
|
element1 -attribute1 value1 { ... } element2 -attribute2 value2 { ... }
|
|
|
|
# this is OK
|
|
element1 -attribute1 value1 { ... }
|
|
element2 -attribute2 value2 { ....}
|
|
|
|
|
|
The DEF markup (elements and attributes) is defined in file
|
|
./helpdoc.schema (which uses its own schema language that was
|
|
inspired by RELAX NG schema language).
|
|
|
|
Making use of an element and/or attribute in *.def files which is
|
|
not defined in helpdoc.schema file, will produce an error during
|
|
def-->xml conversion (otherwise the helpdoc is not a full
|
|
validator).
|
|
|
|
|
|
--
|
|
4. HOW IT ALL WORKS
|
|
|
|
To transform INPUT_*.def file to INPUT_*.xml and INPUT_*.html
|
|
file, execute
|
|
|
|
either:
|
|
../dev-tools/helpdoc INPUT_whatever.def
|
|
|
|
or simply:
|
|
make INPUT_whatever.html
|
|
|
|
To convert all *.def to *.html files, use: make helpdoc
|
|
|
|
During execution, the helpdoc transforms the *.def file into *.xml
|
|
file and calls the xsltproc program that transforms the latter into
|
|
*.html file. The instructions for doing that are provided by an XSL
|
|
stylesheet (file: ./input_xx.xsl).
|
|
|
|
|
|
5. TO DO ...
|
|
|
|
Put here more descriptions on the markup ...
|