bracx.1

.TH BRACX 1 "July 22, 2015"
.DD July 22, 2015

.SH NAME
bracx - Cross reference Bracy source files

.SH SYNOPSIS
.B bracx\c
 [\c
.B -bglpv\c
] [\c
.BI -c \ count\c
] [\c
.BI -n \ count\c
] [\c
.I file\c
\&...]

.SH DESCRIPTION
.B Bracx
reads the Bracy source files (with the suffix
.B .by\c
) whose pathnames appear on the command line, and writes to stdout a cross
reference table that describes the labels in those files.

.PP
There are two kinds of labels.
An
.I internal label
appears as the first word of a
.I goto
or
.I label
scope.
It begins with a letter, followed by zero or more letters and digits.
An
.I external label
appears as the first word of a
.I goto
scope.
It contains at least one character that is not a letter or a digit.
Styles (such as italic, boldface, etc.) of the characters in a label are
ignored.

.PP
Each label in the cross reference table is prefixed with G, L, or B.
G means that the label appears only in
.I goto
scopes.
L means that the label appears only in
.I label
scopes.
B means that the label appears in both
.I goto
and
.I label
scopes.

.PP
Following each label is a series of one or more line numbers.
Each line number is also prefixed by G, L, or B.
G means the label appears in a
.I goto
scope on the line with that number.
L means it appears in a
.I label
scope on that line, and B means it appears in both scopes on that line.
(It's probably not useful to have a label in both scopes on the same line, but
it's still possible.)

.PP
The following options are recognized.
Options must precede pathnames on the command line.
If an option doesn't appear on the command line, then its default takes effect.
If no pathnames appear on the command line, then
.B bracx
does nothing (with one exception, noted below).

.TP
.BI -b
Both.
In the cross reference table, include labels that appear in both
.I goto
and
.I label
scopes.
If some combination of the options
.B -b\c
\&,
.B -g\c
\&,
or
.B -l
appear on the command line, then the table includes only the specified types
of labels.
If none of these options appear, then the default is to include all labels.

.TP
.BI -e
External.
Show both internal and external labels in the cross reference table.
The default is to show only internal labels.

.TP
.BI -c \ count
Characters.
In the cross reference table, print the first
.I count
Unicode characters of each label.
Labels with fewer characters are padded on the right with blanks.
The value of
.I count
must be an integer greater than or equal to 1.
The default is 21 characters, which is consistent with displaying the table
using 79-character lines.

.TP
.BI -g
Goto.
In the cross reference table, include labels that appear in
.I goto
scopes.
If some combination of the options
.B -b\c
\&,
.B -g\c
\&,
or
.B -l
appear on the command line, then the table includes only the specified types
of labels.
If none of these options appear, then the default is to include all labels.

.TP
.BI -l
(Ell.) Label.
In the cross reference table, include labels that appear in
.I label
scopes.
If some combination of the options
.B -b\c
\&,
.B -g\c
\&,
or
.B -l
appear on the command line, then the table includes only the specified types
of labels.
If none of these options appear, then the default is to include all labels.

.TP
.BI -n \ count
Numbers.
In the cross reference table, print
.I count
line numbers per line.
The value of
.I count
must be an integer greater than or equal to 1.
The default is 8, which is consistent with displaying the table using
79-character lines.

.TP
.BI -p
Print.
Print the Bracy source files to stdout before printing the cross reference
table.
Source files are separated from each other, and from the table, by form feeds
(U+000C).
Each line in the source files is prefixed by a line number: the same line
numbers that appear in the cross reference table.
The default is not to print the source files, only the table.

.TP
.BI -v
Version.
Print
.B bracx\c
\&'s version number and other identifying information on stdout, then halt.
This is the exception noted above: it works even if no pathnames appear on the
command line.
The default is not to print version information.

.PP
The command "\c
.B bracx -egl \c
.I file\c
\&"
may be helpful for finding errors.
It prints the line numbers of external labels in
.I goto
scopes, internal labels in
.I goto
scopes but not in
.I label
scopes, and internal labels in
.I label
scopes but not in
.I goto
scopes.

.SH COPYING
Copyright (C) 2015 James B. Moen.
Permission is granted to copy, distribute, and/or modify this document under
the terms of the GNU Free Documentation License, Version 1.3 or any later
version published by the Free Software Foundation; with no Invariant
Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license may be obtained at <http://fsf.org/>.

.SH VERSION
Version 0.4.

.SH REFERENCES
James B. Moen.
"The Bracy Manual."
Unpublished technical report.
2014.

.SH AUTHOR
James B. Moen

.SH SEE ALSO
.B ascii\c
(7),
.B bracy\c
(1),
.B unicode\c
(7).