« back to all changes in this revision
Viewing changes to doc/sgmltexi.info-1
- browse files at revision 1
- compare with another revision
- download diff
- download tarball
- view history from revision 1
- Committer: Bazaar Package Importer
- Author(s): Gaetano Paolone (bigpaul)
- Date: 2004-01-05 20:04:06 UTC
- Revision ID: james.westby@ubuntu.com-20040105200406-qt6ax0cotplbpded
Tags: 2003.00.00-2
* Description improved
(closes: #209695)
* closing NMU: (closes: #148141)
(closes: #144278)
(closes: #209695)
* closing NMU: (closes: #148141)
(closes: #144278)
- files added:
- .bzr-builddeb
- bin
- debian
- doc
- doc/.ispell_default
- doc/sgmltexi
- man
- old
- po
- share
- share/entities
- share/sgmltexi.cat
added
removed
doc/sgmltexi.info-1
1
This is sgmltexi.info, produced by makeinfo version 4.3 from
2
sgmltexi.texinfo.
3
4
INFO-DIR-SECTION Texinfo documentation system
5
START-INFO-DIR-ENTRY
6
* Sgmltexi: (sgmltexi). Sgmltexi
7
END-INFO-DIR-ENTRY
8
9
Sgmltexi is an SGML system (DTD and tools) to make Texinfo
10
documentation using SGML. The Sgmltexi DTD is designed to follow most
11
of the Texinfo philosofy, hiding the node managing.
12
13
Sgmltexi is to be intended as a simplified Texinfo using SGML; that
14
is: you cannot do all that it is possible with Texinfo alone. Sgmltexi
15
impose some restrictions, but maybe it can be simpler to write Texinfo
16
documentation this way.
17
18
Copyright (C) 2000-2003 Daniele Giacomini <daniele@swlibero.org>
19
20
Permission is granted to copy, distribute and/or modify this
21
document under the terms of the GNU Free Documentation License, Version
22
1.1 or any later version published by the Free Software Foundation;
23
with no Invariant Sections, with no Front-Cover Texts, and with no
24
Back-Cover Texts. A copy of the license is included in the section
25
entitled "GNU Free Documentation License".
26
27
28
File: sgmltexi.info, Node: Top, Next: Top, Prev: Top, Up: (dir)
29
30
Sgmltexi
31
********
32
33
Sgmltexi is an SGML system (DTD and tools) to make Texinfo
34
documentation using SGML. The Sgmltexi DTD is designed to follow most
35
of the Texinfo philosofy, hiding the node managing.
36
37
Sgmltexi is to be intended as a simplified Texinfo using SGML; that
38
is: you cannot do all that it is possible with Texinfo alone. Sgmltexi
39
impose some restrictions, but maybe it can be simpler to write Texinfo
40
documentation this way.
41
42
* Menu:
43
44
* intro:: What is Sgmltexi
45
46
* chap 1:: General structure for a Sgmltexi source file
47
* chap 2:: Sectioning, nodes and menus
48
* chap 3:: Block and in-line
49
* chap 4:: Index and cross reference
50
* chap 5:: Marking words and phrases
51
* chap 6:: Marking block of text
52
* chap 7:: List and tables
53
* chap 8:: Insertions
54
* chap 9:: Definitions
55
* chap 10:: Conditional and literal back-end code
56
* chap 11:: How to use the front-end
57
* chap 12:: How to install
58
* chap 13:: Dependencies
59
* chap 14:: Encoding
60
* chap 15:: Supported and unsupported Texinfo feature
61
62
* ISOnum:: Supported ISOnum entities: numeric and special graphic
63
* ISOpub:: Supported ISOpub entities: publishing
64
* ISOtech:: Supported ISOtech entities: general technical
65
* ISOlat1:: Supported ISOlat1 entities: added latin 1
66
* ISOlat2:: Supported ISOlat2 entities: added latin 2
67
* GNU FDL:: GNU Free Documentation License
68
69
* ndx:: Index
70
71
72
File: sgmltexi.info, Node: intro, Next: chap 1, Prev: Top, Up: Top
73
74
Introduction to Sgmltexi
75
************************
76
77
Sgmltexi is a DTD with tools to get Texinfo. The idea is to have
78
another way to write Texinfo documents, intended to be a little bit
79
easier, but also with some limitations.
80
81
Sgmltexi manages Texinfo nodes automatically, generating a an Info
82
menu at the Top node, and other menus if required. The node names may be
83
generated automatically with string like "chap 1", "app A" and so on, or
84
can be inserted manually, with different names.
85
86
The Sgmltexi document has a precise scheme: there may be one or more
87
introductions, there is a body (made probably of chapters), there may be
88
appendixes and indexes. The body is organized into chapters, that may be
89
grouped into parts and also tomes. This way, also big documents are
90
easily managed.
91
92
Sgmltexi is a work derived form ALtools and Alml, from the same
93
author. These are the SGML typesetting systems made for the need of an
94
Italian documentation project:
95
Appunti di informatica libera (http://a2.swlibero.org/).
96
97
Obtain Sgmltexi
98
===============
99
100
At the moment, the main distribution source for Sgmltexi is the
101
following URI:
102
103
`http://a2.swlibero.org/~daniele/software/sgmltexi/'
104
105
What's new about Sgmltexi
106
=========================
107
108
The new Sgmltexi is simplified: the derivation system was removed,
109
and the Sgmltexi source files should be "expanded" to avoid the
110
horizontal tabs presence. The expansion is needed when reproducing
111
literal text, otherwise, strings like `\011' will appear, instead of
112
original tabs.
113
114
This modification will reduce the pre-elaboration time, and will
115
avoid also some possible troubles with SGML files included inside the
116
main source.
117
118
Please consider that this one might be the last release for
119
Sgmltexi, because the Texinfo development is taking different SGML/XML
120
paths.
121
122
123
124
File: sgmltexi.info, Node: chap 1, Next: chap 2, Prev: intro, Up: Top
125
126
General structure for a Sgmltexi source file
127
********************************************
128
129
The typical Sgmltexi source start like this:
130
131
<!DOCTYPE Sgmltexi PUBLIC "-//GNU//DTD Sgmltexi//EN">
132
133
It can be useful to define also some internal entities, like this:
134
135
<!DOCTYPE Sgmltexi PUBLIC "-//GNU//DTD Sgmltexi//EN"
136
[
137
<!ENTITY EDITION "2003.10.11" >
138
...
139
...
140
]>
141
142
All the document is enclosed inside the element `sgmltexi'. Inside,
143
there must be an `head' element, there may be an `intro' element, there
144
must be a `body' element, and there may be an `appendix' element. The
145
space after the `appendix' element may be occupied by some indexes
146
(will be shown later).
147
148
<sgmltexi>
149
<head>
150
...
151
</head>
152
<intro>
153
...
154
</intro>
155
<body>
156
...
157
</body>
158
<appendix>
159
...
160
</appendix>
161
</sgmltexi>
162
163
The element `sgmltexi' has three possible attribute: `lang',
164
`charset' and `spacing'.
165
166
- Attribute: lang
167
This is a two letter code defining the text language. The use of
168
this attribute generates a `@documentlanguage' command.
169
170
171
- Attribute: charset
172
This is the input character set, like it can be done with the
173
Texinfo `@documentencoding' command. It is obscured by the
174
`--input-encoding' option, that take precedence and generate a
175
pure ISO 646 Texinfo output.
176
177
178
- Attribute: spacing
179
This is a deprecated feature that help controlling the spacing
180
after sentences. It is deprecated because this action should be
181
controlled with the language specific configuration. This attribute
182
is here only as a last resort. Valid values are: `normal',
183
`french' and `uniform'. Selecting `french' or `uniform' it is
184
introduced the command `@frenchspacing'.
185
186
187
<sgmltexi lang="it" charset="ISO-8859-1" spacing="uniform">
188
189
* Menu:
190
191
* sect 1.1:: `head'
192
* sect 1.2:: `admin'
193
* sect 1.3:: `titlepage'
194
* sect 1.4:: Table of contents
195
* sect 1.5:: `menu'
196
* sect 1.6:: `intro'
197
* sect 1.7:: `body'
198
* sect 1.8:: `appendix'
199
* sect 1.9:: Indexes
200
201
202
File: sgmltexi.info, Node: sect 1.1, Next: sect 1.2, Up: chap 1
203
204
`head'
205
======
206
207
The `head' element is the more complicated. It is important to
208
define many informations about the document. Here it is the example
209
from this manual:
210
211
<head>
212
<admin>
213
<setfilename content="sgmltexi.info">
214
<settitle content="Sgmltexi">
215
<setchapternewpage content="odd">
216
<defindex name="sg">
217
<syncodeindex from="sg" to="cp">
218
<syncodeindex from="vr" to="cp">
219
<infodir cat="Texinfo documentation system">
220
</admin>
221
<titlepage>
222
<title>Sgmltexi</title>
223
<subtitle>An alternative way to write Texinfo
224
documentation</subtitle>
225
<subtitle>This edition is for Sgmltexi
226
&EDITION; for Texinfo 4</subtitle>
227
<abstract>
228
<p>Sgmltexi is an SGML system (DTD and tools) to
229
make Texinfo documentation using SGML...</p>
230
...
231
</abstract>
232
<author>Daniele Giacomini
233
<daniele@swlibero.org></author>
234
<legal>
235
<copyright>Copyright © 2000-2003 Daniele Giacomini
236
<daniele@swlibero.org></copyright>
237
<publishnote>
238
<p>Published by...</p>
239
</publishnote>
240
<license>
241
<p>Permission is granted to make and distribute
242
verbatim copies of this manual...</p>
243
...
244
</license>
245
<coverart>
246
<p>Cover art by ...</p>
247
</coverart>
248
</legal>
249
</titlepage>
250
<shortcontents>
251
<contents>
252
</head>
253
254
This is not all necessary, but it is a good starting point. Looking
255
at this example, can be recognized some important elements: `admin',
256
for administrative informations, and `titlepage'.
257
258
259
File: sgmltexi.info, Node: sect 1.2, Next: sect 1.3, Prev: sect 1.1, Up: chap 1
260
261
`admin'
262
=======
263
264
The `admin' element is used to enclose some empty elements that
265
describe informations that should go inside the Texinfo header. The
266
order for these elements is not important, as Texinfo source will be
267
build in the right one. It follows a summary table and then the detailed
268
description.
269
270
*Element* *Attribute* *Content* *Description or Texinfo equivalence*
271
setfilename empty `@setfilename'
272
content Info file name
273
settitle empty `@settitle'
274
content title
275
setchapternewpage empty `@setchapternewpage'
276
content on, off, odd tell how to separate chapters
277
footnotestyle empty `@footnotestyle'
278
content end, separate where to place footnotes
279
headings empty `@headings'
280
content on, off, how headings should work
281
single,
282
double,
283
singleafter,
284
doubleafter
285
defindex empty `@defindex'
286
name define a two letter index name
287
defcodeindex empty `@defcodeindex'
288
name define a two letter index name with
289
`@code' items
290
synindex empty `@synindex'
291
from source index, as a two letters name
292
to destination index, as a two letters
293
name
294
syncodeindex empty `@syncodeindex'
295
from source index, as a two letters name
296
to destination index, with `@code'
297
items
298
infodir empty or Info directory information
299
literal
300
`@direntry'
301
cat The `@dircategory' argument
302
303
- Element: setfilename
304
This element is empty and is used to define the file name for
305
Info, with the Texinfo command `@setfilename'.
306
307
- Attribute: content
308
This attribute is used to assign the file name.
309
310
311
Use this element like this, only with the opening tag:
312
313
<setfilename content="sgmltexi.info">
314
315
316
- Element: settitle
317
This element is empty and is used to define the title for Info,
318
with the Texinfo command `@settitle'.
319
320
- Attribute: content
321
This attribute is used to assign the title.
322
323
324
Use this element like this, only with the opening tag:
325
326
<settitle content="Sgmltexi">
327
328
329
- Element: setchapternewpage
330
This element is empty and is used to define the Texinfo command
331
`@setchapternewpage'.
332
333
- Attribute: content
334
This attribute is used to assign the desired value, that can
335
be: `on', `off' or `odd'.
336
337
338
Use this element like this, only with the opening tag:
339
340
<setchapternewpage content="on">
341
342
This element is not essential.
343
344
345
- Element: footnotestyle
346
This element is empty and is used to define the Texinfo command
347
`@footnotestyle'.
348
349
- Attribute: content
350
This attribute is used to assign the desired value, that can
351
be: `end' or `separate'.
352
353
354
Use this element like this, only with the opening tag:
355
356
<footnotestyle content="end">
357
358
This element is not essential.
359
360
361
- Element: heading
362
This element is empty and is used to define the Texinfo command
363
`@headings'.
364
365
- Attribute: content
366
This attribute is used to assign the desired value, that can
367
be: `on', `off', `single', `double', `singleafter',
368
`doubleafter'.
369
370
371
Use this element like this, only with the opening tag:
372
373
<headings content="double">
374
375
This element is not essential.
376
377
378
- Element: defindex
379
- Element: defcodeindex
380
These two empty elements are used to define the Texinfo commands
381
`@defindex' and `@defcodeindex'.
382
383
- Attribute: name
384
This attribute is used to define the name of the new user
385
index that is to be created. The name must be a two letter
386
word.
387
388
389
Use these elements like this, only with the opening tag:
390
391
<defindex name="sg">
392
393
<defcodeindex name="xx">
394
395
These elements are used only as needed, for as many user defined
396
index that are to be created.
397
398
399
- Element: synindex
400
- Element: syncodeindex
401
These two elements are used to copy one index into another, like
402
the command `@synindex' and `@syncodeindex' do with Texinfo.
403
404
- Attribute: from
405
- Attribute: to
406
The first attribute is used to define the index to copy; the
407
second is the index that receive the first one.
408
409
410
Use this element like this, only with the opening tag:
411
412
<syncodeindex from="fn" to="cp">
413
414
This element is used only as needed, for as many user defined
415
index that are to be created.
416
417
418
- Element: infodir
419
This element is used to define the Info directory menu item, when
420
the file is installed with `install-info'.
421
422
- Attribute: cat
423
This attribute defines the category, like the Texinfo command
424
`@dircategory' does.
425
426
427
This element can be used empty, like this:
428
429
<infodir cat="Texinfo documentation system">
430
431
But this element can be used also more explicitly, like this:
432
433
<infodir cat="Texinfo documentation system">
434
* Sgmltexi: (sgmltexi). SGML for Texinfo.
435
* Sgmltexi install: (sgmltexi)install. Install Sgmltexi.
436
</infodir>
437
438
This element is used only if needed. If the element is use empty,
439
only one line inside the `@direntry' environment is inserted, with
440
information already given.
441
442
443
444
File: sgmltexi.info, Node: sect 1.3, Next: sect 1.4, Prev: sect 1.2, Up: chap 1
445
446
`titlepage'
447
===========
448
449
The `titlepage' element is used to enclose all informations that go
450
on the first pages of the document. The order of elements is important.
451
It follows a summary table and then the detailed description.
452
453
*Element* *Attribute* *Content* *Description or Texinfo equivalence*
454
title IN-LINE `@title'
455
subtitle IN-LINE `@subtitle'
456
abstract BLOCK abstract of the document
457
author IN-LINE `@author'
458
frontcovertext BLOCK text shown on the printed front
459
cover
460
tpextra BLOCK extra text shown inside title pages
461
legal copyright, legal information
462
publishnote,
463
license,
464
coverart
465
legal BLOCK simplified legal information
466
copyright One copyright owner
467
publishnote BLOCK publishing note that should appear
468
before the license
469
license BLOCK license or reference to the
470
license, or other conditions
471
related to the document
472
coverart BLOCK coverart note that should appear
473
after the license
474
dedications BLOCK dedications for a book
475
476
- Element: title
477
This element contains the document title; the title for the
478
"printed" document. It is equivalent to `@title' for Texinfo. Use
479
this element like this:
480
481
<title>Sgmltexi</title>
482
483
484
- Element: subtitle
485
This element can be used to define one or more subtitles. It is
486
equivalent to `@subtitle' for Texinfo. Use this element like this,
487
after the title:
488
489
<subtitle>An alternative way to write Texinfo documentation</subtitle>
490
491
This element is used only as needed, without limitations.
492
493
494
- Element: abstract
495
This element can be used to define a brief description for the
496
document. The content must be block text, like the element `p'.
497
This text is used for Info typesetting, inside the Top node. Use
498
this element like this:
499
500
<abstract>
501
502
<p>Sgmltexi is an SGML system (DTD and tools) to
503
make Texinfo documentation using SGML.
504
The Sgmltexi DTD is designed to...</p>
505
506
<p>...</p>
507
508
</abstract>
509
510
This element can be used at most one time.
511
512
513
- Element: author
514
This element can be used to define one of the document authors.
515
This element is equivalent to the Texinfo command `@author'. Use
516
this element like this:
517
518
<author>Tizio Tizi <tizio@dinkel.brot.dg></author>
519
<author>Caio Cai <caio@dinkel.brot.dg></author>
520
521
This element must be used at least one time.
522
523
524
- Element: frontcovertext
525
This element can be used to include one or more block of text,
526
that should appear on the front cover, for the printed edition.
527
Use this element like this:
528
529
<frontcovertext>
530
531
<p>Version 1.2.3</p>
532
533
<p><image name="good-thing" height="5cm"></p>
534
535
</frontcovertext>
536
537
538
- Element: tpextra
539
This element can be used to include one or more block of text,
540
that should appear on different places: before the legal
541
informations; after legal information; after the dedications. The
542
name `tpextra' stand for "title page extra" text. Use this element
543
like this:
544
545
<tpextra>
546
547
<p><strong>Pinco Pallino</strong> is a very old man...</p>
548
549
<p><strong>Tizio Tizi</strong> studied telecommunication
550
technology...</p>
551
552
</tpextra>
553
<legal>
554
...
555
...
556
</legal>
557
<tpextra>
558
559
<p>The front cover picture is made by Sempronio.</p>
560
561
</tpextra>
562
<dedications>
563
...
564
...
565
</dedications>
566
<tpextra>
567
568
<p>The software is very important; true free software is much more
569
important.</p>
570
571
</tpextra>
572
573
The use of this element is optional, but notice that the last one
574
can be used only if there is the dedications element before.
575
576
577
- Element: legal
578
This element is used to enclose other elements describing
579
informations about copyright, license and publication.
580
581
- Element: copyright
582
This element contains a line of text describing the copyright
583
owner for the document.
584
585
586
- Element: publishnote
587
This optional element, contains block of text that show
588
information about the printed publication.
589
590
591
- Element: license
592
This element contains block of text to show the license
593
conditions for the document.
594
595
596
- Element: coverart
597
This optional element, contains block of text that show who
598
is responsible for the cover design.
599
600
601
Use this element like this:
602
603
<legal>
604
<copyright>Copyright © 2003 Free Software Foundation,
605
Inc.</copyright>
606
<publishnote>
607
<p>Published by...</p>
608
</publishnote>
609
<license>
610
<p>Permission is granted to copy, distribute and/or
611
modify this document under the terms of the GNU Free
612
Documentation License, Version 1.1 or any later version
613
published by the Free Software Foundation; with no
614
Invariant Sections, with no Front-Cover Texts, and with
615
no Back-Cover Texts. A copy of the license is included
616
in the section entitled "GNU Free Documentation
617
License".</p>
618
</license>
619
<coverart>
620
<p>Cover art by ...</p>
621
</coverart>
622
</legal>
623
624
This element must be used at least one time.
625
626
Actually, this element can have non special internal structure,
627
enclosing simply other block elements. This way, if the standard
628
structure described above is not good for the author intention, it
629
may be used also like this:
630
631
<legal>
632
<p>Copyright © 2003 Free Software Foundation, Inc.</p>
633
634
<p>Published by...</p>
635
636
<p>Permission is granted to copy, distribute and/or modify this
637
document under the terms of the GNU Free Documentation License,
638
Version 1.1 or any later version published by the Free Software
639
Foundation; with no Invariant Sections, with no Front-Cover Texts,
640
and with no Back-Cover Texts. A copy of the license is included in
641
the section entitled "GNU Free Documentation License".</p>
642
643
<p>Cover art by ...</p>
644
</legal>
645
646
647
- Element: dedications
648
This optional element, contains block of text that show one or
649
more dedications.
650
651
652
653
File: sgmltexi.info, Node: sect 1.4, Next: sect 1.5, Prev: sect 1.3, Up: chap 1
654
655
Table of contents
656
=================
657
658
After the `titlepage', there is the place for one or more table of
659
contents. To obtain the insertion of these table of contents can be
660
used one of the following empty element.
661
662
- Element: contents
663
The standard table of contents, like the command `@contents' for
664
Texinfo.
665
666
667
- Element: shortcontents
668
- Element: summarycontents
669
A reduced table of contents, like the command `@shortcontents' and
670
`@summarycontents' for Texinfo.
671
672
673
674
File: sgmltexi.info, Node: sect 1.5, Next: sect 1.6, Prev: sect 1.4, Up: chap 1
675
676
`menu'
677
======
678
679
After the contents elements, may appear the `menu' element. This
680
element ask explicitly for the correspondent Texinfo `@menu' command.
681
At this level, the menu is inserted automatically, also without
682
inserting this element. But the `menu' element may be used to define a
683
specific (manual) menu for texinfo. See the following example:
684
685
<menu>
686
* introduction :: Introduction
687
* structure:: General structure for a Sgmltexi source file
688
* how to use:: How to use the front-end
689
* install:: How to install
690
* GFDL:: GNU Free Documentation License
691
* index:: Index
692
</menu>
693
694
The `menu' may be used also at chapter level and below, and there
695
can be also empty: in this case, an automatic Texinfo menu will be
696
inserted.
697
698
699
File: sgmltexi.info, Node: sect 1.6, Next: sect 1.7, Prev: sect 1.5, Up: chap 1
700
701
`intro'
702
=======
703
704
After the `head' element there may be one `intro' element. This is
705
just a way to define a group of chapter that have no numbering.
706
Chapters inside this element are delimited in the same way as for the
707
`body' and `appendix' elements.
708
709
<intro>
710
<h1>Introduction to Sgmltexi</h1>
711
712
<p>Sgmltexi is a DTD with tools to get Texinfo...</p>
713
714
<p>Sgmltexi manage Texinfo nodes automatically,...</p>
715
716
</intro>
717
718
719
File: sgmltexi.info, Node: sect 1.7, Next: sect 1.8, Prev: sect 1.6, Up: chap 1
720
721
`body'
722
======
723
724
After the `head' and `intro' elements, there must be one `body'
725
element. This is the body of the document.
726
727
The body may be divided into chapters, or parts, or tomes, depending
728
on the documentation project that is started. Tomes are delimited with
729
the element `tomeheading', that contains the tome title; parts are
730
delimited using the element `partheading', with the same meaning.
731
732
Chapters and lower sectioning are a little anonymous, like HTML:
733
`h1', `h2', `h3' and `h4'. This is done that way because introduction,
734
body and appendix may have the same method for text sectioning.
735
736
<body>
737
<partheader>Networking</partheader>
738
739
<h1>IP protocol history</h1>
740
741
<p>Bla bla bla...</p>
742
743
<p>Bla bla bla...</p>
744
745
<h2>ISO/OSI model</h2>
746
747
<p>Bla bla bla...</p>
748
749
<p>Bla bla bla...</p>
750
751
<h1>IPv4 and IPv6</h1>
752
753
<p>Bla bla bla...</p>
754
755
<p>...</p>
756
757
</body>
758
759
Every sectioning element, from tome to last sub-subsection, have an
760
optional attribute: `id'. This attribute may be used to define an
761
identification string that can be the target for cross references.
762
763
<h1 id="ip history">IP protocol history</h1>
764
765
Note that due to Texinfo design limitations, cross references labels
766
cannot contain the comma.
767
768
769
770
File: sgmltexi.info, Node: sect 1.8, Next: sect 1.9, Prev: sect 1.7, Up: chap 1
771
772
`appendix'
773
==========
774
775
After the body, it may be placed the `appendix'. This one is used to
776
delimit a group of chapters that must be intended as appendixes. This
777
way, also the appendix is organized in chapter delimited with `h1'
778
heading, and smaller sections.
779
780
781
File: sgmltexi.info, Node: sect 1.9, Prev: sect 1.8, Up: chap 1
782
783
Indexes
784
=======
785
786
After the body and after the optional appendix, can be placed one or
787
more analytic index. This is obtained with a special heading element:
788
`indexheading'. This can be used only in conjunction with `printindex'
789
to define the type of index to include. The example should be clear
790
enough:
791
792
...
793
<indexheading>Index of functions</indexheading>
794
<printindex name="fn">
795
<indexheading>Concept index</indexheading>
796
<printindex name="cp">
797
...
798
</sgmltexi>
799
800
As can be seen from the example, `printindex' has an attribute,
801
`name', that tells the type of index to include. In fact, this way is
802
generated the Texinfo command `@printindex'.
803
804
805
File: sgmltexi.info, Node: chap 2, Next: chap 3, Prev: chap 1, Up: Top
806
807
Sectioning, nodes and menus
808
***************************
809
810
To write good documentation with Texinfo, it is required to have
811
control on nodes and menus. With Sgmltexi, nodes and menus can be
812
forgotten, but the Info result may suffer for this choice. Anyway, with
813
Sgmltexi it is possible to choose different levels of manual/automatic
814
node handling.
815
816
Headings elements can incorporate some more attributes: `node' and
817
`menu'. The first one define the node name, overriding any automatic
818
determination; the second define the node description on the menu (the
819
automatical choice is otherwise the title).
820
821
<h1 id="ip history" node="history" menu="History of IP protocol">
822
IP protocol history</h1>
823
824
This will generate on the Info menu, the following line:
825
826
* history:: History of IP protocol
827
828
The `node' and `menu' attribute may be used independently: the
829
attribute that is not used, will be determined automatically.
830
831
Having access to nodes, it is possible to use them for cross
832
reference, without the need for the `id' attribute.
833
834
Sgmltexi creates automatically the Top node menu. As already
835
explained before (*note top node menu::), the menu can be explicitly
836
defined. In this way, all nodes and descriptions must be made manually.
837
838
Inserting the `menu' element at the bottom of a chapter, or at a
839
lower section, will ask an insertion of a lower Info menu. See the
840
example:
841
842
<h1>IP protocol history</h1>
843
844
<p>Bla bla bla...</p>
845
846
<p>Bla bla bla...</p>
847
848
<menu>
849
850
<h2>ISO/OSI model</h2>
851
852
<p>Bla bla bla...</p>
853
854
<p>Bla bla bla...</p>
855
856
<h2>More information</h2>
857
858
<p>Bla bla bla...</p>
859
860
<p>...</p>
861
862
The example shows the insertion of an automatic Info menu before
863
`h2' sections. This menu may otherwise be described completely, like
864
this:
865
866
<menu>
867
* IP layer:: IP ISO/OSI layer model
868
* more on IP:: More details on IP
869
</menu>
870
871
When the menu is described this way, node names must be the same as
872
the one used with the heading elements. That is: when writing the menu,
873
also nodes must be exactly declared, like this:
874
875
<h1>IP protocol history</h1>
876
877
<p>Bla bla bla...</p>
878
879
<p>Bla bla bla...</p>
880
881
<menu>
882
* IP layer:: IP ISO/OSI layer model
883
* more on IP:: More details on IP
884
</menu>
885
886
<h2 node="IP layer">ISO/OSI model</h2>
887
888
<p>Bla bla bla...</p>
889
890
<p>Bla bla bla...</p>
891
892
<h2 node="more on IP">More information</h2>
893
894
<p>Bla bla bla...</p>
895
896
<p>...</p>
897
898
It is evident that a `menu' attribute (like `<h2 menu="Much more
899
information">') has no effect in this case.
900
901
*Element* *Attribute* *Content* *Description or Texinfo equivalence*
902
tomeheading IN-LINE title of a tome
903
partheading title of a part
904
h1 IN-LINE title of a chapter, introduction or
905
appendix
906
h2 IN-LINE title of a section
907
h3 IN-LINE title of a subsection
908
h4 IN-LINE title of a sub-subsection
909
indexheading IN-LINE title of an analytic index
910
node Info node name
911
menu Info node description
912
next Next node name
913
prev Previous node name
914
up Up node name
915
type numbered, type of section, for `h1' to `h4'
916
unnumbered, elements
917
heading
918
919
Unnumbered sections and simple headings
920
=======================================
921
922
Elements `h1', `h2', `h3' and `h4' may have an additional attribute:
923
`type'. The keywords `numbered', `unnumbered' and `heading' may be
924
assigned. `numbered' is the default value; it means that the title will
925
be numbered (with numbers if inside `body', with letters if inside
926
`appendix'). Assigning `unnumbered', the titles are not numbered.
927
Assigning `heading', the titles are not numbered and not annotated
928
inside the table of context.
929
930
<h1 type="unnumbered">Acknowledgements</h1>
931
...
932
933
Inside the `intro' elements, titles cannot be numbered: it is
934
explicitly excluded.
935
936
937
File: sgmltexi.info, Node: chap 3, Next: chap 4, Prev: chap 2, Up: Top
938
939
Block and in-line
940
*****************
941
942
Sgmltexi has a DTD where most of the elements are divided into two
943
categories, block and in-line, with the help of two parameter entities:
944
`block' and `inline' (SGML macro are `%block;' and `%inline;').
945
946
A block is something like a paragraph, a list, a table; an in-line
947
is text, text emphatisation, anchors, cross references, and other
948
things that stay inside a text.
949
950
Usually, but not necessarily, an in-line element contains text and
951
possibly other in-line elements; but a block element may be made to
952
contain in-line or other blocks. The Sgmltexi DTD don't consider the
953
possibility of block elements that may contain either block or in-line.
954
These kinds of contents are known as "flow" (this name is used inside
955
the HTML DTD) and are rarely useful.
956
957
Some block elements, like `example', may contain block elements or a
958
single `pre' element (a special block element not classified as part of
959
the `%block;' macro). The `pre' element can contain only in-line that
960
is preformatted, that is: it maintains line breaks.
961
962
The two basic block element are shown in the following table:
963
964
*Element* *Attribute* *Content* *Description or Texinfo equivalence*
965
p IN-LINE paragraph, or simple block of text
966
indent `on', `off' first line indentation; default is
967
`on'
968
center IN-LINE `@center'
969
970
971
File: sgmltexi.info, Node: chap 4, Next: chap 5, Prev: chap 3, Up: Top
972
973
Index and cross reference
974
*************************
975
976
There are different kind of insertions for making indexes and cross
977
references, that reproduce equivalent Texinfo commands.
978
979
Indexes
980
=======
981
982
Index entries are inserted with a group of empty elements: `cindex',
983
`findex', `vindex', `kindex', `pindex', `tindex' and `userindex'. All
984
these elements have the same attribute, `entry', that define the item
985
text to be inserted. The `userindex' has an additional attribute, to
986
define the user index name (that should be made of two letters).
987
988
These elements are a kind of block that may be inserted just after
989
any sectioning title, like this:
990
991
<h1>IP protocol history</h1>
992
<cindex entry="IP protocol">
993
<cindex entry="history">
994
995
<p>Bla bla bla...</p>
996
997
The following table resumes the meaning for so many different index
998
entry elements.
999
1000
*Element* *Attribute* *Content* *Description or Texinfo equivalence*
1001
cindex entry empty concept index item
1002
findex entry empty function index item
1003
vindex entry empty variable index item
1004
kindex entry empty keystroke index item
1005
pindex entry empty program index item
1006
tindex entry empty data type index item
1007
userindex entry empty user defined index item
1008
name user defined index name (two
1009
letters)
1010
printindex name print the named index (two letters)
1011
1012
The index is inserted with the element `printindex', already
1013
described. Standard index names are listed in the following table.
1014
1015
*Index name* *Description*
1016
cp concept index.
1017
ky keystroke index.
1018
pg program index.
1019
fn function index.
1020
vr variable index.
1021
tp data type index.
1022
1023
Cross references
1024
================
1025
1026
Cross reference elements are all in-line empty elements. All
1027
information is given via attributes. As all cross reference elements are
1028
implementations of equivalent Texinfo commands, there is only the
1029
following table as description. Every attribute description follow its
1030
own element. Please note that not all attributes are necessary.
1031
1032
*Element* *Attribute* *Content* *Description or Texinfo equivalence*
1033
anchor empty `@anchor'
1034
id anchor identity string
1035
xref empty `@xref'
1036
id node or anchor name
1037
name cross reference name
1038
title title or topic
1039
info info file name
1040
ptitle printed manual title
1041
ref empty `@ref'
1042
id node or anchor name
1043
name cross reference name
1044
title title or topic
1045
info info file name
1046
ptitle printed manual title
1047
pxref empty `@pxref'
1048
id node or anchor name
1049
name cross reference name
1050
title title or topic
1051
info info file name
1052
ptitle printed manual title
1053
inforef empty `@inforef'
1054
id node or anchor name
1055
name cross reference name
1056
info info file name
1057
uref empty `@uref'
1058
uri URI address
1059
name title or description
1060
replace replacement text
1061
email empty `@email'
1062
email electronic mail address
1063
name title or description
1064
1065
Use like this:
1066
1067
<p>Sgmltexi creates automatically the Top node menu. As already
1068
explained before (<pxref id="top node menu">), the menu can be
1069
...
1070
1071
1072
File: sgmltexi.info, Node: chap 5, Next: chap 6, Prev: chap 4, Up: Top
1073
1074
Marking words and phrases
1075
*************************
1076
1077
A lot of in-line elements are used to mark words or phrases.
1078
Actually, the DTD is very permissive, so that every element of these can
1079
contain any in-line element. It is so only to assure compatibility with
1080
Texinfo, but may change in the future. The following table list these
1081
elements, included `kbdinputstyle', used to select the style for the
1082
`kbd' element.
1083
1084
*Element* *Attribute* *Content* *Description or Texinfo equivalence*
1085
code IN-LINE `@code'
1086
kbd IN-LINE `@kbd'
1087
kbdinputstyle empty `@kbdinputstyle'
1088
style `code', how to show keyboard input style;
1089
`example', default is `distinct'
1090
`distinct'
1091
key IN-LINE `@key'
1092
samp IN-LINE `@samp'
1093
var IN-LINE `@var'
1094
env IN-LINE `@env'
1095
file IN-LINE `@file'
1096
command IN-LINE `@command'
1097
option IN-LINE `@option'
1098
dfn IN-LINE `@dfn'
1099
cite IN-LINE `@cite'
1100
acronym IN-LINE `@acronym'
1101
url IN-LINE `@url'
1102
emph IN-LINE `@emph'
1103
strong IN-LINE `@strong'
1104
sc IN-LINE `@sc'
1105
roman IN-LINE `@r'
1106
italic IN-LINE `@i'
1107
bold IN-LINE `@b'
1108
typewriter IN-LINE `@t'
1109
1110
Use like this:
1111
1112
<p><strong>Pinco Pallino</strong> is a very old man...</p>
1113
1114
<p><strong>Tizio Tizi</strong> studied telecommunication
1115
technology...</p>
1116
1117
1118
File: sgmltexi.info, Node: chap 6, Next: chap 7, Prev: chap 5, Up: Top
1119
1120
Marking block of text
1121
*********************
1122
1123
Some block elements are used to mark other block of text or special
1124
kind of in-line text. The DTD is very permissive, to assure maximum
1125
compatibility with Texinfo, but this may change in the future. The
1126
following table list these elements, included the special element
1127
`pre', used to insert in-line preformatted text, and `exdent', used
1128
inside `pre' to obtain an exdented line.
1129
1130
*Element* *Attribute* *Content* *Description or Texinfo equivalence*
1131
exdent IN-LINE `@exdent'
1132
pre IN-LINE preformatted text
1133
quotation BLOCK `@quotation'
1134
display BLOCK or `pre' `@display'
1135
smalldisplay BLOCK or `pre' `@smalldisplay'
1136
example BLOCK or `pre' `@example'
1137
smallexample BLOCK or `pre' `@smallexample'
1138
flushleft IN-LINE `@flushleft'
1139
flushright IN-LINE `@flushright'
1140
lisp BLOCK or `pre' `@lisp'
1141
smalllisp BLOCK or `pre' `@smalllisp'
1142
cartouche BLOCK or `pre' `@cartouche'
1143
format BLOCK or `pre' `@format'
1144
smallformat BLOCK or `pre' `@smallformat'
1145
texinfo literal embedded literal Texinfo code
1146
Texinfo
1147
1148
Use like this:
1149
1150
<example>
1151
<p>Hello everybody</p>
1152
<p>Hello to the world</p>
1153
</example>
1154
1155
In this case the `example' element contains preformatted text
1156
(please not the use of two SGML entities, `lt' and `gt'):
1157
1158
<example>
1159
<pre>
1160
#!/usr/bin/perl
1161
while ($line = <STDIN>)
1162
{
1163
chomp $line;
1164
print ("$line\r\n");
1165
}
1166
</pre>
1167
</example>
1168
1169
If it is necessary to include a preformatted literal text, do like
1170
this (please note that there is no need to hide `<' and `>'):
1171
1172
<example>
1173
<pre>
1174
<![CDATA[
1175
#!/usr/bin/perl
1176
while ($line = <STDIN>)
1177
{
1178
chomp $line;
1179
print ("$line\r\n");
1180
}
1181
]]>
1182
</pre>
1183
</example>
1184
1185
1186
File: sgmltexi.info, Node: chap 7, Next: chap 8, Prev: chap 6, Up: Top
1187
1188
List and tables
1189
***************
1190
1191
List and tables are block elements. The following table list the
1192
elements used to implement list and tables.
1193
1194
*Element* *Attribute* *Content* *Description or Texinfo equivalence*
1195
itemize `item', `@itemize'
1196
`itemx', BLOCK
1197
mark mark before items; default is
1198
`•'
1199
enumerate `item', `@enumerate'
1200
`itemx', BLOCK
1201
start starting number
1202
table `item', `@table'
1203
`itemx', BLOCK
1204
emphasis `asis', emphasis for the descriptive item
1205
`code',
1206
`samp',
1207
`var', `kbd',
1208
`file'
1209
vtable `item', `@vtable'
1210
`itemx', BLOCK
1211
emphasis `asis', emphasis for the descriptive
1212
`code', variable item
1213
`samp',
1214
`var', `kbd'
1215
ftable `item', `@ftable'
1216
`itemx', BLOCK
1217
emphasis `asis', emphasis for the descriptive
1218
`code', function item
1219
`samp',
1220
`var', `kbd'
1221
item IN-LINE or `@item'
1222
empty
1223
itemx IN-LINE or `@itemx'
1224
empty
1225
multitable `columnfraction'`@multitable'
1226
or
1227
`columnexample';
1228
`raw'
1229
columnfraction .N column fraction, where ".N" is the
1230
0.N fraction of the horizontal space
1231
columnexample pure text column fraction, where the inserted
1232
text gives the example of the
1233
column extention
1234
raw IN-LINE, `tab' row of the table
1235
tab empty column separation
1236
1237
It follows some examples; first an unnumbered list:
1238
1239
<itemize mark="#">
1240
<item>
1241
1242
<p>First item.</p>
1243
1244
<item>
1245
1246
<p>Second item.</p>
1247
1248
</itemize>
1249
1250
Here is the result:
1251
1252
# First item.
1253
1254
# Second item.
1255
1256
1257
Here is a numbered list:
1258
1259
<enumerate start="3">
1260
<item>
1261
1262
<p>First item.</p>
1263
1264
<item>
1265
1266
<p>Second item.</p>
1267
1268
</enumerate>
1269
1270
Here is the result:
1271
1272
3. First item.
1273
1274
4. Second item.
1275
1276
1277
Here is a descriptive list:
1278
1279
<table emphasis="code">
1280
<item>ls</item>
1281
<itemx>dir</itemx>
1282
<p>List directory contents.</p>
1283
<item>cd</item>
1284
<p>Change directory.</p>
1285
</table>
1286
1287
Here is the result:
1288
1289
`ls'
1290
`dir'
1291
List directory contents.
1292
1293
`cd'
1294
Change directory.
1295
1296
1297
File: sgmltexi.info, Node: chap 8, Next: chap 9, Prev: chap 7, Up: Top
1298
1299
Insertions
1300
**********
1301
1302
Here are described some mixed elements that have not found a better
1303
place. There are two types of such insertions: in-line and block
1304
insertions. The first of the following tables list the in-line elements
1305
and the second the block elements.
1306
1307
*Element* *Attribute* *Content* *Description or Texinfo equivalence*
1308
dmn parsed `@dmn'
1309
character data
1310
math parsed `@math'
1311
character data
1312
footnote IN-LINE `@footnote'
1313
image empty `@image'
1314
name file name to be inserted (without
1315
extention)
1316
width image width
1317
height image height
1318
whole IN-LINE `@w' (preventing line break)
1319
br empty `@*' (line break)
1320
dh empty `@-' (discretionary hyphen)
1321
hyphenation empty `@hyphenation'
1322
words list of hy-phen-a-ted words
1323
1324
*Element* *Attribute* *Content* *Description or Texinfo equivalence*
1325
sp empty `@sp'
1326
lines skip N lines
1327
page empty `@page'
1328
group BLOCK `@group'
1329
need empty `@need'
1330
mils thousandths of inch
1331
Loggerhead is a web-based interface for Breezy
Version: 2.0.1