mirror of https://gitlab.com/QEF/q-e.git
5822e77399
and html files in Doc/ for user guide and developer manual as well git-svn-id: http://qeforge.qe-forge.org/svn/q-e/trunk/espresso@5729 c92efa57-630b-4861-b058-cf58834340f0 |
||
---|---|---|
.. | ||
helpdoc.d | ||
Makefile | ||
README.helpdoc | ||
callhtml.pl | ||
calltree.pl | ||
check_gui | ||
guihelp.xsl | ||
helpdoc | ||
helpdoc.schema | ||
release.sh |
README.helpdoc
--------------------------------- *** 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 ...