quantum-espresso/dev-tools

          ---------------------------------
          *** 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 ...