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
|
.Dd October 7, 1995
.Os FreeBSD 2.1
.Dt SGMLFMT 1
.Sh NAME
.Nm sgmlfmt
.Nd Formats SGML files tagged according to the linuxdoc DTD.
.Sh SYNOPSIS
.Nm
.Fl f Ar format
.Op Fl links
.Op Fl ssi
.Op Fl i Ar name ...
.Ar file
.Sh DESCRIPTION
The
.Nm
command reads SGML files tagged according to the linuxdoc DTD,
validates them using the
.Xr sgmls 1
parser and then converts them to the specified output format.
The input file must include the following document type
declaration before any uncommented text:
.Bd -literal -offset indent
<!DOCTYPE linuxdoc PUBLIC "-//FreeBSD//DTD linuxdoc//EN">
.Ed
.Pp Options for
.Nm
include the following:
.Bl -tag -width Ds
.It Fl f Ar format
Determines the output format which can be one of the following:
.Bl -tag -width Ds
.It Ar html
Generates a set of linked HTML files suitable for use with an
HTML browser. A top level file,
.Pa file.html ,
contains the title, author, date, abstract and brief table of
contents for the document. A file
.Pa file_toc.html
contains a complete table of contents. A series of files named
.Pa file1.html ,
.Pa file2.html ...
.Pa filen.html
contain the actual text of the document.
.It Ar latex
Generates a single output file with the extension
.Pa .tex
suitable for processing with LaTeX. Note that the LaTeX style
file
.Pa /usr/share/sgml/FreeBSD/lib/linuxdoc.sty
must be accessible to LaTeX for correct processing.
.It Ar ascii
Generates a single output file with the extension
.Pa .ascii
suitable for viewing on an ASCII terminal.
.It Ar nroff
Generates a single output file with the extension
.Pa .nroff
suitable processing with
.Xr nroff 1
or
.Xr groff 1 .
This is actually an intermediate conversion used by the
.Fl f Ar ascii
format option.
.El
.It Fl i Ar name
Pretend that
.Dl <!ENTITY % name "INCLUDE">
occurs at the start of the document type declaration subset in
the document entity. Since repeated definitions of an entity are
ignored, this definition will take precedence over any other
definitions of this entity in the document type declaration.
Multiple
.Fl i
options are allowed. If the declaration replaces the reserved
name INCLUDE then the new reserved name will be the replacement
text of the entity. Typically the document type declaration will
contain
.Dl <!ENTITY % name "IGNORE">
and will use
.Li %name;
in the status keyword specification of a
marked section declaration. In this case the effect of the
option will be to cause the marked section not to be ignored.
.It Fl links
When used with the
.Fl f Ar html
option, for each
.Li <label id="foo">
in the document source
.Nm
generates a symbolic link
.Pa foo.html
pointing to the numbered
.Pa .html
file containing the reference. Since the number of the file
containing a particular section can change when a document
is modified, this provides a convenient hook by which separate
documents can provide links into another document without the
links becoming invalid when the target document is modified.
When creating a symbolic link, any occurrence of a slash (/) in label
is replaced with percent (%), while any occurrence of a space is replaced
with an underscore (_).
.It Fl ssi
When used with the
.Fl f Ar html
option, hooks will be placed to have an http server include a
custom header and footer on the document using the server side
include mechanism. This mechanism is supported by the Apache and
NCSA http servers and possibly others. Included files are named
.Pa file.hdr
and
.Pa file.ftr
for the header and footer of the
.Pa file.html .
Other pages include file are named
.Pa file.ftr1 ,
.Pa file.ftr2 ...
.Pa file.ftrn
where the number corresponds to the depth of the file from
.Pa file.html .
.El
.Pp
If the input file name ends with
.Pa .sgml ,
the extension may be omitted on the command line.
In all cases, the output files are created in the current working
directory.
.Sh FILES
.Pa /usr/share/sgml/FreeBSD/dtd/linuxdoc
- the linuxdoc DTD.
.Pp
.Pa /usr/share/sgml/FreeBSD/rep/
- directory containing replacement files for
.Xr sgmlsasp 1 .
.Pp
.Pa /usr/share/sgml/FreeBSD/lib/linuxdoc.sty
- the LaTeX style used in documents produced with the
.Fl latex
format option.
.Sh SEE ALSO
.Xr sgmls 1 ,
.Xr sgmlsasp 1 ,
.Xr groff 1
.Sh HISTORY
The
.Nm
command appeared in Version 2.0.5 FreeBSD UNIX.
.Sh AUTHORS
The
.Nm
command was written by John Fieber
.Aq jfieber@FreeBSD.org .
The linuxdoc DTD was written by Matt Welsh
.Aq mdw@cs.cornell.edu
and based on the Qwertz DTD written by Tom Gordon
.Aq thomas.gordon@gmd.de .
.Sh BUGS
The ASCII output has many, many bugs including no meaningful
cross references, and numerous formatting problems.
.Pp
A line in the SGML source file beginning with a period (.) will
confuse
.Xr groff 1
which is used to generate ASCII output.
.Pp
The division of the sources file into separate HTML files is
currently fixed.
.Pp
Although legal according to the DTD, it the ascii formatting gets botched if
the
.Li <heading>
.No ...
.Li </heading>
tags are omitted following a
sectioning tag such as
.Li <sect> .
.Pp
Beginning and ending tags for the
.Li <tag>
element must occur on the same line for correct formatting with
the
.Fl ascii
option.
|
