Package: docbook-to-man
Version: 1:2.0.0-50
Severity: minor
Tags: patch
Dear Maintainer,
>From "/usr/share/doc/debian/bug-reporting.txt.gz":
Don't file bugs upstream
If you file a bug in Debian, don't send a copy to the upstream software
maintainers yourself, as it is possible that the bug exists only in
Debian. If necessary, the maintainer of the package will forward the
bug upstream.
-.-
I do not send reports upstream if I have to get an account there.
The Debian maintainers have one already.
If I get a negative (or no) response from upstream, I send henceforth
bugs to Debian.
-.-
* What led up to the situation?
Checking for defects with a new version
test-[g|n]roff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=0 -ww -z < "man page"
[Use
grep -n -e ' $' -e '\\~$' -e ' \\f.$' -e ' \\"' <file>
to find (most) trailing spaces.]
["test-groff" is a script in the repository for "groff"; is not shipped]
(local copy and "troff" slightly changed by me).
[The fate of "test-nroff" was decided in groff bug #55941.]
* What was the outcome of this action?
Output from "test-nroff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=0 -ww -z ":
troff:<stdin>:54: warning: trailing space in the line
troff:<stdin>:57: warning: trailing space in the line
troff:<stdin>:58: warning: trailing space in the line
troff:<stdin>:59: warning: trailing space in the line
troff:<stdin>:60: warning: trailing space in the line
troff:<stdin>:62: warning: trailing space in the line
troff:<stdin>:63: warning: trailing space in the line
troff:<stdin>:64: warning: trailing space in the line
troff:<stdin>:65: warning: trailing space in the line
troff:<stdin>:66: warning: trailing space in the line
troff:<stdin>:70: warning: trailing space in the line
troff:<stdin>:71: warning: trailing space in the line
troff:<stdin>:74: warning: trailing space in the line
troff:<stdin>:75: warning: trailing space in the line
troff:<stdin>:77: warning: trailing space in the line
<stdin>:85: warning: table wider than line length minus indentation
an.tmac:<stdin>:95: warning: .l = 1920u = 80n = 80m, .i = 120u, TW (table
width) = 2064u = 86n = 86m
troff:<stdin>:98: warning: trailing space in the line
troff:<stdin>:101: warning: trailing space in the line
troff:<stdin>:102: warning: trailing space in the line
troff:<stdin>:103: warning: trailing space in the line
troff:<stdin>:104: warning: trailing space in the line
troff:<stdin>:109: warning: trailing space in the line
troff:<stdin>:110: warning: trailing space in the line
troff:<stdin>:113: warning: trailing space in the line
troff:<stdin>:114: warning: trailing space in the line
troff:<stdin>:115: warning: trailing space in the line
troff:<stdin>:121: warning: trailing space in the line
troff:<stdin>:122: warning: trailing space in the line
troff:<stdin>:123: warning: trailing space in the line
troff:<stdin>:135: warning: trailing space in the line
troff:<stdin>:140: warning: trailing space in the line
<stdin>:146: warning: table wider than line length minus indentation
an.tmac:<stdin>:157: warning: .l = 1920u = 80n = 80m, .i = 120u, TW (table
width) = 1824u = 76n = 76m
troff:<stdin>:160: warning: trailing space in the line
troff:<stdin>:164: warning: trailing space in the line
troff:<stdin>:165: warning: trailing space in the line
troff:<stdin>:166: warning: trailing space in the line
troff:<stdin>:167: warning: trailing space in the line
troff:<stdin>:170: warning: trailing space in the line
troff:<stdin>:171: warning: trailing space in the line
troff:<stdin>:172: warning: trailing space in the line
troff:<stdin>:175: warning: trailing space in the line
troff:<stdin>:176: warning: trailing space in the line
troff:<stdin>:177: warning: trailing space in the line
troff:<stdin>:178: warning: trailing space in the line
troff:<stdin>:180: warning: trailing space in the line
troff:<stdin>:181: warning: trailing space in the line
troff:<stdin>:184: warning: trailing space in the line
troff:<stdin>:187: warning: trailing space in the line
troff:<stdin>:188: warning: trailing space in the line
troff:<stdin>:191: warning: trailing space in the line
troff:<stdin>:192: warning: trailing space in the line
troff:<stdin>:193: warning: trailing space in the line
troff:<stdin>:194: warning: trailing space in the line
troff:<stdin>:197: warning: trailing space in the line
troff:<stdin>:204: warning: trailing space in the line
troff:<stdin>:208: warning: trailing space in the line
troff:<stdin>:213: warning: trailing space in the line
troff:<stdin>:214: warning: trailing space in the line
troff:<stdin>:217: warning: trailing space in the line
troff:<stdin>:227: warning: trailing space in the line
troff:<stdin>:230: warning: trailing space in the line
troff:<stdin>:236: warning: trailing space in the line
troff:<stdin>:237: warning: trailing space in the line
troff:<stdin>:240: warning: trailing space in the line
troff:<stdin>:241: warning: trailing space in the line
troff:<stdin>:242: warning: trailing space in the line
troff:<stdin>:243: warning: trailing space in the line
troff:<stdin>:249: warning: trailing space in the line
troff:<stdin>:250: warning: trailing space in the line
troff:<stdin>:251: warning: trailing space in the line
troff:<stdin>:252: warning: trailing space in the line
troff:<stdin>:253: warning: trailing space in the line
troff:<stdin>:255: warning: trailing space in the line
troff:<stdin>:261: warning: trailing space in the line
troff:<stdin>:262: warning: trailing space in the line
troff:<stdin>:263: warning: trailing space in the line
troff:<stdin>:264: warning: trailing space in the line
troff:<stdin>:267: warning: trailing space in the line
troff:<stdin>:271: warning: trailing space in the line
troff:<stdin>:285: warning: trailing space in the line
troff:<stdin>:286: warning: trailing space in the line
troff:<stdin>:287: warning: trailing space in the line
troff:<stdin>:288: warning: trailing space in the line
<stdin>:303: warning: table wider than line length minus indentation
an.tmac:<stdin>:331: warning: .l = 1920u = 80n = 80m, .i = 120u, TW (table
width) = 1920u = 80n = 80m
troff:<stdin>:334: warning: trailing space in the line
troff:<stdin>:337: warning: trailing space in the line
troff:<stdin>:338: warning: trailing space in the line
troff:<stdin>:342: warning: trailing space in the line
troff:<stdin>:344: warning: trailing space in the line
troff:<stdin>:345: warning: trailing space in the line
troff:<stdin>:346: warning: trailing space in the line
troff:<stdin>:347: warning: trailing space in the line
troff:<stdin>:366: warning: trailing space in the line
troff:<stdin>:367: warning: trailing space in the line
troff:<stdin>:370: warning: trailing space in the line
troff:<stdin>:371: warning: trailing space in the line
troff:<stdin>:372: warning: trailing space in the line
troff:<stdin>:373: warning: trailing space in the line
troff:<stdin>:374: warning: trailing space in the line
troff:<stdin>:375: warning: trailing space in the line
troff:<stdin>:376: warning: trailing space in the line
troff:<stdin>:377: warning: trailing space in the line
troff:<stdin>:378: warning: trailing space in the line
troff:<stdin>:381: warning: trailing space in the line
troff:<stdin>:382: warning: trailing space in the line
troff:<stdin>:383: warning: trailing space in the line
troff:<stdin>:384: warning: trailing space in the line
troff:<stdin>:387: warning: trailing space in the line
troff:<stdin>:388: warning: trailing space in the line
troff:<stdin>:391: warning: trailing space in the line
troff:<stdin>:398: warning: trailing space in the line
troff:<stdin>:401: warning: trailing space in the line
troff:<stdin>:403: warning: trailing space in the line
troff:<stdin>:404: warning: trailing space in the line
troff:<stdin>:405: warning: trailing space in the line
troff:<stdin>:408: warning: trailing space in the line
troff:<stdin>:410: warning: trailing space in the line
troff:<stdin>:413: warning: trailing space in the line
troff:<stdin>:414: warning: trailing space in the line
troff:<stdin>:417: warning: trailing space in the line
troff:<stdin>:420: warning: trailing space in the line
troff:<stdin>:421: warning: trailing space in the line
troff:<stdin>:422: warning: trailing space in the line
troff:<stdin>:424: warning: trailing space in the line
troff:<stdin>:425: warning: trailing space in the line
troff:<stdin>:428: warning: trailing space in the line
troff:<stdin>:429: warning: trailing space in the line
troff:<stdin>:430: warning: trailing space in the line
troff:<stdin>:431: warning: trailing space in the line
troff:<stdin>:432: warning: trailing space in the line
troff:<stdin>:439: warning: trailing space in the line
troff:<stdin>:440: warning: trailing space in the line
troff:<stdin>:441: warning: trailing space in the line
troff:<stdin>:446: warning: trailing space in the line
troff:<stdin>:463: warning: trailing space in the line
troff:<stdin>:464: warning: trailing space in the line
troff:<stdin>:465: warning: trailing space in the line
troff:<stdin>:467: warning: name 'DS' not defined
troff:<stdin>:476: warning: name 'DE' not defined
troff:<stdin>:478: warning: trailing space in the line
troff:<stdin>:492: warning: trailing space in the line
troff:<stdin>:493: warning: trailing space in the line
troff:<stdin>:494: warning: trailing space in the line
troff:<stdin>:495: warning: trailing space in the line
troff:<stdin>:496: warning: trailing space in the line
troff:<stdin>:497: warning: trailing space in the line
troff:<stdin>:498: warning: trailing space in the line
troff:<stdin>:499: warning: trailing space in the line
troff:<stdin>:500: warning: trailing space in the line
troff:<stdin>:501: warning: trailing space in the line
troff:<stdin>:502: warning: trailing space in the line
* What outcome did you expect instead?
No output (no warnings).
-.-
General remarks and further material, if a diff-file exist, are in the
attachments.
-- System Information:
Debian Release: forky/sid
APT prefers testing
APT policy: (500, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.17.11+deb14-amd64 (SMP w/2 CPU threads; PREEMPT)
Locale: LANG=is_IS.iso88591, LC_CTYPE=is_IS.iso88591 (charmap=ISO-8859-1),
LANGUAGE not set
Shell: /bin/sh linked to /usr/bin/dash
Init: sysvinit (via /sbin/init)
Versions of packages docbook-to-man depends on:
ii docbook 4.5-11
ii libc6 2.42-5
ii opensp 1.5.2-15.2
docbook-to-man recommends no packages.
docbook-to-man suggests no packages.
-- no debconf information
Input file is transpec.5
Output from "mandoc -T lint transpec.5": (shortened list)
1 ERROR: skipping unknown macro: .DE
1 ERROR: skipping unknown macro: .DS
123 STYLE: input text line longer than 80 bytes:
163 STYLE: whitespace at end of input line
6 WARNING: skipping paragraph macro: PP after SH
7 WARNING: skipping paragraph macro: PP after SS
Find most trailing spaces with:
grep -n -e ' $' -e ' \\f.$' -e ' \\"' <man page>
-.-.
Output from
test-nroff -mandoc -t -ww -z transpec.5: (shortened list)
1 .l = 1920u = 80n = 80m, .i = 120u, TW (table width) = 1824u = 76n = 76m
1 .l = 1920u = 80n = 80m, .i = 120u, TW (table width) = 1920u = 80n = 80m
1 .l = 1920u = 80n = 80m, .i = 120u, TW (table width) = 2064u = 86n = 86m
1 name 'DE' not defined
1 name 'DS' not defined
3 table wider than line length minus indentation
146 line(s) with a trailing space
Find most trailing spaces with:
grep -n -e ' $' -e ' \\f.$' -e ' \\"' <man page>
-.-.
Input file is transpec.5
Remove space characters (whitespace) at the end of lines.
Use "git apply ... --whitespace=fix" to fix extra space issues, or use
global configuration "core.whitespace".
Number of lines affected is
163
-.-.
Reduce space between words.
transpec.5:193:\fIvalue\fP is the rest of the line and may be any string.
This action is done immediately before \fBEndText\fP.
transpec.5:256:a reference to the value of an attribute: \fB${\fIname\fB}\fR.
transpec.5:259:by using the form: \fB${\fIname default\fB}\fR.
-.-.
Change a HYPHEN-MINUS (code 0x2D) to a minus(-dash) (\-),
if it
is in front of a name for an option,
is a symbol for standard input,
is a single character used to indicate an option,
or is in the NAME section (man-pages(7)).
N.B. - (0x2D), processed as a UTF-8 file, is changed to a hyphen
(0x2010, groff \[u2010] or \[hy]) in the output.
46:\fBtranspec\fP - translation specification for \fBinstant\fP
-.-.
Wrong distance (not two spaces) between sentences in the input file.
Separate the sentences and subordinate clauses; each begins on a new
line. See man-pages(7) ("Conventions for source file layout") and
"info groff" ("Input Conventions").
The best procedure is to always start a new sentence on a new line,
at least, if you are typing on a computer.
Remember coding: Only one command ("sentence") on each (logical) line.
E-mail: Easier to quote exactly the relevant lines.
Generally: Easier to edit the sentence.
Patches: Less unaffected text.
Search for two adjacent words is easier, when they belong to the same line,
and the same phrase.
The amount of space between sentences in the output can then be
controlled with the ".ss" request.
Mark a final abbreviation point as such by suffixing it with "\&".
Some sentences (etc.) do not begin on a new line.
Split (sometimes) lines after a punctuation mark; before a conjunction.
Lines with only one (or two) space(s) between sentences could be split,
so latter sentences begin on a new line.
Use
#!/usr/bin/sh
sed -e '/^\./n' \
-e 's/\([[:alpha:]]\)\. */\1.\n/g' $1
to split lines after a sentence period.
Check result with the difference between the formatted outputs.
See also the attachment "general.bugs"
76:then that translation spec is said to match. The appropriate actions, as
specified in that spec, are then taken.
80:For quick reference, this is a brief summary of the possible criteria fields
for translation. A complete discussion of each follows.
140:For quick reference, this is a brief summary of the action fields for
translation. They are only performed if all the criteria are satisfied.
193:\fIvalue\fP is the rest of the line and may be any string. This action is
done immediately before \fBEndText\fP.
197:This names the spec with the number \fIspec-id\fP. Other specs may refer to
this one by this number by an \fBAction\fP field or an \fB_action\fP special
variable.
218:Most special characters are escaped with a \e (backslash). Like in C or
shell programs, to print a \e (backslash), you must escape it with another
backslash. These special character strings are:
275:This is the date and time that the program started. The format is: \f(CWTue
10 Aug 1993, 16:52\fP.
398:Print the name of the sgml instance file to the output stream. If
\fBline\fP is specified, also print the line number.
497:until an element with no IDREF attributes is found. It will then apply the
transpec numbered \fB87\fP to that element,
-.-.
Split lines longer than 80 characters (fill completely
an A4 sized page line on a terminal)
into two or more lines.
Appropriate break points are the end of a sentence and a subordinate
clause; after punctuation marks.
Add "\:" to split the string for the output, "\<newline>" in the source.
[List of affected lines removed.]
Longest line is number 218 with 194 characters
Most special characters are escaped with a \e (backslash). Like in C or shell
programs, to print a \e (backslash), you must escape it with another backslash.
These special character strings are:
-.-.
Do not use more than two space characters between sentences or (better)
only a new line character.
193:\fIvalue\fP is the rest of the line and may be any string. This action is
done immediately before \fBEndText\fP.
-.-.
Use the name of units in text; use symbols in tables and
calculations.
The rule is to have a (no-break, \~) space between a number and
its units (see "www.bipm.org/en/publications/si-brochure")
296:"\fB${_followrel child TITLE 15t}\fR"), will cause the criteria statements
-.-.
Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".
[List of affected lines removed.]
-.-.
Only one space character is after a possible end of sentence
(after a punctuation, that can end a sentence).
transpec.5:76:then that translation spec is said to match. The appropriate
actions, as specified in that spec, are then taken.
transpec.5:80:For quick reference, this is a brief summary of the possible
criteria fields for translation. A complete discussion of each follows.
transpec.5:140:For quick reference, this is a brief summary of the action
fields for translation. They are only performed if all the criteria are
satisfied.
transpec.5:197:This names the spec with the number \fIspec-id\fP. Other specs
may refer to this one by this number by an \fBAction\fP field or an
\fB_action\fP special variable.
transpec.5:218:Most special characters are escaped with a \e (backslash). Like
in C or shell programs, to print a \e (backslash), you must escape it with
another backslash. These special character strings are:
transpec.5:275:This is the date and time that the program started. The format
is: \f(CWTue 10 Aug 1993, 16:52\fP.
transpec.5:398:Print the name of the sgml instance file to the output stream.
If \fBline\fP is specified, also print the line number.
transpec.5:497:until an element with no IDREF attributes is found. It will then
apply the transpec numbered \fB87\fP to that element,
-.-.
Remove quotes when there is a printable
but no space character between them
and the quotes are not for emphasis (markup),
for example as an argument to a macro.
transpec.5:44:.TH "\fBtranspec\fP" "5" "file format"
transpec.5:45:.SH "Name"
transpec.5:47:.SH "Synopsis"
transpec.5:52:.SH "Description"
transpec.5:247:.SH "Variables"
transpec.5:274:.IP "\fBdate\fP"
transpec.5:276:.IP "\fBhost\fP"
transpec.5:278:.IP "\fBtranspec\fP"
transpec.5:280:.IP "\fBuser\fP"
transpec.5:336:.IP "\fB_allatts\fP"
transpec.5:365:.IP "\fB_filename\fP"
transpec.5:407:.IP "\fB_location\fP"
transpec.5:427:.IP "\fB_path\fP"
transpec.5:459:.IP "\fB+content\fP"
transpec.5:461:.SH "Examples"
-.-.
Add lines to use the CR font for groff instead of CW.
.if t \{\
. ie \\n(.g .ft CR
. el .ft CW
.\}
469:.ft CW
482:.ft CW
506:.ft CW
-.-.
.\" Define a fallback for the CW font
.
.if \n(.g \{\
. ie t .ftr CW CR
. el .ftr CW R
.\}
275:This is the date and time that the program started. The format is: \f(CWTue
10 Aug 1993, 16:52\fP.
368:For example, to print the filename in the latex macro from the epsf macro
package, use \f(CW\e\eepsfboxi{${_filename}}\fP.
431:For example: \f(CWOSF-BOOK(3) BODY(0) CHAPTER(4) SECTION\fP.
-.-.
Split lines longer than 80 characters (fill completely
an A4 sized page line on a terminal)
into two or more lines.
Appropriate break points are the end of a sentence and a subordinate
clause; after punctuation marks.
Add "\:" to split the string for the output, "\<newline>" in the source.
[List of affected lines removed.]
Longest line is number 38 with 98 characters
\fB_eachatt\fP \fIatt\fP \fIspec-id\fP [\fIspec-id\fP]@do spec-id for each word
of attribute value
-.-.
Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".
temp.table:10:PAttSet@attname (val)@parent has this attribute set (optional to
value val)
-.-.
Output from "test-nroff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=0 -ww -z ":
troff:<stdin>:54: warning: trailing space in the line
troff:<stdin>:57: warning: trailing space in the line
troff:<stdin>:58: warning: trailing space in the line
troff:<stdin>:59: warning: trailing space in the line
troff:<stdin>:60: warning: trailing space in the line
troff:<stdin>:62: warning: trailing space in the line
troff:<stdin>:63: warning: trailing space in the line
troff:<stdin>:64: warning: trailing space in the line
troff:<stdin>:65: warning: trailing space in the line
troff:<stdin>:66: warning: trailing space in the line
troff:<stdin>:70: warning: trailing space in the line
troff:<stdin>:71: warning: trailing space in the line
troff:<stdin>:74: warning: trailing space in the line
troff:<stdin>:75: warning: trailing space in the line
troff:<stdin>:77: warning: trailing space in the line
<stdin>:85: warning: table wider than line length minus indentation
an.tmac:<stdin>:95: warning: .l = 1920u = 80n = 80m, .i = 120u, TW (table
width) = 2064u = 86n = 86m
troff:<stdin>:98: warning: trailing space in the line
troff:<stdin>:101: warning: trailing space in the line
troff:<stdin>:102: warning: trailing space in the line
troff:<stdin>:103: warning: trailing space in the line
troff:<stdin>:104: warning: trailing space in the line
troff:<stdin>:109: warning: trailing space in the line
troff:<stdin>:110: warning: trailing space in the line
troff:<stdin>:113: warning: trailing space in the line
troff:<stdin>:114: warning: trailing space in the line
troff:<stdin>:115: warning: trailing space in the line
troff:<stdin>:121: warning: trailing space in the line
troff:<stdin>:122: warning: trailing space in the line
troff:<stdin>:123: warning: trailing space in the line
troff:<stdin>:135: warning: trailing space in the line
troff:<stdin>:140: warning: trailing space in the line
<stdin>:146: warning: table wider than line length minus indentation
an.tmac:<stdin>:157: warning: .l = 1920u = 80n = 80m, .i = 120u, TW (table
width) = 1824u = 76n = 76m
troff:<stdin>:160: warning: trailing space in the line
troff:<stdin>:164: warning: trailing space in the line
troff:<stdin>:165: warning: trailing space in the line
troff:<stdin>:166: warning: trailing space in the line
troff:<stdin>:167: warning: trailing space in the line
troff:<stdin>:170: warning: trailing space in the line
troff:<stdin>:171: warning: trailing space in the line
troff:<stdin>:172: warning: trailing space in the line
troff:<stdin>:175: warning: trailing space in the line
troff:<stdin>:176: warning: trailing space in the line
troff:<stdin>:177: warning: trailing space in the line
troff:<stdin>:178: warning: trailing space in the line
troff:<stdin>:180: warning: trailing space in the line
troff:<stdin>:181: warning: trailing space in the line
troff:<stdin>:184: warning: trailing space in the line
troff:<stdin>:187: warning: trailing space in the line
troff:<stdin>:188: warning: trailing space in the line
troff:<stdin>:191: warning: trailing space in the line
troff:<stdin>:192: warning: trailing space in the line
troff:<stdin>:193: warning: trailing space in the line
troff:<stdin>:194: warning: trailing space in the line
troff:<stdin>:197: warning: trailing space in the line
troff:<stdin>:204: warning: trailing space in the line
troff:<stdin>:208: warning: trailing space in the line
troff:<stdin>:213: warning: trailing space in the line
troff:<stdin>:214: warning: trailing space in the line
troff:<stdin>:217: warning: trailing space in the line
troff:<stdin>:227: warning: trailing space in the line
troff:<stdin>:230: warning: trailing space in the line
troff:<stdin>:236: warning: trailing space in the line
troff:<stdin>:237: warning: trailing space in the line
troff:<stdin>:240: warning: trailing space in the line
troff:<stdin>:241: warning: trailing space in the line
troff:<stdin>:242: warning: trailing space in the line
troff:<stdin>:243: warning: trailing space in the line
troff:<stdin>:249: warning: trailing space in the line
troff:<stdin>:250: warning: trailing space in the line
troff:<stdin>:251: warning: trailing space in the line
troff:<stdin>:252: warning: trailing space in the line
troff:<stdin>:253: warning: trailing space in the line
troff:<stdin>:255: warning: trailing space in the line
troff:<stdin>:261: warning: trailing space in the line
troff:<stdin>:262: warning: trailing space in the line
troff:<stdin>:263: warning: trailing space in the line
troff:<stdin>:264: warning: trailing space in the line
troff:<stdin>:267: warning: trailing space in the line
troff:<stdin>:271: warning: trailing space in the line
troff:<stdin>:285: warning: trailing space in the line
troff:<stdin>:286: warning: trailing space in the line
troff:<stdin>:287: warning: trailing space in the line
troff:<stdin>:288: warning: trailing space in the line
<stdin>:303: warning: table wider than line length minus indentation
an.tmac:<stdin>:331: warning: .l = 1920u = 80n = 80m, .i = 120u, TW (table
width) = 1920u = 80n = 80m
troff:<stdin>:334: warning: trailing space in the line
troff:<stdin>:337: warning: trailing space in the line
troff:<stdin>:338: warning: trailing space in the line
troff:<stdin>:342: warning: trailing space in the line
troff:<stdin>:344: warning: trailing space in the line
troff:<stdin>:345: warning: trailing space in the line
troff:<stdin>:346: warning: trailing space in the line
troff:<stdin>:347: warning: trailing space in the line
troff:<stdin>:366: warning: trailing space in the line
troff:<stdin>:367: warning: trailing space in the line
troff:<stdin>:370: warning: trailing space in the line
troff:<stdin>:371: warning: trailing space in the line
troff:<stdin>:372: warning: trailing space in the line
troff:<stdin>:373: warning: trailing space in the line
troff:<stdin>:374: warning: trailing space in the line
troff:<stdin>:375: warning: trailing space in the line
troff:<stdin>:376: warning: trailing space in the line
troff:<stdin>:377: warning: trailing space in the line
troff:<stdin>:378: warning: trailing space in the line
troff:<stdin>:381: warning: trailing space in the line
troff:<stdin>:382: warning: trailing space in the line
troff:<stdin>:383: warning: trailing space in the line
troff:<stdin>:384: warning: trailing space in the line
troff:<stdin>:387: warning: trailing space in the line
troff:<stdin>:388: warning: trailing space in the line
troff:<stdin>:391: warning: trailing space in the line
troff:<stdin>:398: warning: trailing space in the line
troff:<stdin>:401: warning: trailing space in the line
troff:<stdin>:403: warning: trailing space in the line
troff:<stdin>:404: warning: trailing space in the line
troff:<stdin>:405: warning: trailing space in the line
troff:<stdin>:408: warning: trailing space in the line
troff:<stdin>:410: warning: trailing space in the line
troff:<stdin>:413: warning: trailing space in the line
troff:<stdin>:414: warning: trailing space in the line
troff:<stdin>:417: warning: trailing space in the line
troff:<stdin>:420: warning: trailing space in the line
troff:<stdin>:421: warning: trailing space in the line
troff:<stdin>:422: warning: trailing space in the line
troff:<stdin>:424: warning: trailing space in the line
troff:<stdin>:425: warning: trailing space in the line
troff:<stdin>:428: warning: trailing space in the line
troff:<stdin>:429: warning: trailing space in the line
troff:<stdin>:430: warning: trailing space in the line
troff:<stdin>:431: warning: trailing space in the line
troff:<stdin>:432: warning: trailing space in the line
troff:<stdin>:439: warning: trailing space in the line
troff:<stdin>:440: warning: trailing space in the line
troff:<stdin>:441: warning: trailing space in the line
troff:<stdin>:446: warning: trailing space in the line
troff:<stdin>:463: warning: trailing space in the line
troff:<stdin>:464: warning: trailing space in the line
troff:<stdin>:465: warning: trailing space in the line
troff:<stdin>:467: warning: name 'DS' not defined
troff:<stdin>:476: warning: name 'DE' not defined
troff:<stdin>:478: warning: trailing space in the line
troff:<stdin>:492: warning: trailing space in the line
troff:<stdin>:493: warning: trailing space in the line
troff:<stdin>:494: warning: trailing space in the line
troff:<stdin>:495: warning: trailing space in the line
troff:<stdin>:496: warning: trailing space in the line
troff:<stdin>:497: warning: trailing space in the line
troff:<stdin>:498: warning: trailing space in the line
troff:<stdin>:499: warning: trailing space in the line
troff:<stdin>:500: warning: trailing space in the line
troff:<stdin>:501: warning: trailing space in the line
troff:<stdin>:502: warning: trailing space in the line
-.-
Additionally:
Change '.DS' (display) to ".PP"; remove '.DE' (display end)
Move a table to the next page with '.ne 5v' for an A4 page size (troff).
-.-
Generally:
Split (sometimes) lines after a punctuation mark; before a conjunction.
-.-
Tables:
Put data, that are wider than the header in the (centered) last column,
in a "T{...\nT}" block, when the table gets wider than the output line.
Table headers, that are wider than any data in the corresponding column,
do not need to be centered, so left adjustment (l, L) is sufficient.
--- transpec.5 2025-12-16 14:58:16.012072655 +0000
+++ transpec.5.new 2025-12-16 18:02:12.572620011 +0000
@@ -1,32 +1,32 @@
.\" -*- nroff -*-
.\"
-.\" Copyright (c) 1994
-.\" Open Software Foundation, Inc.
-.\"
-.\" Permission is hereby granted to use, copy, modify and freely distribute
-.\" the software in this file and its documentation for any purpose without
-.\" fee, provided that the above copyright notice appears in all copies and
-.\" that both the copyright notice and this permission notice appear in
-.\" supporting documentation. Further, provided that the name of Open
-.\" Software Foundation, Inc. ("OSF") not be used in advertising or
-.\" publicity pertaining to distribution of the software without prior
-.\" written permission from OSF. OSF makes no representations about the
-.\" suitability of this software for any purpose. It is provided "as is"
-.\" without express or implied warranty.
+.\" Copyright (c) 1994
+.\" Open Software Foundation, Inc.
+.\"
+.\" Permission is hereby granted to use, copy, modify and freely distribute
+.\" the software in this file and its documentation for any purpose without
+.\" fee, provided that the above copyright notice appears in all copies and
+.\" that both the copyright notice and this permission notice appear in
+.\" supporting documentation. Further, provided that the name of Open
+.\" Software Foundation, Inc. ("OSF") not be used in advertising or
+.\" publicity pertaining to distribution of the software without prior
+.\" written permission from OSF. OSF makes no representations about the
+.\" suitability of this software for any purpose. It is provided "as is"
+.\" without express or implied warranty.
.\"
.\" Copyright (c) 1996 X Consortium
.\" Copyright (c) 1996 Dalrymple Consulting
-.\"
+.\"
.\" Permission is hereby granted, free of charge, to any person obtaining a
copy
.\" of this software and associated documentation files (the "Software"), to
deal
.\" in the Software without restriction, including without limitation the
rights
.\" to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
.\" copies of the Software, and to permit persons to whom the Software is
.\" furnished to do so, subject to the following conditions:
-.\"
+.\"
.\" The above copyright notice and this permission notice shall be included in
.\" all copies or substantial portions of the Software.
-.\"
+.\"
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
.\" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
.\" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE
@@ -34,47 +34,50 @@
.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
.\" OTHER DEALINGS IN THE SOFTWARE.
-.\"
+.\"
.\" Except as contained in this notice, the names of the X Consortium and
.\" Dalrymple Consulting shall not be used in advertising or otherwise to
.\" promote the sale, use or other dealings in this Software without prior
.\" written authorization.
.\"
.\" Translated with /usr/local/lib/tpt/ref-man.ts by fld on cord, Wed 07 Feb
1996, 22:00
-.TH "\fBtranspec\fP" "5" "file format"
-.SH "Name"
-\fBtranspec\fP - translation specification for \fBinstant\fP
-.SH "Synopsis"
+.\" Define a fallback for the CW font
+.
+.if \n(.g \{\
+. ie t .ftr CW CR
+. el .ftr CW R
+.\}
+.
+.TH \fBtranspec\fP 5 "file format"
+.SH Name
+\fBtranspec\fP \- translation specification for \fBinstant\fP
+.SH Synopsis
.na
-.PP
\fBfile.ts\fP
.ad
-.SH "Description"
-.PP
-The \fBtranspec\fP file is used by the \fBinstant\fP program to translate an
SGML document instance to a format suitable for a formatting application.
+.SH Description
+The \fBtranspec\fP file is used by the \fBinstant\fP program to translate an
SGML document instance to a format suitable for a formatting application.
The convention is to name the file with the suffix \fB.ts\fP.
.PP
-A \fBtranspec\fP file is composed of a number of individual translation specs.
-Each translation spec (transpec) is made up of a number of fields, one per
line.
-Translation specs are separated by a line with a leading dash. Text after the
dash is ignored.
-Fields are composed of two parts, a name and a value, separated by a colon.
+A \fBtranspec\fP file is composed of a number of individual translation specs.
+Each translation spec (transpec) is made up of a number of fields, one per
line.
+Translation specs are separated by a line with a leading dash. Text after the
dash is ignored.
+Fields are composed of two parts, a name and a value, separated by a colon.
The colon must immediately follow the name, and any amount of whitespace
(blanks and tabs) may be present between the colon and value.
-Values should not be quoted, and you should be careful of trailing spaces.
-(Trailing space will be considered part of the value.)
-Quotes, if they appear, will be considered part of the value of the fields.
-Lines that begin with whitespace (blanks and tabs) are a continuation of the
previous line; the leading space is ignored.
-These characteristics are very similar to those of e-mail headers.
+Values should not be quoted, and you should be careful of trailing spaces.
+(Trailing space will be considered part of the value.)
+Quotes, if they appear, will be considered part of the value of the fields.
+Lines that begin with whitespace (blanks and tabs) are a continuation of the
previous line; the leading space is ignored.
+These characteristics are very similar to those of e-mail headers.
Lines beginning with a \fB#\fP (number sign) are comments and blank lines are
ignored.
.SH "Field Descriptions"
-.PP
-Some fields are for identifying criteria that determines if a particular spec
matches an element in the instance.
-Others specify what action is to take place when a match happens, such as
sending text to the output stream.
+Some fields are for identifying criteria that determines if a particular spec
matches an element in the instance.
+Others specify what action is to take place when a match happens, such as
sending text to the output stream.
.SS "Criteria fields"
-.PP
-Criteria fields restrict the conditions under which a single translation spec
will apply.
-If each field specified in a particular transpec matches an element under
consideration in the document instance,
+Criteria fields restrict the conditions under which a single translation spec
will apply.
+If each field specified in a particular transpec matches an element under
consideration in the document instance,
then that translation spec is said to match. The appropriate actions, as
specified in that spec, are then taken.
-The program, \fBinstant\fP, searches the list of transpecs in the order given
in the file.
+The program, \fBinstant\fP, searches the list of transpecs in the order given
in the file.
Therefore, the more restrictive specs (those with more criteria) should appear
before less restrictive ones.
.PP
For quick reference, this is a brief summary of the possible criteria fields
for translation. A complete discussion of each follows.
@@ -88,39 +91,43 @@ AttValue@attname reg-expr@current elemen
Content@reg-expr@is reg-expr in char content>
Context@context@element context, up the tree
NthChild@number@current element is Nth child of its parent
-PAttSet@attname (val)@parent has this attribute set (optional to value val)
+PAttSet@attname (val)@T{
+parent has this attribute set (optional to value val)
+T}
Relation@relationship gi@gi has relationship to current element
-VarREValue@var REvalue@variable is set to regular expression value
+VarREValue@var REvalue@T{
+variable is set to regular expression value
+T}
VarValue@var value@variable is set to value
.TE
'br\" labeled list
.IP "\fBGI:\fP \fIgi\fP [...]"
-\fIgi\fP is the name of the generic identifier, or element name, to consider.
+\fIgi\fP is the name of the generic identifier, or element name, to consider.
More than one GI may appear in this field.
.IP "\fBAttValue:\fP \fIattname\fP \fIregular-expression\fP"
-This is an attribute name-value pair, where \fIattname\fP is an attribute if
the GI.
-The \fIregular-expression\fP is of the form accepted by the unix program
\fBegrep\fP.
-This pair is compared to the corresponding attribute name-value pairs of the
GI under consideration.
-To simply test if an attribute us set, use \fB.\fP (a dot) for
\fIregular-expression\fP.
+This is an attribute name-value pair, where \fIattname\fP is an attribute if
the GI.
+The \fIregular-expression\fP is of the form accepted by the unix program
\fBegrep\fP.
+This pair is compared to the corresponding attribute name-value pairs of the
GI under consideration.
+To simply test if an attribute us set, use \fB.\fP (a dot) for
\fIregular-expression\fP.
There may be more than one of these lines for each transpec.
.IP "\fBContent:\fP \fIregular-expression\fP"
This specifies that the character content of GI contains a string matching the
\fIregular-expression\fP.
.IP "\fBContext:\fP \fIcontext\fP"
-This specifies the \fIcontext\fP in which to apply this translation spec.
-It is either a list of generic identifiers or a regular expression describing
a list of generic identifiers, looking up the hierarchy.
+This specifies the \fIcontext\fP in which to apply this translation spec.
+It is either a list of generic identifiers or a regular expression describing
a list of generic identifiers, looking up the hierarchy.
The first is the parent of the GI.
.IP "\fBNthChild:\fP \fInumber\fP"
-This specifies that the GI is the \fInumber\fPth child element of its parent.
-Children are numbered starting with \fB1\fP.
-Negative numbers may be used to indicate order counting backwards.
+This specifies that the GI is the \fInumber\fPth child element of its parent.
+Children are numbered starting with \fB1\fP.
+Negative numbers may be used to indicate order counting backwards.
For example, \-1 denotes the last child.
.IP "\fBPAttSet:\fP \fIattname\fP"
This specifies that the parent has this attribute, \fIattname\fP, set to any
value (not IMPLIED). A value to match may optionally
be specified after attname.
.IP "\fBRelation:\fP \fIrelationship\fP \fIgi\fP"
-This specifies that the current element has the \fIrelationship\fP to the
named \fIgi\fP.
-The acceptable relationships are: \fBancestor\fP (anywhere up the tree),
\fBchild\fP (immediate child),
-\fBdescendant\fP (anywhere down the tree), \fBparent\fP (immediate ancestor),
\fBsibling\fP (share same parent element),
+This specifies that the current element has the \fIrelationship\fP to the
named \fIgi\fP.
+The acceptable relationships are: \fBancestor\fP (anywhere up the tree),
\fBchild\fP (immediate child),
+\fBdescendant\fP (anywhere down the tree), \fBparent\fP (immediate ancestor),
\fBsibling\fP (share same parent element),
\fBsibling+\fP (any later sibling), \fBsibling+1\fP (the immediately following
sibling), \fBsibling-\fP (any earlier sibling),
\fBsibling-1\fP (the immediately following sibling).
.IP "\fBVarREValue:\fP \fIvarname\fP \fIREvalue\fP"
@@ -132,12 +139,11 @@ This specifies that the global variable
value \fIvalue\fP (see the \fBVarREValue\fP statement).
'br\" labeled list end
.PP
-There are two special GIs.
+There are two special GIs.
If specified, \fB_Start\fP and \fB_End\fP are processed as if they were GIs in
the instance at the start and end of the translation, respectively.
Their criteria are never checked. Only their actions are performed.
.SS "Action fields"
-.PP
-For quick reference, this is a brief summary of the action fields for
translation. They are only performed if all the criteria are satisfied.
+For quick reference, this is a brief summary of the action fields for
translation. They are only performed if all the criteria are satisfied.
A complete discussion of each follows.
.P
.TS
@@ -147,7 +153,9 @@ l l l.
Action@spec-id@use transpec whose spec ID is `spec-id'
EndText@text@text for end of element
Increment@name@increment variable `name'
-Ignore@key@flag for ignoring element's children and/or data
+Ignore@key@T{
+flag for ignoring element's children and/or data
+T}
Message@text@text to send to stderr
Quit@text@print text and quit program
Replace@text@replace this subtree with text
@@ -157,64 +165,62 @@ StartText@text@text for start of element
.TE
'br\" labeled list
.IP "\fBAction:\fP \fIspec-id\fP"
-Use the actions of the spec identified by the \fBSpecID\fP with matching
identifier \fIspec-id\fP.
+Use the actions of the spec identified by the \fBSpecID\fP with matching
identifier \fIspec-id\fP.
.IP "\fBEndText:\fP \fItext\fP"
This specifies text to be output when the end tag is processed.
.IP "\fBIgnore:\fP \fIkey\fP"
-This specifies that the data or children for this element are to be ignored.
-Set \fIkey\fP to \fBall\fP to ignore the element (data and child elements),
-to \fBdata\fP to ignore the immediate character data content (child elements
are still descended into),
-and to \fBchildren\fP to process the immediate character data content but not
descended into child elements.
+This specifies that the data or children for this element are to be ignored.
+Set \fIkey\fP to \fBall\fP to ignore the element (data and child elements),
+to \fBdata\fP to ignore the immediate character data content (child elements
are still descended into),
+and to \fBchildren\fP to process the immediate character data content but not
descended into child elements.
Other actions specified in this transpec are still performed, however.
.IP "\fBIncrement:\fP \fIname\fP"
-This is used to increment a variable whose value is a number.
-If the variable is not a number, no action will be taken.
-The variable must have been previously defined. This action is done
immediately before \fBEndText\fP.
+This is used to increment a variable whose value is a number.
+If the variable is not a number, no action will be taken.
+The variable must have been previously defined. This action is done
immediately before \fBEndText\fP.
There may be more than one of these lines for each transpec.
.IP "\fBMessage:\fP \fItext\fP"
-This specifies a string to be printed to the standard error when the matching
element is processed.
-It is intended for informing the user of the progress of the translation.
-It is also used for validation of instances (see the \fB\-v\fP flag of
\fBinstant\fP(1));
-a spec would be written to recognize a construct that is not allowed.
+This specifies a string to be printed to the standard error when the matching
element is processed.
+It is intended for informing the user of the progress of the translation.
+It is also used for validation of instances (see the \fB\-v\fP flag of
\fBinstant\fP(1));
+a spec would be written to recognize a construct that is not allowed.
This action is done immediately after \fBStartText\fP.
-Messages are also useful for debugging spec files; one is able to easily tell
when a matching spec is processed,
-without looking at the actual output of the translation.
+Messages are also useful for debugging spec files; one is able to easily tell
when a matching spec is processed,
+without looking at the actual output of the translation.
Note that the spec writer is responsible for putting newlines (\fB\en\fP) in
the message text.
.IP "\fBReplace:\fP \fItext\fP"
-This specifies text to replace the current subtree with.
+This specifies text to replace the current subtree with.
This is equivalent to \fBStartText\fP and \fBIgnore\fP.
.IP "\fBQuit:\fP \fItext\fP"
-This specifies text to be printed to the standard error. The program then
terminates with exit status 1.
-This is intended for bailing out when an undesirable instance is encountered
+This specifies text to be printed to the standard error. The program then
terminates with exit status 1.
+This is intended for bailing out when an undesirable instance is encountered
(such as when it is known that the formatting application can never handle a
class of components, like tables).
.IP "\fBSet:\fP \fIname\fP \fIvalue\fP"
-This is used to set a variable whose name is \fIname\fP and value is
\fIvalue\fP.
-Names that would be valid for GIs in the document instance are valid for
variable names.
-\fIvalue\fP is the rest of the line and may be any string. This action is
done immediately before \fBEndText\fP.
-There may be more than one of these lines for each transpec.
+This is used to set a variable whose name is \fIname\fP and value is
\fIvalue\fP.
+Names that would be valid for GIs in the document instance are valid for
variable names.
+\fIvalue\fP is the rest of the line and may be any string. This action is
done immediately before \fBEndText\fP.
+There may be more than one of these lines for each transpec.
See the discussion on variables below.
.IP "\fBSpecID:\fP \fIspec-id\fP"
-This names the spec with the number \fIspec-id\fP. Other specs may refer to
this one by this number by an \fBAction\fP field or an \fB_action\fP special
variable.
+This names the spec with the number \fIspec-id\fP. Other specs may refer to
this one by this number by an \fBAction\fP field or an \fB_action\fP special
variable.
This is used for cases where several specs to perform the exact same action.
.IP "\fBStartText:\fP \fItext\fP"
This specifies text to be output when the start tag is processed.
'br\" labeled list end
.SS "Other Fields"
-.PP
-These fields may appear anywhere. The action occurs when the translation spec
file is read, before any elements are translated.
+These fields may appear anywhere. The action occurs when the translation spec
file is read, before any elements are translated.
Theses are independent of any element processing.
'br\" labeled list
.IP "\fBVar:\fP \fIname\fP \fIvalue\fP"
-This is used to define a variable whose name is \fIname\fP and value is
\fIvalue\fP.
+This is used to define a variable whose name is \fIname\fP and value is
\fIvalue\fP.
It is similar to \fBSet\fP, but it may occur anywhere in the file and takes
effect when the spec file is read.
'br\" labeled list end
.SS "Text Strings"
-.PP
-The \fItext\fP referred to in the \fBStartText\fP, \fBEndText\fP,
\fBReplace\fP,
-and \fBMessage\fP actions is more than simple character strings.
+The \fItext\fP referred to in the \fBStartText\fP, \fBEndText\fP,
\fBReplace\fP,
+and \fBMessage\fP actions is more than simple character strings.
Special sequences allow more complex output.
.PP
-One type of special sequence is for C-style string processing.
+One type of special sequence is for C-style string processing.
Most special characters are escaped with a \e (backslash). Like in C or shell
programs, to print a \e (backslash), you must escape it with another backslash.
These special character strings are:
'br\" labeled list
.IP "\fB\en (backslash-n)\fP"
@@ -224,68 +230,65 @@ This specifies that a carriage return ch
.IP "\fB\et (backslash-t)\fP"
This specifies that a tab character is to be printed to the output stream.
.IP "\fB\es (backslash-s)\fP"
-This specifies that a space is to be printed to the output stream.
+This specifies that a space is to be printed to the output stream.
This is useful for the end of a transpec line, where it can be difficult to
tell if a blank is present at the end.
.IP "\fB\e007 (backslash-007)\fP"
-This specifies that the character whose octal value is 007 is to be printed to
the output stream.
+This specifies that the character whose octal value is 007 is to be printed to
the output stream.
This works for any octal character value.
.IP "\fB^ (caret)\fP"
This specifies the that position in the string will be at the start of a line
in the output stream.
'br\" labeled list end
.PP
-If the first token of the text string is \fB#include\fP, then the second token
is taken to be a file name and that file is included.
-If the file is not found, the library directory, as mentioned above, is
searched.
+If the first token of the text string is \fB#include\fP, then the second token
is taken to be a file name and that file is included.
+If the file is not found, the library directory, as mentioned above, is
searched.
If the text string starts with a \fB!\fP (exclamation point), the rest of the
line is taken to be a command and the output of that command is inserted.
.PP
-An element's attributes may also be used in the text of output fields.
-To use an attribute value, precede its name with a \fB${\fP (dollar sign-left
curly bracket) and follow it with a \fB}\fP (right curly bracket).
-(This style is followed by the Bourne shell.) For example, \fB${TYPE}\fP.
-If the attribute is not set (not IMPLIED), nothing will be printed to the
output stream.
+An element's attributes may also be used in the text of output fields.
+To use an attribute value, precede its name with a \fB${\fP (dollar sign-left
curly bracket) and follow it with a \fB}\fP (right curly bracket).
+(This style is followed by the Bourne shell.) For example, \fB${TYPE}\fP.
+If the attribute is not set (not IMPLIED), nothing will be printed to the
output stream.
To specify a value to use if the attribute is not set, place the value after
the attribute name, separated by a space.
To return the attribute value in lower-case, add a colon followed by
lower-case l (\fB${TYPE:l}\fP.
-.SH "Variables"
+.SH Variables
+Variables in \fBinstant\fP are similar to those in many other string-oriented
programming languages, such as \fBsh\fP and \fBawk\fP.
+They are set by: \fBVar:\fP \fIname\fP \fIvalue\fP and \fBSet:\fP \fIname\fP
\fIvalue\fP.
+Values may be set and reset to any string.
+In a \fBVar\fP line, if the value begins with a \fB!\fP,
+then the rest of the line is executed as a command, and its output is taken as
the \fIvalue\fP.
.PP
-Variables in \fBinstant\fP are similar to those in many other string-oriented
programming languages, such as \fBsh\fP and \fBawk\fP.
-They are set by: \fBVar:\fP \fIname\fP \fIvalue\fP and \fBSet:\fP \fIname\fP
\fIvalue\fP.
-Values may be set and reset to any string.
-In a \fBVar\fP line, if the value begins with a \fB!\fP,
-then the rest of the line is executed as a command, and its output is taken as
the \fIvalue\fP.
-.PP
-A reference to the value of a variable follows the same syntax as
-a reference to the value of an attribute: \fB${\fIname\fB}\fR.
+A reference to the value of a variable follows the same syntax as
+a reference to the value of an attribute: \fB${\fIname\fB}\fR.
If that variable has not been defined, a null value will be returned.
A default value can be returned instead of null for an undefined variable
-by using the form: \fB${\fIname default\fB}\fR.
+by using the form: \fB${\fIname default\fB}\fR.
.PP
-Variables may be used as attributes are, that is in any of the text strings
mentioned above.
-In fact, if an attribute name is referred to and it is not set for a given
element,
-\fBinstant\fP looks for a variable with the same name. This way global
defaults can be set.
-If you want to be sure that you are accessing a local variable value, not an
attribute value, you can use lower or mixed case names.
+Variables may be used as attributes are, that is in any of the text strings
mentioned above.
+In fact, if an attribute name is referred to and it is not set for a given
element,
+\fBinstant\fP looks for a variable with the same name. This way global
defaults can be set.
+If you want to be sure that you are accessing a local variable value, not an
attribute value, you can use lower or mixed case names.
Attribute names, as passed by \fBonsgmls\fP, are in upper case.
.PP
-Any number of \fBVar\fP actions may appear in the spec file. These set the
values of the variables before any translation takes place.
+Any number of \fBVar\fP actions may appear in the spec file. These set the
values of the variables before any translation takes place.
The \fBSet\fP actions within transpecs are performed when that spec is
processed when an element matches the given criteria.
.SS "Preset Variables"
-.PP
-Several variables are preset by \fBinstant\fP upon start of the program.
+Several variables are preset by \fBinstant\fP upon start of the program.
Their values may be overridden in transpec files or on the command line.
'br\" labeled list
-.IP "\fBdate\fP"
+.IP \fBdate\fP
This is the date and time that the program started. The format is: \f(CWTue 10
Aug 1993, 16:52\fP.
-.IP "\fBhost\fP"
+.IP \fBhost\fP
This is the name of the host where the program is run. It is what is returned
by the \fBgethostname\fP library call.
-.IP "\fBtranspec\fP"
+.IP \fBtranspec\fP
This is the translation spec filename.
-.IP "\fBuser\fP"
+.IP \fBuser\fP
This is the login name of the user running the program.
'br\" labeled list end
.SS "Special Variables"
-.PP
-There is a collection of special variables called \fIspecial variables\fP.
-These are identified by starting the names with a \fB_\fP (underscore).
-This is a summary of the special variables. A complete discussion of each
special variable follows.
-\fBspec-id\fP refers to a number specified in a \fBSpecID\fP field.
+There is a collection of special variables called \fIspecial variables\fP.
+These are identified by starting the names with a \fB_\fP (underscore).
+This is a summary of the special variables. A complete discussion of each
special variable follows.
+\fBspec-id\fP refers to a number specified in a \fBSpecID\fP field.
When used in a special variable, it means to perform the action in that
translation spec.
.PP
Note that when a \fIspec-id\fR is given in a special variable,
@@ -296,6 +299,7 @@ the \fIspec-id\fR (with no spaces betwee
"\fB${_followrel child TITLE 15t}\fR"), will cause the criteria statements
in the named translation spec to evaluate successfully before that translation
spec will be processed.
+.ne 5v
.P
.TS
tab(@);
@@ -305,7 +309,9 @@ l l.
\fB_allatts\fP@print all attribute/value pairs
\fB_attval\fP \fIatt\fP [\fIvalue\fP] \fIspec-id\fP@use spec-id if attribute
matches
\fB_chasetogi\fP \fIgi\fP \fIspec-id\fP@follow IDREFs until gi found
-\fB_eachatt\fP \fIatt\fP \fIspec-id\fP [\fIspec-id\fP]@do spec-id for each
word of attribute value
+\fB_eachatt\fP \fIatt\fP \fIspec-id\fP [\fIspec-id\fP]@T{
+do spec-id for each word of attribute value
+T}
\fB_eachcon\fP \fIspec-id\fP [\fIspec-id\fP]@do spec-id for each word of
content
\fB_env\fP \fIenv-variable\fP@return value of env variable
\fB_filename\fP@filename of notation
@@ -325,26 +331,30 @@ l l.
\fB_path\fP@print path to current element
\fB_pattr\fP \fIattname\fP@value of parent's attribute
\fB_pfind\fP \fIargs ...\fP@same as \fB_find\fP, but start at parent
+.TE
+.TS
+tab(@);
+l l .
\fB_relation\fP \fIrel\fP \fIgi\fP \fIspec-id\fP [\fIspec-id\fP]@do spec-id if
relation matches
\fB_set\fP \fIvar\fP \fIvalue\fP@set variable to value
\fB_!\fP\fIcommand\fP@command to run
.TE
'br\" labeled list
.IP "\fB_action\fP \fIspec-id\fP"
-Use the actions of the spec identified by the \fBSpecID\fP with matching
identifier \fIspec-id\fP.
+Use the actions of the spec identified by the \fBSpecID\fP with matching
identifier \fIspec-id\fP.
This behaves similarly to the \fBAction\fP action, but is in addition to the
present translation spec.
-.IP "\fB_allatts\fP"
-Print all attribute name-value pairs of the current element to the output
stream.
-The name and value are separated by a \fB=\fP (equals sign), and the value is
surrounded by quotes.
+.IP \fB_allatts\fP
+Print all attribute name-value pairs of the current element to the output
stream.
+The name and value are separated by a \fB=\fP (equals sign), and the value is
surrounded by quotes.
This can be useful for creating a normalized version of the instance.
.IP "\fB_attval\fP \fIattname\fP [\fIvalue\fP] \fIspec-id\fP"
If the current element has an attribute named \fIattname\fP, optionally whose
value matches \fIvalue\fP,
-use the actions of the transpec identified by \fIspec-id\fP.
+use the actions of the transpec identified by \fIspec-id\fP.
.IP "\fB_chasetogi\fP \fIgi\fP \fIspec-id\fP"
-Follow IDREF attributes until if finds an element whose GI is \fIgi\fP or
which has a child element with that GI.
-It will apply the transpec \fIspec-id\fP to that element.
-By default, \fBinstant\fP assumes the attributes named \fBLINKEND\fP,
\fBLINKENDS\fP, and \fBIDREF\fP are of type IDREF or IDREFS.
-(This corresponds with the OSF DTDs.)
+Follow IDREF attributes until if finds an element whose GI is \fIgi\fP or
which has a child element with that GI.
+It will apply the transpec \fIspec-id\fP to that element.
+By default, \fBinstant\fP assumes the attributes named \fBLINKEND\fP,
\fBLINKENDS\fP, and \fBIDREF\fP are of type IDREF or IDREFS.
+(This corresponds with the OSF DTDs.)
You can change this by setting the variable \fBlink_atts\fP to a
space-separated list of attribute names.
.IP "\fB_eachatt\fP \fIatt\fP \fIspec-id\fP [\fIspec-id2\fP]"
The transpec named by \fIspec-id\fR is invoked once per each word
@@ -362,124 +372,128 @@ If \fIspec-id2\fP is specified, it will
in the content and \fIspec-id2\fP for the others.
.IP "\fB_env\fP \fIenv-variable\fP"
Print the value of the environment variable \fIenv-variable\fP to the output
stream.
-.IP "\fB_filename\fP"
-Print the filename of the notation associated with this element, if any.
-This is used to get the filename of an external notation entity reference.
+.IP \fB_filename\fP
+Print the filename of the notation associated with this element, if any.
+This is used to get the filename of an external notation entity reference.
For example, to print the filename in the latex macro from the epsf macro
package, use \f(CW\e\eepsfboxi{${_filename}}\fP.
.IP "\fB_find\fP [\fBtop\fP] \fIrelationship\fP \fIargs ...\fP \fIspec-id\fP"
-Descend the document hierarchy finding elements that match one of several
criteria.
-When one is found, the action specified by \fIspec-id\fP is performed.
-If \fBtop\fP is specified, the search starts at the top of the document
hierarchy, rather than at the current element.
-The possible values for \fIrelationship\fP are \fBgi\fP, \fBgi-parent\fP,
\fBparent\fP, and \fBattr\fP,
-and take different arguments.
-Explanations may be best done by example:
-\fB_find gi CHAPTER 123\fP means to find elements whose GI is CHAPTER, and
perform action 123;
-\fB_find gi-parent TITLE CHAPTER 124\fP means to find elements whose GI is
TITLE and whose parent is CHAPTER, and perform action 124;
-\fB_find parent BODY 125\fP means to find elements whose parent's GI is BODY,
and perform action 125;
+Descend the document hierarchy finding elements that match one of several
criteria.
+When one is found, the action specified by \fIspec-id\fP is performed.
+If \fBtop\fP is specified, the search starts at the top of the document
hierarchy, rather than at the current element.
+The possible values for \fIrelationship\fP are \fBgi\fP, \fBgi-parent\fP,
\fBparent\fP, and \fBattr\fP,
+and take different arguments.
+Explanations may be best done by example:
+\fB_find gi CHAPTER 123\fP means to find elements whose GI is CHAPTER, and
perform action 123;
+\fB_find gi-parent TITLE CHAPTER 124\fP means to find elements whose GI is
TITLE and whose parent is CHAPTER, and perform action 124;
+\fB_find parent BODY 125\fP means to find elements whose parent's GI is BODY,
and perform action 125;
\fB_find attr TYPE UGLY 125\fP means to find elements whose attribute named
TYPE is set to UGLY, and perform action 126.
.IP "\fB_followlink\fP [\fIattname\fP] \fIspec-id\fP"
-When processing an element, \fBinstant\fP will follow the IDREF attributes
until an element with no IDREF attributes is found.
-It will then apply the transpec specified by \fIspec-id\fP to that element.
-If specified, it will follow the link pointed to by \fIattname\fP.
-By default, \fBinstant\fP assumes the attributes named \fBLINKEND\fP and
\fBLINKENDS\fP are if type IDREF or IDREFS.
+When processing an element, \fBinstant\fP will follow the IDREF attributes
until an element with no IDREF attributes is found.
+It will then apply the transpec specified by \fIspec-id\fP to that element.
+If specified, it will follow the link pointed to by \fIattname\fP.
+By default, \fBinstant\fP assumes the attributes named \fBLINKEND\fP and
\fBLINKENDS\fP are if type IDREF or IDREFS.
You can change this by setting the variable \fBlink_atts\fP to a
space-separated list of attribute names.
.IP "\fB_followrel\fP \fIrelationship\fP \fIgi\fP \fIspec-id\fP"
-If the \fIgi\fP has the specified \fIrelationship\fP to the current element,
-perform the action specified by \fIspec-id\fP on the related element.
+If the \fIgi\fP has the specified \fIrelationship\fP to the current element,
+perform the action specified by \fIspec-id\fP on the related element.
See the discussion of the criteria field \fBRelation\fP for acceptable
relationship names.
.IP "\fB_gi\fP [\fBM|L|U\fP]"
-Print the name of the current GI to the output stream.
+Print the name of the current GI to the output stream.
If specified, \fBM\fP, \fBL\fP, or \fBU\fP will ensure the GI name is printed
in mixed, lower, or upper case, respectively.
.IP "\fB_id\fP \fIid\fP [\fIspec-id\fP]"
Find the element with \fIid\fP and use \fIspec-id\fP, if set. If not set, use
the spec for that element's context.
.IP "\fB_include\fP \fIfilename\fP"
Insert the file \fIfilename\fP into the output stream.
.IP "\fB_infile\fP [\fBline\fP]"
-Print the name of the sgml instance file to the output stream. If \fBline\fP
is specified, also print the line number.
+Print the name of the sgml instance file to the output stream. If \fBline\fP
is specified, also print the line number.
This depends on \fBonsgmls\fP being called with the \fB\-l\fP option.
.IP "\fB_insertnode\fP \fBS\fP|\fBE\fP \fIspec-id\fP"
-Do \fIspec-id\fP when the current element is traversed at a later pass.
+Do \fIspec-id\fP when the current element is traversed at a later pass.
This can be considered inserting a node, without content, into the hierarchy.
-This is only useful if done to elements \fIbefore\fP they are processed.
-Typically \fB_chasetogi\fP or \fB_followlink\fP is specified early in an
instance's processing,
-so that when the elements found by one of these actions are processed in their
turn, the added actions are performed.
+This is only useful if done to elements \fIbefore\fP they are processed.
+Typically \fB_chasetogi\fP or \fB_followlink\fP is specified early in an
instance's processing,
+so that when the elements found by one of these actions are processed in their
turn, the added actions are performed.
\fB_insertnode\fP would be specified as the action of a \fIspec-id\fP pointed
to in a \fB_chasetogi\fP or \fB_followlink\fP usage.
-.IP "\fB_location\fP"
-The location of the current element is printed to the output stream in several
ways: the path to the element (see \fB_path\fP),
+.IP \fB_location\fP
+The location of the current element is printed to the output stream in several
ways: the path to the element (see \fB_path\fP),
a position hint, which is the nearest title, the line number, if the ESIS
(output from \fBonsgmls\fP) contains line numbers,
-and the ID of the element, if it has one.
+and the ID of the element, if it has one.
This is especially useful when using the \fBMessage\fP action to validate an
instance.
.IP "\fB_namelist\fP \fIspec-id\fP [\fIspec-id2\fP]"
-This assumes that the content of the current element is a namelist (a list of
element IDs),
-and applies the action based on \fIspec-id\fP for each element pointed to.
+This assumes that the content of the current element is a namelist (a list of
element IDs),
+and applies the action based on \fIspec-id\fP for each element pointed to.
If \fIspec-id2\fP is specified, it will use \fIspec-id\fP for the first ID in
the namelist and \fIspec-id2\fP for the others.
.IP "\fB_nchild\fP [\fIgi\fP]"
-Print the number of child elements of the element to the output stream.
+Print the number of child elements of the element to the output stream.
If \fIgi\fP is specified, print the number of child element with that name.
.IP "\fB_osftable\fP \fBtex\fP|\fBtbl\fP|\fBcheck\fP [\fIflag\fP]"
-Print table markup into the output stream. The format depends on whether
\fBtex\fP or \fBtbl\fP is specified.
-The \fIflag\fP may be one of \fBcellstart\fP, \fBcellend\fP, \fBrowstart\fP,
\fBrowend\fP, \fBtop\fP, or \fBbottom\fP.
-The value determines what markup or text will be generated.
+Print table markup into the output stream. The format depends on whether
\fBtex\fP or \fBtbl\fP is specified.
+The \fIflag\fP may be one of \fBcellstart\fP, \fBcellend\fP, \fBrowstart\fP,
\fBrowend\fP, \fBtop\fP, or \fBbottom\fP.
+The value determines what markup or text will be generated.
If \fBcellstart\fP is specified, the correct markup for the beginning of a
cell is output.
-If \fBtop\fP, \fBbottom\fP, or \fBrowend\fP are specified,
-the correct markup for the end of the appropriate position is printed to the
output stream.
+If \fBtop\fP, \fBbottom\fP, or \fBrowend\fP are specified,
+the correct markup for the end of the appropriate position is printed to the
output stream.
If \fBcheck\fP is specified, the attributes and child elements are checked for
errors and consistency.
-.IP "\fB_path\fP"
-Print the path to current GI to the output stream. A path is each element,
going down the tree from the topmost element.
-A number in parentheses after each element name shows which child element the
next one is in the order of children for that element.
-Ordering starts at 0.
-For example: \f(CWOSF-BOOK(3) BODY(0) CHAPTER(4) SECTION\fP.
-This says the path is \fB<OSF-BOOK>\fP's third child, \fB<BODY>\fP's zeroth,
+.IP \fB_path\fP
+Print the path to current GI to the output stream. A path is each element,
going down the tree from the topmost element.
+A number in parentheses after each element name shows which child element the
next one is in the order of children for that element.
+Ordering starts at 0.
+For example: \f(CWOSF-BOOK(3) BODY(0) CHAPTER(4) SECTION\fP.
+This says the path is \fB<OSF-BOOK>\fP's third child, \fB<BODY>\fP's zeroth,
and \fB<CHAPTER>\fP's fourth, which is named \fB<SECTION>\fP.
.IP "\fB_pattr\fP \fIname\fP"
Print the value of parent's attribute whose name is \fIname\fP to the output
stream.
.IP "\fB_pfind\fP \fIrel\fP \fIgi\fP \fIspec-id\fP"
This is exactly the same as \fB_find\fP except that the search starts at the
current element's parent.
.IP "\fB_relation\fP \fIrelationship\fP \fIgi\fP \fIspec-id\fP
[\fIspec-id2\fP]"
-If the \fIgi\fP has the specified \fIrelationship\fP to the current element,
-perform the action specified by \fIspec-id\fP on the current element.
-If the relationship test fails and \fIspec-id2\fP is specified, perform that
action.
+If the \fIgi\fP has the specified \fIrelationship\fP to the current element,
+perform the action specified by \fIspec-id\fP on the current element.
+If the relationship test fails and \fIspec-id2\fP is specified, perform that
action.
See the discussion of the criteria field \fBRelation\fP for acceptable
relationship names.
.IP "\fB_set\fP \fIvarname\fP \fIvalue\fP"
Set the value of the variable \fIvarname\fP to \fIvalue\fP.
.IP "\fB_isset\fP \fIvarname\fP [\fIvalue\fP] \fIspec-id\fP"
-If the value of the variable \fIvarname\fP is set to \fIvalue\fP, then perform
action referred to by \fIspec-id\fP.
+If the value of the variable \fIvarname\fP is set to \fIvalue\fP, then perform
action referred to by \fIspec-id\fP.
If \fIvalue\fP is not specified, action will be performed if \fIvarname\fP is
set to any value.
.IP "\fB_!\fP \fIcommand\fP"
Run the command \fIcommand\fP, directing its standard output into the output
stream.
'br\" labeled list end
.SS "Immediate Variables"
-.PP
\fIImmediate variables\fR are like special variables, except that they
are expanded when the transpec is originally processed (special
variables are processed later, near when the final output is being generated).
The general syntax of immediate variables is \fB${+\fIimmediate_variable\
...\fB}\fR.
.PP
There is currently only one immediate variable defined:
-.IP "\fB+content\fP"
+.IP \fB+content\fP
This special variable is replaced by the data content of the current element.
-.SH "Examples"
-.PP
-The following will output the given string for elements whose generic
identifier is \fBP\fP (for paragraph).
-At the start of processing this element, the program ensures that the output
starts on a new line,
-the \fBtroff\fP macro \fB<.P>\fP is output, then a newline.
+.SH Examples
+The following will output the given string for elements whose generic
identifier is \fBP\fP (for paragraph).
+At the start of processing this element, the program ensures that the output
starts on a new line,
+the \fBtroff\fP macro \fB<.P>\fP is output, then a newline.
At the end of this element processing, the program ensures that the output
starts on a new line.
-.DS
+.PP
.nf
-.ft CW
+.if t \{\
+. ie \n(.g .ft CR
+. el .ft CW
+.\}
GI: P
StartText: ^.P^
EndText: ^
-
.ft R
.fi
-.DE
+.
.PP
-The following will output the given string for elements whose generic
identifier is \fBCMD-ARGUMENT\fP and which have an
+The following will output the given string for elements whose generic
identifier is \fBCMD-ARGUMENT\fP and which have an
attribute \fBPRESENCE\fP set to the value \fBOPTIONAL\fP.
-.DS
+.PP
.nf
-.ft CW
+.if t \{\
+. ie \n(.g .ft CR
+. el .ft CW
+.\}
GI: CMD-ARGUMENT
AttValue: PRESENCE OPTIONAL
StartText: $\e\e[
@@ -487,23 +501,25 @@ EndText: $\e\e]
-
.ft R
.fi
-.DE
.PP
-The following prints the section number, title, and page number of the target
of a cross reference.
-Assume the cross reference points to a section element, which contains a title
element.
-The criteria for this spec to match is that the attribute \fBOSFROLE\fP is set
to the value \fBgetfull\fP.
-The action is to replace the content of the \fB<XREF>\fP element with the
given string.
-When processing the string, \fBinstant\fP will follow the IDREF attributes of
\fB<XREF>\fP
-until an element with no IDREF attributes is found. It will then apply the
transpec numbered \fB87\fP to that element,
-which will print the name of the GI in mixed case into the output stream.
-It will then print the LaTeX reference instruction with the value of the
\fBLINKEND\fP attribute as an argument.
-(This will become the section number after processing by LaTeX.)
-It will then follow IDREFs until if finds an element whose GI is \fBTITLE\fP
or which has a child element with that GI.
-It will apply the transpec numbered \fB1\fP to that element, which copies the
title into the output stream where the cross reference occurs.
+The following prints the section number, title, and page number of the target
of a cross reference.
+Assume the cross reference points to a section element, which contains a title
element.
+The criteria for this spec to match is that the attribute \fBOSFROLE\fP is set
to the value \fBgetfull\fP.
+The action is to replace the content of the \fB<XREF>\fP element with the
given string.
+When processing the string, \fBinstant\fP will follow the IDREF attributes of
\fB<XREF>\fP
+until an element with no IDREF attributes is found. It will then apply the
transpec numbered \fB87\fP to that element,
+which will print the name of the GI in mixed case into the output stream.
+It will then print the LaTeX reference instruction with the value of the
\fBLINKEND\fP attribute as an argument.
+(This will become the section number after processing by LaTeX.)
+It will then follow IDREFs until if finds an element whose GI is \fBTITLE\fP
or which has a child element with that GI.
+It will apply the transpec numbered \fB1\fP to that element, which copies the
title into the output stream where the cross reference occurs.
Finally, it will print the word \fBpage\fP followed by the LaTeX instruction
to obtain the page number of a reference.
-.DS
+.PP
.nf
-.ft CW
+.if t \{\
+. ie \n(.g .ft CR
+. el .ft CW
+.\}
GI: XREF
AttValue: OSFROLE getfull
Replace: ${_followlink 87} \e\eref{${LINKEND}},\es
@@ -520,7 +536,6 @@ SpecID: 1
-
.ft R
.fi
-.DE
+.
.SH "Related Information"
-.PP
\fBinstant\fP(1), \fBonsgmls\fP(1), \fBegrep\fP(1).
Any program (person), that produces man pages, should check the output
for defects by using (both groff and nroff)
[gn]roff -mandoc -t -ww -b -z -K utf8 <man page>
To find trailing space use
grep -n -e ' $' -e ' \\f.$' -e ' \\"' <man page>
The same goes for man pages that are used as an input.
-.-
For a style guide use
mandoc -T lint
-.-
For general input conventions consult the man page "nroff(7)" (item
"Input conventions") or the Texinfo manual about the same item.
-.-
Any "autogenerator" should check its products with the above mentioned
'groff', 'mandoc', and additionally with 'nroff ...'.
It should also check its input files for too long (> 80) lines.
This is just a simple quality control measure.
The "autogenerator" may have to be corrected to get a better man page,
the source file may, and any additional file may.
-.-
Common defects:
Not removing trailing spaces (in in- and output).
The reason for these trailing spaces should be found and eliminated.
"git" has a "tool" to point out whitespace,
see for example "git-apply(1)" and git-config(1)")
-.-
Not beginning each input sentence on a new line.
Line length and patch size should thus be reduced when that has been fixed.
The script "reportbug" uses 'quoted-printable' encoding when a line is
longer than 1024 characters in an 'ascii' file.
See man-pages(7), item "semantic newline".
-.-
The difference between the formatted output of the original
and patched file can be seen with:
nroff -mandoc <file1> > <out1>
nroff -mandoc <file2> > <out2>
diff -d -u <out1> <out2>
and for groff, using
\"printf '%s\n%s\n' '.kern 0' '.ss 12 0' | groff -mandoc -Z - \"
instead of 'nroff -mandoc'
Add the option '-t', if the file contains a table.
Read the output from 'diff -d -u ...' with 'less -R' or similar.
-.-.
If 'man' (man-db) is used to check the manual for warnings,
the following must be set:
The option "-warnings=w"
The environmental variable:
export MAN_KEEP_STDERR=yes (or any non-empty value)
or
(produce only warnings):
export MANROFFOPT="-ww -b -z"
export MAN_KEEP_STDERR=yes (or any non-empty value)
-.-
