1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
|
---------------------------------
*** 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 ...
|
