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
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html lang="en">
<head>
<title>GTML Reference Page</title>
<meta name="Author" content="Andrew E. Schulman,Bruno Beaufils, Gihan Perera">
<meta name="Generator" content="GTML 3.5.4">
<meta name="Keywords" content=
"HTML pre-processor, perl, script, web site design, templates, free
software, GPL">
<meta name="Description" content=
"GTML is a simple yet powerful HTML pre-processor, which has a lot of
features to design AND maintain entire web sites. It's syntax is very
close to the C language preprocessor one. Some of its features are: use
of macros, conditionnal processing, file inclusion, sitemap generation
and much more. It is written in perl.">
<link rel="Begin" type="text/html" href="http://sourceforge.net/projects/gtml/">
<link rel="Next" type="text/html" href="NEWS.html">
<link rel="Prev" href="gtml.html">
<link rel="Stylesheet" type="text/css" href="gtml.css">
</head>
<body text="#000033">
<!-- ---------- Title line ---------- -->
<center>
<table border="0" width="95%" bgcolor="#ffffcc" cellpadding="5" cellspacing="0" align="center">
<tr>
<td align="left">
<font size="2" face='Arial,Helvetica'>
<a href="gtml.html"><<</a>
</font>
</td>
<td align="center"><font color="#000066" face="Verdana,Arial,Helvetica" size="+3">
<b>GTML Reference Page</b>
</td>
<td align="right">
<font size="2" face='Arial,Helvetica'>
<a href="NEWS.html">>></a>
</font>
</td>
</tr>
</table>
</center>
<center>
<table width="75%" border="0" cellpadding="10">
<tr valign="top">
<td>
<p>This is the reference page for the HTML pre-processor <code>GTML</code>. It describes
all the <code>GTML</code> features and commands in detail. For more information about
getting <code>GTML</code>, see <a href="gtml.html"> the main <code>GTML</code> page</a>.
<a name="toc"></a>
<p><code>GTML</code> features fall into four main areas, and we'll look at them
in this order:
<ul>
<li><a href="#commands"> <code>GTML</code> commands</a> embedded among HTML text.
<li>The optional <a href="#project"> <code>GTML</code> project file</a>, which allows you
to manage a set of Web pages together.
<li><a href="#special">Special <em>named constants</em></a> generated or used
by <code>GTML</code>.
<li><a href="#cmdline">Command-line options</a>.
</ul>
<!-- ==================== Commands ==================== -->
<a name="commands"></a>
<h2>Commands</h2>
<p>The original syntax of <code>GTML</code> was stolen shamelessly from the C
language pre-processor, and has been adapted to suit Web site
management. It supports the following commands:
<ul>
<li><a href="#include"><code>include</code></a>
- Include the contents of another file.
<li><a href="#define"><code>define</code></a> and
<a href="#newdefine"> <code>newdefine</code></a>
- Create <em>named constants</em> which can be used as shorthand
definitions of frequently-used HTML segments.
<li><a href="#undef"><code>undef</code></a>
- Remove a named constant.
<li><a href="#timestamp"><code>timestamp</code></a> and
<a href="#mtimestamp"> <code>mtimestamp</code></a>
- Insert a formatted date/time stamp.
<li><a href="#literal"><code>literal</code></a>
- Turn off <code>GTML</code> processing.
<li><a href="#definechar"><code>definechar</code></a>
- Define characters (or strings) translations.
<li><a href="#entities"><code>entities</code></a>
- Convert special characters to HTML entities.
<li><a href="#if"><code>if, ifdef, ifndef, elsif, elsifdef, elsifndef, else, endif</code></a>
- Select sections of the source based on certain conditions.
<li><a href="#compress"><code>compress</code></a>
- Turn on file compression, eliminating HTML useless segments.
<li><a href="#sitemap"><code>sitemap</code></a> and <a href="#sitemap"><code>toc</code></a>
- Insert a map of all your site.
</ul>
<!-- -------------------- Syntax -------------------- -->
<h3>Command syntax</h3>
<p>There are two ways of writing commands:
<ul>
<li>You can insert the commands directly, in which case they are preceded by
`<code><strong>#</strong></code>', and must appear at the start of a separate line
(<strong>no preceeding spaces</strong>). Here's an example:<br>
<pre>
#include "header.txt"
</pre>
<li>The other method is to embed the command inside an HTML comment. In this
case, the line must begin with `<code><strong><!-- ###</strong></code>'
followed by the command name, followed by the close-comment tag
`<code><strong>--></strong></code>'. Here's the same example in this format:<br>
<pre>
<!-- ###include "header.txt" -->
</pre>
</ul>
<p>The first method is simpler, and is the recommended way of writing <code>GTML</code>
, if possible. However, if you're using an HTML authoring tool which complains
about <code>GTML</code> commands, you can use the second method to <em>hide</em> the
<code>GTML</code> commands from the tool.
<!-- -------------------- include -------------------- -->
<a name="include"></a>
<h3>#include</h3>
<p>If you have some common text which you want inserted in more than one Web
page, put it in a separate file - say, <code><strong>common.txt</strong></code>.
Then, at the place where you want the text in each file, put the following
line:
<pre>
#include "common.txt"
</pre>
<p><code>GTML</code> replaces this line with the entire contents of the file
<code><strong>common.txt</strong></code>.
<p>The name of the file can be defined in a named constant, as described next.
<p>The directories in which the file may be looked for can be defined in a
<a href="#searchpath">special</a> named constant.
<!-- -------------------- define -------------------- -->
<a name="define"></a>
<h3>#define</h3>
<p>This is a simple way to create shorthand definitions - what we call
<em>named constants</em>, or <em>macros</em> - for your frequently-used
text. For some text which you use often - say, an e-mail address - include a
line like this:
<pre>
#define MY_EMAIL gihan@pobox.com
</pre>
<p>This defines a <em>named constant</em> <var>MY_EMAIL</var> and its
<em>value</em> <samp>gihan@pobox.com</samp>. The value can be any text,
including spaces and HTML markup (leading spaces and tabs are ignored), as
long as <strong>it's all on one line</strong> or <strong>it's all on
multiple consecutives lines with a trailing `<code><strong>\</strong></code>' at the end of each
lines, except the last</strong>.
<p>To use this named constant, whenever you want your e-mail address,
specify it like this:
<pre>
<<MY_EMAIL>>
</pre>
<p>The double angle-brackets tell <code>GTML</code> to substitute this with its
definition (You can
<a href="#delimiters">specify your own choice of delimiters</a>
instead of the double-angle brackets).
<p>There are a few other things you should know about <code>#define</code>:
<ul>
<li>Named constants can be set <a href="#cmdline">from the command line</a>
when you run <code>GTML</code>.
<li><strong>Nested definition values</strong><br>
The value of a named constant can itself contain other named constants,
like this:
<pre>
#define MAILTO <a href="mailto:<<MY_EMAIL>>">
</pre>
<p><code>GTML</code> will happily do both substitutions. <br>
<em>Note</em>: Definitions are evaluated at time of use, not time of
definition. This allows you to change the nested value to get a
different result. To get definitions body evaluated at time of
definition, you must use the <code>#define!</code> command.
<a name="define!"></a>
<li><strong>Nested definition names</strong><br>
If you want the <em>name</em> of a named constant to contain other named
constants, use <code>#define!</code> instead of
<code>#define</code>. For example, this sets the named constant
<var>A</var> to <samp>fred</samp>:
<pre>
#define BLAH A
#define! <<BLAH>> fred
</pre>
<p>(This doesn't achieve much here, but typically the second line is in
a separate file, which is included by the file with the first line).
<a name="define+"></a>
<li><strong>Added values</strong><br>
If you want to add something to the definition of a named constant, use
<code>#define+</code>. For example, this sets the named constant
<var>A</var> to <samp>foobar</samp>:
<pre>
#define A foo
#define+ A bar
</pre>
<li><strong>Undefined values</strong><br>
If a named constant is not defined before it's used, its value is a
blank string.
<li><strong>Re-defining values</strong><br>
It's perfectly OK to have more than one <code>#define</code> for the
same named constant. You can use this to change the value of a named
constant part-way through the processing.
<li><strong>Pre-defined values</strong><br>
<code>GTML</code> <a href="#special">creates some named constants</a>
for you automatically, such as the file name and links to the previous
and next files.
<li><strong>Variables values</strong><br>
Sometimes the frequently-used text you want to shorthand may embed some
variable pieces. <code>GTML</code> allows you to specify what the pieces are which
may vary, the same way the C language preprocessor does for macros with
arguments. Parameters are enclosed in parenthesis and seperated by a
comma. For instance, this creates a shortand to make HTML links:
<pre>
#define url(x,y) <a href="mailto:x">y</a>
</pre>
<p>Now the use of
<samp>
<<url(<<MY_EMAIL>>,Gihan)>>
</samp> will give:
<pre>
<a href="mailto:gigan@pobox.com">Gihan</a>
</pre>
<li><strong>Added variables values</strong><br>
If you add a variable valued definition with <code>#define+</code>, then
you <strong>add</strong> the parameter to the initial constant. For
instance, this adds a third parameter to the <var>url</var> macro:
<pre>
#define+ url(x) <a href="http://x">Perera</a>
</pre>
<p>Now guess what the following line will give:
<pre>
<<url(<<MY_EMAIL>>,Gihan,www.pobox.com/~gihan)>>
</pre>
<p>Yeah, you find:
<pre>
<a href="mailto:gigan@pobox.com">Gihan</a><a href="http://www.pobox.com/~gihan">Perera</a>
</pre>
<p>If you want to use commas in your arguments you just have to
<strong>quote the complete argument</strong> with single or double
quotes.
</ul>
<!-- -------------------- newdefine -------------------- -->
<a name="newdefine"></a>
<a name="newdefine!"></a>
<h3>#newdefine</h3>
<p>This is identical to <a href="#define"><code>#define</code></a>, except that the
definition applies only if the named constant has not been defined already. If
it has been defined, the old definition is unchanged. <code>#newdefine!</code>
is identical to <code>#define!</code> with the same exception.
<!-- -------------------- undef -------------------- -->
<a name="undef"></a>
<h3>#undef</h3>
<p>Use this to remove the definition of a named constant:
<pre>
</pre>
<p>If the named constant didn't exist previously, this does nothing.
<!-- -------------------- if -------------------- -->
<a name="if"></a>
<h3>#if, #ifdef, #ifndef, #elsif, #elsifdef, #elsifndef, #else, #endif</h3>
<p>These commands are used together for conditional output:
<ul>
<li><strong><code>#if <<FRED>> == foo</code></strong><br>
Process the following lines only if after substitution, the left and
right values are equal. Here if value of named constant
<var>FRED</var> is equal to <samp>foo</samp>.
<li><strong><code>#if foo != <<FRED>> </code></strong><br>
Process the following lines only if after substitution, the left and
right values are different. Here if value of named constant
<var>FRED</var> is different from <samp>foo</samp>.
<li><strong><code>#ifdef FRED</code></strong><br>
Process the following lines only if the named constant <var>FRED</var>
is defined.
<li><strong><code>#ifndef FRED</code></strong><br>
Process the following lines only if the named constant <var>FRED</var>
is <em>not</em> defined.
<li><strong><code>#elsif <<FRED>> == foo</code></strong><br>
If previous lines were not processed, then process the following lines
only if after substitution, the left and right values are equal.
<li><strong><code>#elsif <<FRED>> != foo</code></strong><br>
If previous lines were not processed, then process the following lines
only if after substitution, the left and right values are different.
<li><strong><code>#elsifdef FRED</code></strong><br>
If previous lines were not processed, then process the following lines
only if the named constant <var>FRED</var> is defined.
<li><strong><code>#elsifndef FRED</code></strong><br>
If previous lines were not processed, then process the following lines
only if the named constant <var>FRED</var> is not defined.
<li><strong><code>#else</code></strong><br>
The opposite effect of the most recent matching <code>#if</code>,
<code>#ifdef</code>, <code>#ifndef</code>, <code>#elsif</code>,
<code>#elsifdef</code> or <code>#elsifndef</code>.
<li><strong><code>#endif</code></strong><br>
End a block of conditional output. Every <code>#if</code>,
<code>#ifdef</code> or <code>#ifndef</code> must have a matching
<code>#endif</code>
</ul>
<p>Conditional blocks can be nested.
<!-- -------------------- timestamp -------------------- -->
<a name="timestamp"></a>
<h3>#timestamp</h3>
<p>The special named constant <var>TIMESTAMP</var> evaluates to the current
date and time. But to use it, you must tell <code>GTML</code> what format to use to print
the date/time.
<p>The format string is specified in the <code>#timestamp</code> statement
like this:
<p>
<pre>
#timestamp $dd/$MM/$yy at $hh:$mm:$ss
</pre>
<p>The value of <samp><<TIMESTAMP>></samp> will then be:
<samp>8/06/96 at 11:45:03</samp>.
<p>As you can see, certain strings (like <code>$dd</code>) are replaced with
values. The full set of substitution strings is as follows (everything else is
left unchanged in the format string):
<p>
<table cellpadding="5" border="1">
<tr><td>$hh</td> <td>Hour (00 to 23)</td></tr>
<tr><td>$mm</td> <td>Minute (00 to 59)</td></tr>
<tr><td>$ss</td> <td>Seconds (00 to 59)</td></tr>
<tr><td>$Day</td> <td>Full weekday name (Sunday to Saturday)</td></tr>
<tr><td>$Ddd</td> <td>Short weekday name (Sun to Sat)</td></tr>
<tr><td>$dd</td> <td>Day of the month (1 to 31)</td></tr>
<tr><td>$ddth</td> <td>Day of the month with ordinal extension (1st to 31th)</td></tr>
<tr><td>$MM</td> <td>Month number (1 to 12)</td></tr>
<tr><td>$Month</td> <td>Full month name (January to December)</td></tr>
<tr><td>$Mmm</td> <td>Short month name (Jan to Dec)</td></tr>
<tr><td>$yyyy</td> <td>Year (e.g. 1996)</td></tr>
<tr><td>$yy</td> <td>Short year (e.g. 96)</td></tr>
</table>
<p>Monthnames are output in English by default; but they can be output in
other languages, according to the <a href="#language">LANGUAGE special definition</a>.
<!-- -------------------- mtimestamp -------------------- -->
<a name="mtimestamp"></a>
<h3>#mtimestamp</h3>
<p>This is identical to <a href="#timestamp"><code>timestamp</code></a>, except that
the time used is not the current one, but the time the file was last modified.
<!-- -------------------- literal -------------------- -->
<a name="literal"></a>
<h3>#literal</h3>
<p>The command <code>#literal ON</code> tells <code>GTML</code> to stop interpreting lines
beginning with `<code><strong>#</strong></code>' as <code>GTML</code> commands, until the next <code>#literal
OFF</code> line. Defined constants are still substituted, and
<a href="#entities">entities are translated</a> if desired.
<p>For example, this is useful for bracketing blocks of C code, which might
have lines beginning with `<code><strong>#</strong></code>'.
<!-- -------------------- entities -------------------- -->
<a name="entities"></a>
<h3>#entities</h3>
<p>The command <code>#entities ON</code> tells <code>GTML</code> to convert the
characters `<code><strong><</strong></code>', `<code><strong>></strong></code>' and `<code><strong>&</strong></code>' into HTML
entities so they aren't treated as part of HTML commands. Use <code>#entities
OFF</code> to turn off
this conversion.
<p>This is useful for bracketing blocks of program code, which often contain
these characters.
<!-- -------------------- definechar -------------------- -->
<a name="definechar"></a>
<h3>#definechar</h3>
<p>Basic HTML authorized characters may only be ASCII characters. Accentuated
characters are coded in HTML in a certain way. For instance the `<code><strong>é</strong></code>'
character is coded `<code><strong>&eacute;</strong></code>'. You may want to input `<code><strong>é</strong></code>'
in your source file, and have the right code used in your HTML file. This
character's translation may be defined with the <code>#definechar</code>
command, like in this example:
<pre>
#definechar é &eacute;
</pre>
<p>Sometimes you might want to input special characters that are not available
on your keyboard, but do not want to input its HTML code (Think of the German
`<code><strong>ß</strong></code>' on an English keyboard). For instance if you want all occurrances
of `<code><strong>ss</strong></code>' in your source file to be translated into `<code><strong>ß</strong></code>', you
can use the <code>#definechar</code> command:
<pre>
#definechar ss &szlig;
</pre>
<!-- -------------------- compress -------------------- -->
<a name="compress"></a>
<h3>#compress</h3>
<p>The command <code>#compress ON</code> tells <code>GTML</code> to begin producing
compressed HTML code, i.e. stripping multiple spaces, removing newlines, HTML
comments, and all other stuff useless for an HTML browser to render a
page. This compression is done on the output file until the next <code>#compress
OFF</code>.
<!-- -------------------- sitemap -------------------- -->
<a name="sitemap"></a>
<h3>#sitemap, #toc</h3>
<p>When you specify a <a href="#hierarchy"> hierarchy of pages</a> in your
<a href="#project">project file</a> you may insert a table of contents, or site map,
of those pages, using the command <code>#sitemap</code>, or
<code>#toc</code>.
<p>See <a href="#hierarchy">Document hierarchy</a> specifications for more
information on how the list is created.
<!-- ==================== Project files ==================== -->
<a name="project"></a>
<h2><code>GTML</code> project files</h2>
<p>Because <code>GTML</code> is most useful for managing multiple files, it's quite
common to change something in a #include'd file, and then run <code>GTML</code> on all
the `<code><strong>.gtm</strong></code>' files which use it.
<p>To make this procedure easier, <code>GTML</code> supports a concept of a <em>project
file</em>. This is a simple text file with the extension `<code><strong>.gtp</strong></code>'. It
can contain:
<ul>
<li><strong><code>define ...</code></strong><br>
As for <code><a href="#define">#define</a></code> in a source file.
<li><strong><code>define! ...</code></strong><br>
As for <code><a href="#define!">#define!</a></code> in a source file.
<li><strong><code>define+ ...</code></strong><br>
As for <code><a href="#define+">#define+</a></code> in a source file.
<li><strong><code>newdefine ...</code></strong><br>
As for <code><a href="#newdefine">#newdefine</a></code> in a source file.
<li><strong><code>newdefine! ...</code></strong><br>
As for <code><a href="#newdefine!">#newdefine!</a></code> in a source file.
<li><strong><code>undef ...</code></strong><br>
As for <code><a href="#undef">#undef</a></code> in a source file.
<li><strong><code>timestamp ...</code></strong><br>
As for <code><a href="#timestamp">#timestamp</a></code> in a source file.
<li><strong><code>mtimestamp ...</code></strong><br>
As for <code><a href="#mtimestamp">#mtimestamp</a></code> in a source file.
<li><strong><code>if ...</code></strong><br>
<strong><code>ifdef ...</code></strong><br>
<strong><code>ifndef ...</code></strong><br>
<strong><code>elsif ...</code></strong><br>
<strong><code>elsifdef ...</code></strong><br>
<strong><code>elsifndef ...</code></strong><br>
<strong><code>else</code></strong><br>
<strong><code>endif</code></strong><br>
As for <code>
<a href="#if">#if, #ifdef, #ifndef, #elsif, #elsifdef, #elsifndef, #else, #endif</a></code>
in a source file.
<li><strong><code>definechar ...</code></strong><br>
As for <a href="#definechar">#definechar</a> in a source file.
<li><strong><code>compress ...</code></strong><br>
As for <a href="#compress">#compress</a> in a source file.
<li><strong><code>include ...</code></strong><br>
As for <a href="#include">#include</a> in a source file, but only on project
files.
<li><strong><code>// ...</code></strong><br>
Comment lines (the `<code><strong>//</strong></code>' must be the first characters on the line), which
are ignored. Blank lines are also ignored.
<li><strong><code>allsource</code></strong><br>
This is a shorthand way of specifying all source files from the current
directory and sub-directories (recursively).
<li><strong><code>filename alias file</code></strong><br>
This is used to make an alias to a file, so that you may use the alias,
as a defined constant, instead of the filename itself in source
files. <code>GTML</code> will compute the right relative path to the file in each
source file. This way you may move your files wherever you want, <code>GTML</code>
will be able to recreate your pages without having to modify the source
files.
<li><code><strong>filename.gtm</strong></code><br>
All other lines are names of source files, which are processed by <code>GTML</code>
in turn.
<p>These files can be in other directories below the current
directory. Simply specify the file name relative to the current
directory (e.g. <samp>sub/fred/index.gtm</samp>).
<p>The file can be a defined alias filename. In this case use it as a
filenamed constant, e.g.
<pre>
filename FOO bar/foo
<<FOO>>
</pre>
<p>The file name can be followed by a level number and a title, to be
used in <a href="#hierarchy">creating a hierarchy of documents</a>. In
this case the file is processed after the project file has been
completely read (in order to have the complete document hirearchy).
<li><strong><code>hierarchy</code></strong><br>
This is used to process all files of the declared hierarchy so far, so
that you may process those files more than once, if you want to change
some named constant values between each process. If not used
files of the hierarchy are processed after the project file has been
entirely read.
</ul>
<p>When you run <code>GTML</code> with the project file as a command-line argument, it
will process all the source files in the project file. They will all inherit
the <code>define</code>, <code>definechar</code> and <code>timestamp</code>
values, if any, in the project file. The <code>mtimestamp</code> value will
change according to the modification date of the appropriate source file.
<p>You may use a project file, but process only selected source files
(declared in the project) with the
<a href="#optionf"> `<code><strong>-F</strong></code>' command line argument</a>.
<p>Note that <code>#define</code>, <code>#newdefine</code> and
<code>#undef</code> commands inside a file are local to that file - they don't
carry over to the next file in the project. However, named constants defined
in the project file are inherited by all files in the project.
<!-- -------------------- Hierarchy -------------------- -->
<a name="hierarchy"></a>
<h3>Document hierarchy</h3>
<p><code>GTML</code> allows you to create a hierarchy of Web pages, with links between
them. Each Web page can have a link to the previous page, the next page, or
one level up in the hierarchy. Obviously, some of these links don't apply to
some pages - <code>GTML</code> generates only those that apply to each page.
<h4>Describing the hierarchy</h4>
<p>You describe the document hierarchy to <code>GTML</code> by listing the file names in
the project file in a certain order, with a document level and title for
each. Level 1 is for top-level documents, and 2, 3, 4, and so on are lower
levels. File names without a level have no hierarchical information attached
to them.
<p>When <code>GTML</code> processes a file, it defines special named constants which can
be used in exactly the same way as <a href="#define">other named constants</a>.
<p>For each file, <code>GTML</code> generates the named constants,
<var>LINK_PREV</var>,
<var>LINK_NEXT</var> and
<var>LINK_UP</var>. These correspond to the file names of the previous file,
next file and one level up in the hierarchy. In addition, it also generates
the corresponding named constants
<var>TITLE_PREV</var>,
<var>TITLE_NEXT</var>,
<var>TITLE_UP</var> and
<var>TITLE_CURRENT</var> to be the titles of these files (As stated above,
the title follows the level number in the project file).
<p>Some of these named constants may not be applicable to some files, in which
case the named constant is not defined for that file.
<h4>Example</h4>
<p>Here's an extract from a hypothetical <code>GTML</code> project file:
<pre>
contents.gtm 1 Table of Contents
chapter1.gtm 2 Introduction
sec11.gtm 3 What's the Problem
sec12.gtm 3 Old Approaches
sec13.gtm 3 New Idea
chapter2.gtm 2 Historical Evidence
sec21.gtm 3 Early 1900's
sec22.gtm 3 Recent Findings
chapter3.gtm 2 Our Bright Idea
</pre>
<p>To take a simple case, the file <code><strong>sec21.gtm</strong></code> will have
<code>LINK_NEXT</code> set to <code><strong>sec22.html</strong></code> (and <code>TITLE_NEXT</code>
set to <em>Recent Findings</em>) and <var>LINK_UP</var> set to
<code><strong>chapter2.html</strong></code> (and <var>TITLE_UP</var> set to <em>Historical
Evidence</em>). <var>LINK_PREV</var> and <var>TITLE_PREV</var> will be
undefined.
<h4>Using the links</h4>
<p>The links can be used to create <em>navigation links</em> between the
documents. In other words, each document can have links up the
hierarchy and to the next and previous documents.
<p>Typically, you would place the navigation information in a common file and
<code>#include</code> it into each <code>GTML</code> source file. The <code>GTML</code>
<code>#ifdef</code> command can be used to exclude links which don't apply to
a particular file.
<p>Here's a simple example:
<pre>
#ifdef LINK_NEXT
<p>Next document: <a href="<<LINK_NEXT>>"><<TITLE_NEXT>></a>
#endif
#ifdef LINK_PREV
<p>Previous document: <a href="<<LINK_PREV>>"><<TITLE_PREV>></a>;
#endif
#ifdef LINK_UP
<p>Up one level: <a href="<<LINK_UP>>"><<TITLE_UP>></a>;
#endif
</pre>
<a name="toc"></a>
<h4>Creation of table of contents</h4>
<p>When you have described a document hierarchy, and you use a
<a href="#sitemap"> <code>#toc</code> or <code>#sitemap</code></a> command into your
source file, <code>GTML</code> includes a sitemap generated as a list with the help of the
<var>__TOC_#__(x)</var>, and <var>__TOC_#_ITEM__(x,y)</var> special named
constants (`<code><strong>#</strong></code>' being a file level).
<p>With the previous example it gives:
<pre>
<<__TOC_1__('
<<__TOC_1_ITEM__('contents.html','Table of Contents')>>
<<__TOC_2__('
<<__TOC_2_ITEM__('chapter1.html','Introduction')>>
<<__TOC_3__('
<<__TOC_3_ITEM__('sec11.html','What's the Problem')>>
<<__TOC_3_ITEM__('sec12.html','Old Approaches')>>
<<__TOC_3_ITEM__('sec13.html','New Idea')>>
')>>
<<__TOC_2_ITEM__('chapter2.html','Historical Evidence')>>
<<__TOC_3__('
<<__TOC_3_ITEM__('sec21.html','Early 1900's')>>
<<__TOC_3_ITEM__('sec22.html','Recent Findings')>>
')>>
')>>
')>>
</pre>
<p><var>__TOC_#__(x)</var>, and <var>__TOC_#_ITEM__(x,y)</var> have
the following default values:
<pre>
#define __TOC_#__(x) <ul>x</ul>
#define __TOC_#_ITEM__(x,y) <li><a href="x">y</a>
</pre>
<p>You may redefine this constant to whatever you want as long as you respect
the number of variables.
<!-- ==================== Special Macros ==================== -->
<a name="special"></a>
<h2>Special definitions</h2>
<h4>Environment</h4>
<p>All environment variables are defined as named constants by <code>GTML</code>.
<h4>Current file names</h4>
<p>The special named constants <var>ROOT_PATH</var>, <var>BASENAME</var>,
<var>FILENAME</var> and <var>PATHNAME</var> are set to the current
path to root of the project (where the project file resides), output file name
without any extension and excluding any directory path information, output
file name excluding any directory path information, and directory path
information relative to the path to the root of the project.
<a name="searchpath"></a>
<h4>Search path for include files</h4>
<p><code>GTML</code> always searches for include files in the directory of the processed
source file first, then the current directory (where the <code>GTML</code> command is
executed).
<p>In addition, if you define the named constant <var>INCLUDE_PATH</var>,
<code>GTML</code> will interpret it as a list of directories (separated by colons), to
search for include files. Those directories may be absolute, or relative to
the root path of the project.
<h4>Output directory</h4>
<p>By default, <code>GTML</code> writes its output files to the same directory as the
corresponding source file. You can override this by defining the named
constant <var>OUTPUT_DIR</var> as the name of the output directory.
<p>If you are doing this with a project file, specify <var>OUTPUT_DIR</var>
as the top-level output directory. <code>GTML</code> will create the same directory
hierarchy for the output files as for the input files (It creates
sub-directories as required).
<a name="extension"></a>
<h4>Output suffix</h4>
<p>By default all created files are created by changing the <strong>.gtm</strong>, or
<strong>.gtml</strong> extension of the source file to the <strong>.html</strong> one.
<p>You may change this behavior by defining the special constant
<var>EXTENSION</var> to whatever extension you want.
<p>The definition of this constant does not have sense in a source file, since
the output file is already created the moment GTML starts to parse the source
file. It makes sense however to define it in the
<a href="#project">project file</a> or on the <a href="#cmdline">command line</a>.
<p>If the suffix is preceded by two dots as in <code><strong>gtml.css..gtm</strong></code>, then the
source suffix is not replaced, but just removed, as in <code><strong>gtml.css</strong></code>.
<h4>Fast generation</h4>
<p><code>GTML</code> only processes files which are younger than the output files which
they might produce.
This is very useful, as it increases the generation speed of web
sites with a big number of pages, when only one of them has been changed. Same
kind of the way <code>make</code> works.
<p>To enable this feature you just have to define the special constant
<var>FAST_GENERATION</var>. The use of this constant will work only in
<a href="#project"><code>GTML</code> project files</a> or on the <a href="#cmdline">command line</a>.
<p>This feature does not take into account included files, but only the main
gtml source, and the wanted output. To deal with more complex file
dependencies you may use the <code>make</code> tool in conjunction with the
<a href="#optionf">`<code><strong>-F</strong></code>'</a> and
<a href="#optionm">`<code><strong>-M</strong></code>'</a> command line arguments.
<a name="language"></a>
<h4>Language localisation</h4>
<p>By default all timestamps produce monthnames and daynames which are output
in English. You can output them in other languages by defining the constant
<var>LANGUAGE</var> to a value corresponding to an available language.
<p>As of today seven languages are available. The default one is
English. Following is the list of those language with the corresponding value
for <var>LANGUAGE</var> constant:
<ul>
<li><code>fr</code> for French ;
<li><code>de</code> for German ;
<li><code>ie</code> for Irish ;
<li><code>it</code> for Italian ;
<li><code>nl</code> for Dutch ;
<li><code>no</code> for Norvegian ;
<li><code>se</code> for Swedish.
</ul>
<p>If you can send me month and day names in other languages, just do it, I
will integrate it in following versions of <code>GTML</code>.
<a name="delimiters"></a>
<h4>Substitution delimiters</h4>
<p>The default delimiters for substituting named constants are
`<code><strong><<</strong></code>' and `<code><strong>>></strong></code>'. You can change these to any
other strings by defining the named constants <var>OPEN_DELIMITER</var> and
<var>CLOSE_DELIMITER</var> respectively.
<p>For example, if you had the following lines:
<pre>
#define OPEN_DELIMITER {{
#define CLOSE_DELIMTER }}
#define MY_EMAIL gihan@pobox.com
</pre>
<p>then GTML substitutes <var>MY_EMAIL</var> when it finds the text
<samp>{{MY_EMAIL}}</samp> instead of the default
<samp><<MY_EMAIL>></samp>.
<h4>Document hierarchy links</h4>
<p>As described above, <code>GTML</code>
<a href="#hierarchy">defines several named constants</a> for links between documents.
<h4>Embedded Perl code</h4>
<p>You may embed Perl code into your <code>GTML</code> source file, and have the result
of the last evaluated expression inserted in your output file, with the help of
the one argument macro <var>__PERL__</var>.
<p>Here is an example inserting the size of the source file:
<pre>
<<__PERL__(return (stat(<<ROOT_PATH>><<BASENAME>>.".gtm"))[7];)>>
</pre>
<h4>Embedded system command code</h4>
<p>You may embed system command output into your <code>GTML</code> source file, with the help of
the one argument macro <code>__SYSTEM__</code>.
<p>Here is an example inserting the list of files in the current directory:
<pre>
<<__SYSTEM__(dir)>>
</pre>
<!-- ==================== Command-line ==================== -->
<a name="cmdline"></a>
<h2>Command-line arguments</h2>
<!-- -------------------- -D -------------------- -->
<a name="optiond"></a>
<h3>-D</h3>
<p>When you run <code>GTML</code> from the command line, you can define named constants
like this:
<p><samp>-DMY_EMAIL=fred</samp>
<p>This is the same as <samp>#define MY_EMAIL fred</samp> in the file.
<p>These definitions can occur anywhere within the command-line options,
but only affect the files <em>after</em> them. For example, if your
command line is:
<pre>
perl gtml.pl fred.gtm -DMY_EMAIL=fred bill.gtm harry.gtm
</pre>
<p>then the <var>MY_EMAIL</var> definition doesn't apply to
<code><strong>fred.gtm</strong></code>.
<!-- -------------------- -F -------------------- -->
<a name="optionf"></a>
<h3>-F</h3>
<p>When you run <code>GTML</code> from the command line on a project file you may want
to process only some of the files used in it. This may be very useful in
conjunction with <code>make</code> for page regeneration based on complex
files dependencies (induced by <code>#include</code> commands).
<p>To process only one file of a project you can use the `<code><strong>-F</strong></code>'
argument followed by the name of the file to process. File to be processed
must appear, on the command line, before the project file it appears in.
<p>Let us suppose we have this project file, called <code><strong>foo.gtp</strong></code>:
<pre>
// Beginning of foo.gtp
define MAIL beaufils@lifl.fr
foo.gtm
bar.gtm
// End of foo.gtp
</pre>
<p>If you just want to regenerate the <code><strong>bar.html</strong></code> file your command
line will be:
<pre>
perl gtml -Fbar.gtm foo.gtp
</pre>
<p>List of files to processed is cleared after each project file treatment.
<!-- -------------------- -M -------------------- -->
<a name="optionm"></a>
<h3>-M</h3>
<p>When you run <code>GTML</code> with the `<code><strong>-M</strong></code>' command line argument, <code>GTML</code>
process project and source files, but do not produce ouput files. <code>GTML</code>
generates a makefile ready to create output files.
<p>If you do not specify a filename, the generated makefile is created under
the <code><strong>GNUmakefile</strong></code> name.
<p>To specify a filename, just add it after the `<code><strong>-M</strong></code>' argument, with a
colon between the option and the file name.
<!-- -------------------- -h -------------------- -->
<a name="optionh"></a>
<h3>-h, --help</h3>
<p>To get a small command line usage description you can use the
`<code><strong>-h</strong></code>', or `<code><strong>--help</strong></code>' command line argument.
<!-- -------------------- --silent -------------------- -->
<a name="optionv"></a>
<h3>--silent</h3>
<p>If you specify the `<code><strong>--silent</strong></code>' command line argument, <code>GTML</code> will
produce no processing information during its work.
<!-- -------------------- --version -------------------- -->
<a name="optionv"></a>
<h3>--version</h3>
<p>To get the version number of the <code>GTML</code> you are currently using you can
use the `<code><strong>--version</strong></code>' command line argument.
</td>
</tr>
</table>
</center>
<center>
<table borde="0" width="100%" align="center">
<tr>
<td align="left">
<font size="2" face="Arial,Helvetica" color="#000066">
This page has been accessed <!--#echo var="URL_COUNT"--> times since
<!--#echo var="URL_COUNT_RESET"-->.
</font>
</td>
<td align="right">
<font size="2" face="Arial,Helvetica">
<a href="gtml.html"><< Home</a>
<a href="sitemap.html">Sitemap</a>
<a href="NEWS.html">Revision history >></a>
</font>
</td>
</tr>
</table>
</center>
<center>
<hr width="100%">
<table align="center" width="100%" border="0">
<tr>
<td align="left" valign="top">
<font size="2" face="Arial,Helvetica" color="#000066">
<a href="http://sourceforge.net/projects/gtml/">GTML home page</a><br>
<em>Last modification: 1999/9/12 at 18:59</em><br>
</font>
</td>
<td align="right">
<font size="2" face="Arial,Helvetica" color="#000066">
Copyright © 1996-1999 <a href="http://www.pobox.com/~gihan">Gihan Perera</a>
(<a href="mailto:gihan@pobox.com">gihan@pobox.com</a>)<br>
Copyright © 1999 <a href="http://www.lifl.fr/~beaufils">Bruno Beaufils</a>
(<a href="mailto:beaufils@lifl.fr">beaufils@lifl.fr</a>)<br>
Copyright © 2004 <a href="http://home.comcast.net/~andrex">Andrew E. Schulman</a>
(<a href="mailto:schulman@users.sourceforge.net">schulman@users.sourceforge.net</a>)<br>
</font>
</td>
</tr>
</table>
</center>
</body>
</html>
|
