.ig

fdl-typesetting.ms

Description of the procedure used for typesetting the text
of the GNU Free Documentation License.


$Id: fdl-typesetting.ms,v 0406effd886a 2026/03/15 22:17:53 keith $

Copyright (C) 2026, Free Software Foundation, Inc.
Written by Keith Marshall (keith.d.marshall@ntlworld.com)


This file is part of groff-pdfmark.

groff-pdfmark is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by the
Free Software Foundation, either version 3 of the License, or (at your
option) any later version.

groff-pdfmark is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
for more details.

You should have received a copy of the GNU General Public License along
with this program.  If not, see <http://www.gnu.org/licenses/>.

..
.\" Define some special characters, which may be used to improve
.\" the appearance of code samples, when set in a constant-width
.\" text font.
.\"
.char \[thinsp]    \FH\^\FC
.char \[operator^] \s'-2.3z'\v'-0.25v'\(AN\v'+0.23v'\s'+2.5z'
.char \[nbsp]      \FH\|\|\FC
.
.XH-APPENDIX-NH 1 fdl-constraints "License Typesetting Constraints"
.LP
The \*[FDL-APPENDIX-TITLE] is a legal document,
originally published by
.pdfhref W -D https://www.gnu.org/ -- the Free Software Foundation
in the United States of America.
As such,
it is written in the English language,
conforming to the idiomatic style,
and spelling conventions which prevail throughout the USA,
and its dependencies;
while its presentational style,
and layout may be adjusted,
to match the conventions of the containing document,
any modification of its textual content,
and paragraph structure,
is strictly prohibited.
.
.LP
Notice that the language of
.EM this
containing document is also English,
but its idiomatic and spelling conventions
are those which are prescribed by
.pdfhref W \#
 -D https://en.wikipedia.org/wiki/Oxford_English_Dictionary -A , -- \#
 the Oxford English Dictionary
and generally adopted throughout the English speaking world,
where the dominant influence is that of the British Commonwealth;
these conventions,
and in particular those related to spelling,
often exhibit differences\*[em]frequently significant\*[em]from
the conventions which prevail in the USA.
.
However,
in the spirit of conformity with the foregoing constraints,
the idiomatic and spelling conventions of
.pdfhref L -D \*[FDL-APPENDIX-LINK] -- the \*[FDL-APPENDIX-TITLE]
have been preserved,
verbatim,
not only throughout
.pdfhref L -D \*[FDL-APPENDIX-LINK] -A \Z','\^\** -- \#
 its encapsulating appendix
.FS
One minor presentational departure\*[em]which could potentially
be misinterpreted as a content change\*[em]may be observed:
each section number,
as it appears within its respective numbered section heading,
has been qualified by a prefix,
representing the encapsulating appendix number;
thus,
a verbatim representation of each original numbered heading
may be reproduced,
by the simple expedient of removing this appendix number prefix.
.FE
but also within all references thereto.
.
.
.XH-APPENDIX-NH 1 fdl-source-selection \#
 "Choosing an Appropriate License Document Source Format"
.LP
The \*[FDL-APPENDIX-TITLE],
.pdfhref W -D https://www.gnu.org/licenses/#FDL -A , \#
 as published by the Free Software Foundation
is available in several distinct document type formats;
unfortunately,
none of these is immediately suitable as input for
.EM direct
processing by
.CW groff ,
(or by
.CW pdfroff ),
irrespective of any particular choice
of primary typesetting macro package.
Thus,
in order to include the \*[FDL-APPENDIX-TITLE]
.pdfhref L -D \*[FDL-APPENDIX-LINK] -A , -- \#
 as Appendix \*[FDL-APPENDIX-NUMBER] of this publication
it is necessary to choose one of the existing,
published forms of the \*[FDL-APPENDIX-TITLE] document,
and adapt it for formatting by
.CW groff ,
while honouring the requirement that its text remains unchanged;
this entails removal of any existing presentational \%mark\[hy]up code,
and insertion of appropriate
.CW groff
\%mark\(hyup code,
while preserving
.EM all
existing document text,
.EM exactly
as it is.
.
.LP
Choosing from the collection
of various \*[FDL-APPENDIX-TITLE] document formats,
which are available from
.pdfhref W -D https://www.gnu.org/licenses/#FDL -A , \#
 the Free Software Foundation's \%web\[hy]site
the most likely candidates for adaptation to formatting by
.CW groff
would appear to be either the plain text variant,
.CW fdl-1.3.txt \(rq, \%\(lq
or the Texinfo variant,
.CW fdl-1.3.texi \(rq. \%\(lq
.
Of these two,
the Texinfo variant includes existing formatting \%mark\[hy]up,
which
.EM could ,
potentially,
be converted\*[em]although perhaps not so readily
by use of an automated procedure\*[em]to
.CW groff
\%mark\[hy]up,
whereas the plain text variant includes no such \%mark\[hy]up;
however,
structural analysis of the plain text document
.EM does
suggest that automated insertion of suitable
.CW groff
\%mark\[hy]up may be practicable.
.
Thus,
after consideration of the properties of these two original documents,
the plain text variant,
.CW fdl-1.3.txt \(rq, \%\(lq
has been adopted as the original source for
the representation of the \*[FDL-APPENDIX-TITLE],
.pdfhref L -D \*[FDL-APPENDIX-LINK] -A . -- \#
 as it appears within this publication
.
.
.XH-APPENDIX-NH 1 fdl-markup "Marking Up the Plain Text Document Source"
.LP
An unmodified copy of the file,
.CW fdl-1.3.txt \(rq, \%\(lq
as downloaded from
.pdfhref W -A , https://www.gnu.org/licenses/fdl-1.3.txt
has been imported into the source tree for this publication,
under the alternative name of
.CW fdl/fdl-v1.3.txt \(rq. \%\(lq
.
While formatting the encapsulating document,
this file is processed as directed by the
.CW fdl/Makefile.sub \(rq \%\(lq
specification,
merging it with the
.CW fdl/fdl-v1.3.ms.in \(rq \%\(lq
template,
and adding appropriate formatting macro call \%mark\[hy]up,
as may be required,
to produce the
.CW fdl-v1.3.ms \(rq \%\(lq
intermediate input file;
this is then interpolated into
the input stream for the encapsulating document,
to produce the formatted content of
.pdfhref L -D \*[FDL-APPENDIX-LINK] -A , -- \#
 the \*[FDL-APPENDIX-TITLE] appendix
as it appears within the finished publication.
.
.LP
Processing of the
.CW fdl/fdl-v1.3.ms.in \(rq \%\(lq
and
.CW fdl/fdl-v1.3.txt \(rq \%\(lq
files,
in this order,
is performed by an
.CW awk
script,
(which has been encoded as an embedded script,
within
.CW fdl/Makefile.sub \(rq). \%\(lq
This script begins by initializing a pair of internal tags:
.DS I
.fam C
.sp \n[PD]u-\n[DD]u
BEGIN { bl_tag = qs_tag = "BL"; }
.sp \n[PD]u-\n[DD]u
.DE
This initialization is followed by the statement:
.DS I
.fam C
.sp \n[PD]u-\n[DD]u
FILENAME \(ap /\.in$/{ print; next; }
.sp \n[PD]u-\n[DD]u
.DE
which causes the
.CW fdl/fdl-v1.3.ms.in \(rq \%\(lq
file\*[em]and indeed,
any other input file with a
.CW .in \(rq \(lq
final extension,
which may have been specified\*[em]to be copied in its entirety,
line by line,
to the
.CW fdl-v1.3.ms \(rq \%\(lq
intermediate input file,
.EM without
any further processing by the script;
thus,
since
.CW fdl/fdl-v1.3.ms.in \(rq \%\(lq
is the first input file to be processed,
a verbatim copy of its content,
which defines a collection of
.CW \%groff(7)
macros,
as specified in
.XR-NO-PREFIX fdl-macros ,
will be propagated to the beginning of the resulting
.CW fdl-v1.3.ms \(rq \%\(lq
intermediate input file.
.
.LP
Having provided this mechanism
for verbatim copying of any specified
.CW *.in \(rq \%\(lq
input files,
the remainder of the script handles the transcription of the
.CW fdl/fdl-v1.3.txt \(rq \%\(lq
input file,
inserting formatting \%mark\[hy]up,
based on the macros which are defined in
.CW fdl/fdl-v1.3.ms.in \(rq, \%\(lq
in the process.
.
The first step which is performed,
in this stage of the transcription process,
is:
.DS I
.fam C
.sp \n[PD]u-\n[DD]u
/\[thinsp]\[operator^][ \(rst]*$/{ bl_count += 1; next; }
.sp \n[PD]u-\n[DD]u
.DE
which filters out entirely blank input lines,
while accumulating a tally\**
.FS
Note that the
.CW bl_count
variable,
in which this tally is accumulated,
is not
.EM explicitly
initialized at the start of the script;
rather,
it
.CW is
explicitly (re)set,
to zero,
during processing of any \%non\[hy]blank line,
while relying on
.CW awk 's
.EM implicit
initialization of previously unreferenced variables,
to zero,
in the event that any blank line is processed,
.EM before
any such reset is actioned.
.FE
of such lines
in any one contiguous group.
.
.LP
Each \%non\[hy]blank input line\*[em]i.e.\&\~each of those
which passes through the preceding blank line filter\*[em]is classified,
on the basis of its content,
and assigned to one of the following context groups:
.QS
.sp -\n[PD]u
.IP \(bu
Indented text,
identified by matching the beginning
of the entire input line to the regular expression:
.DS I
.fam C
.sp \n[PD]u-\n[DD]u
/\[thinsp]\[operator^] /
.sp \n[PD]u-\n[DD]u
.DE
(thus requiring at least one space to precede
the \%non\[hy]blank content of the input line).
.
.IP \(bu
Numbered section headings;
these are identified as any line which matches the regular expression:
.DS I
.fam C
.sp \n[PD]u-\n[DD]u
$1 \(ap /\[thinsp]\[operator^]([0-9]+\(rs.)+$/
.sp \n[PD]u-\n[DD]u
.DE
This expression is evaluated
.EM after
the test for indented content;
thus,
it is subject to the constraint that the input line exhibits
.EM no
leading space,
preceding the section number field,
which
.EM must ,
itself,
be placed at the beginning of the input line.
.
.IP \(bu
List items;
these are identified by an initial line
which matches the regular expression:
.DS I
.fam C
.sp \n[PD]u-\n[DD]u
$1 \(ap /\[thinsp]\[operator^][A-Z]+\(rs.$/
.sp \n[PD]u-\n[DD]u
.DE
(once again,
as in the case of the section number field
of a numbered section heading,
.EM without
.EM any
white space preceding the upper case alphabetic item label field).
.IP
In cases where the content of any single list item
spans more than one input line,
the additional input lines,
within the context of each item,
are identified by matching the indented text expression.
.
.IP \(bu
Addendum headings;
identified by an
.EM exact
match at the beginning of the input line:
.DS I
.fam C
.sp \n[PD]u-\n[DD]u
$1 == "ADDENDUM:"
.sp \n[PD]u-\n[DD]u
.DE
(once again,
with
.EM no
white space preceding the
.CW ADDENDUM: \(rq \%\(lq
label);
such input lines are interpreted similarly to
those which specify numbered section headings,
.EM except
that the associated heading will be
.EM unnumbered ,
with the prefix,
.B \s'-0.5z'ADDENDUM:\s'+0.5z' \(rq \%\(lq
replacing the section number.
.
.IP \(bu
Any \%non\[hy]blank input line,
which does not match any of the preceding classification criteria,
is regarded as a
.EM normal
input line,
and remains otherwise
.EM unclassified .
.QE
.
Regardless of classification,
any \%non\[hy]blank input line which is not,
itself,
classified as a numbered section heading,
and is processed
.EM before
the
.EM first
line to be so classified,
is deemed to represent a constituent of
the license document \%front\[hy]matter;
within this section of the license document,
any occurrence of either of the three character strings,
.CW (C) \(rq, \(lq
or
.CW (c) \(rq, \(lq
is converted,
by application of the
.CW awk
substitution:\^\**
.FS
It may be noted that identification
of license document \%front\[hy]matter context is predicated
on the truth of the condition:
.DS I 8n
.fam C
.sp -\n[PD]u
qs_tag == "BL"
.sp -\n[DD]u
.DE
.IP \& 5n
The state of this condition is
.EM explicitly
made
.CW true ,
during
.CW awk
script initialization,
but it becomes
.CW false ,
when the first\*[em]and indeed,
any subsequent\*[em]input line is classified as
a numbered section heading;
thus,
the license \%front\[hy]matter is
.EM implicitly
terminated,
on identification of the first numbered section heading
input line.
.FE
.DS I
.fam C
.sp \n[PD]u-\n[DD]u
qs_tag == "BL" { sub( /\(rs([Cc]\(rs)/, "\(rs\(rs(co" ); }
.sp \n[PD]u-\n[DD]u
.DE
to the equivalent typographic copyright symbol,
as represented by
.CW troff 's
.CW \(rs(co \(rq \(lq
special character code.
.
.LP
In addition to the preceding typographic substitution,
which affects
.EM only
the representation of the copyright symbol
in the \%front\[hy]matter section of the license document,
several other typographic substitutions are performed on
.EM every
\%non\[hy]blank input line,
regardless of any pending classification;
first,
the substitution:
.DS I
.fam C
.sp \n[PD]u-\n[DD]u
sub( /[ \(rst]+$/, "" );
.sp \n[PD]u-\n[DD]u
.DE
removes any
.EM insignificant
trailing \%white\[hy]space\*[em]i.e.\&
space and horizontal tab\*[em]characters
from the end of any input line
which exhibits them.
Following this,
the substitution:
.DS I
.fam C
.sp \n[PD]u-\n[DD]u
gsub( /--/, "\(rs\(rs(em" );
.sp \n[PD]u-\n[DD]u
.DE
inserts a typographic \%em\[hy]dash,
in place of any contiguous pair of ASCII hyphen/minus characters,
the substitution sequence:
.DS I
.fam C
.sp \n[PD]u-\n[DD]u
if( gsub( /"[\[operator^]"]*"/, "\(rs\(rs%lq&\(rs\(rs%rq" ) > 0 )
{ gsub( /\(rs\(rs%lq"/, "\(rs\(rs(lq" ); gsub( /"\(rs\(rs%rq/, "\(rs\(rs(rq" );
}
.sp \n[PD]u-\n[DD]u
.DE
inserts a balanced pair of typographic double quotation marks,
around any character sequence within any single input line,
which is enclosed between ASCII double quotation marks,
in place of those ASCII quotation marks,
and a final substitution sequence:
.DS I
.fam C
.sp \n[PD]u-\n[DD]u
if( gsub( /[\[operator^]- ]+-/, "\(rs\(rs%&" ) > 0 )
{ gsub( /-\(rs\(rs%/, "-" );
  while( gsub( /\(rs\(rs%[\[operator^]- ]+-/, "&%!%hy" ) > 0 )
  { gsub( /-%!%hy/, "\(rs\(rs(hy" );
  }
}
.sp \n[PD]u-\n[DD]u
.DE
identifies any hyphenated string,
in which each hyphen is represented by an ASCII hyphen/minus character,
inserts typographic hyphens,
as represented by
.CW troff 's
.CW \(rs(hy \(rq \(lq
special character code,
in place of each corresponding ASCII character,
and prefaces the entire hyphenated string with the
.CW \(rs% \(rq \(lq
control code,
to suppress line breaking of the typeset text,
within any such hypenated string.
.
.LP
Each of these typographic substitutions,
where appropriate,
together with input line classification,
is performed on each input line,
as it is read;
based on classification,
markup to invoke any of the formatting macros,
as documented in
.pdfhref L -D fdl-macros -A , -- the following section
is added,
and the resulting,
marked up input line is copied to the intermediate
.CW troff
input file.
.
.LP
To facilitate the introduction of macro call \%mark\[hy]up,
the
.CW awk
function:
.DS I
.fam C
.sp \n[PD]u-\n[DD]u
function macro( tag ){ return "."TXT2ROFF_PREFIX"-"tag; }
.sp \n[PD]u-\n[DD]u
.DE
is defined.
Typically,
having arranged for the
.CW awk
variable,
.CW TXT2ROFF_PREFIX \(rq, \%\(lq
to represent the string,
.CW \(dqFDL\(dq ,
this function is called,
using a statement of the form:
.DS I
.fam C
.sp \n[PD]u-\n[DD]u
print macro( tag ), <arguments> ...;
.sp \n[PD]u-\n[DD]u
.DE
to insert \%marked\[hy]up content into the
.CW troff
intermediate input file.
.
.LP
One further
.CW awk
function:
.DS I
.fam C
.sp \n[PD]u-\n[DD]u
function bl_insert( tag )
{ if( bl_count > 0 ){ print macro( tag ), bl_count; bl_count = 0; }
}
.sp \n[PD]u-\n[DD]u
.DE
is also defined.
This facilitates \%context\[hy]sensitive interpretation
of the effect of immediately preceding blank lines,
when classifying input lines for \%marking\[hy]up;
it inserts additional \%mark\[hy]up,
appropriate to the identified context,
when a preceding blank line effect is pending,
and clears the pending blank line indicator.
.
With the assistance of this pair of functions,
the \%mark\[hy]up of classified input lines is performed,
in the following order,
by a series of
.CW awk
code sequences;
the first of these adds appropriate \%mark\[hy]up
for lines with explicit indentation:
.DS I
.fam C
.sp \n[PD]u-\n[DD]u
/^ /{ bl_insert( qs_tag );
      ct = length( $0 ); sub( /\[operator^] +/, "" );
      print macro( "TI" ), ct - length( $0 ), $0;
      next;
    }
.sp \n[PD]u-\n[DD]u
.DE
which uses the
.CW FDL-TI \(rq \%\(lq
macro to mark up
.EM all
indented input lines,
noting that immediately preceding blank line interpretation
is predicated on the content of the
.CW bl_tag \(rq \%\(lq
string variable,
in order to differentiate indentation of \%block\[hy]quoted content,
from indented continuation of list items,
and from indentation which is specified to centre content
within the license \%front\[hy]matter.
.
Following this,
numbered section headings are marked up,
by the code:
.DS I
.fam C
.sp \n[PD]u-\n[DD]u
$1 \(ap /\[thinsp]\[operator^]([0-9]+\(rs.)+$/{
      bl_insert( "BL" );
      bl_tag = "LP"; qs_tag = "QS"; print macro( "SH" ), $0;
      next;
}
.sp \n[PD]u-\n[DD]u
.DE
which
.EM always
marks up immediately preceding blank lines using the
.CW FDL-BL \(rq \%\(lq
macro,
while arranging to use the
.CW FDL-LP \(rq \%\(lq
macro in place of blank lines which precede
.EM unclassified
input lines,
and the
.CW FDL-QS \(rq \%\(lq
macro in place of blank lines which precede
indented input lines,
.EM after
the
.EM first
numbered heading has been processed,
and marking up each numbered heading,
itself,
using the
.CW FDL-SH \(rq \%\(lq
macro.
.
Additionally,
the code:
.DS I
.fam C
.sp \n[PD]u-\n[DD]u
$1 == "ADDENDUM:" { bl_insert( "BL" ); print macro( "SH" ), $0; next; }
.sp \n[PD]u-\n[DD]u
.DE
will mark up any addendum heading,
such that it will be formatted similarly to a numbered heading,
substituting the
.B \s'-0.5z'ADDENDUM:\s'+0.5z' \(rq \%\(lq
label in place of a section number.
.
This is then followed,
in turn,
by:
.DS I
.fam C
.sp \n[PD]u-\n[DD]u
$1 \(ap /\[thinsp]\[operator^][A-Z]+\(rs.$/{
      bl_insert( "BL" ); print macro( "IP" ), $0;
      next;
}
.sp \n[PD]u-\n[DD]u
.DE
thus marking up the initial line of any list item,
using the
.CW FDL-IP \(rq \%\(lq
macro,
(assuming that any continuation lines
will be identified as indented lines,
and will be marked up accordingly).
.
.LP
Finally,
the
.CW awk
code:
.DS I
.fam C
.sp \n[PD]u-\n[DD]u
{ bl_insert( bl_tag ); print }
.sp \n[PD]u-\n[DD]u
.DE
which is executed in respect of every
.EM unclassified
input line,
copies all such lines to the
.CW troff
intermediate input file,
.EM without
supplementary \%mark\[hy]up,
while ensuring any such line,
which is immediately preceded by one or more blank input lines,
will be preceded by either a
.CW .FDL-BL\ <n> \(rq \%\(lq
\%mark\[hy]up line,
or a
.CW .FDL-LP\ <n> \(rq \%\(lq
\%mark\[hy]up line,
in the
.CW troff
intermediate input file,
.ne 2v
depending on whether it appears
.EM before ,
or
.EM after
encountering the first numbered section heading,
respectively.
.
.
.ds FDL "\FCFDL\-\\$1\F[]\"
.XH-APPENDIX-NH 1 fdl-macros The \*[FDL-APPENDIX-TITLE] Formatting Macros
.ds FDL-DEFN-SECTION "\*[XH-APPENDIX-SN-NO-DOT]\"
.LP
With the exception of the typographic substitutions\Z','\^\**
.FS
It should be noted that,
while such substitutions
.EM do
change the
.EM physical
content of the input lines,
their effect is restricted to typographic presentational
style\*[em]primarily of
.EM only ; punctuation\*(em
none affect the textual content of the license document.
.FE
the formatting effects of the \%mark\[hy]up,
which is introduced as described in
.pdfhref L -D fdl-markup -A , -- the preceding section
is achieved
.EM entirely
through calls to the various macros which are defined in the
.CW fdl/fdl-v1.3.ms.in \(rq \%\(lq
file.
.
The implementation,
and usage of each of these macros,
together with an explanation of the context in which each is used,
is documented below.
.
.XH-APPENDIX-NH 2 fdl-bl-macro \#
 Marking Redundant Blank Input Lines\*[em]the \*[FDL BL] Macro
.LP
With an effective implementation defined as:
.DS I
.fam C
.sp \n[PD]u-\n[DD]u
\&.de FDL-BL
\&..
.sp \n[PD]u-\n[DD]u
.DE
the
.CW FDL-BL
macro does nothing when called.
It is inserted,
into the
.CW troff
intermediate input file,
in the form:
.DS I
.fam C
.sp \n[PD]u-\n[DD]u
\&.FDL-BL <n>
.sp \n[PD]u-\n[DD]u
.DE
to mark any point at which a contiguous sequence of
.CW <n>
input lines has been discarded,
by the blank line filter,
.EM except \& (
in any context in which the blank lines
serve as a new paragraph marker).
.
Since this macro has no formatting effect,
its principal value is to facilitate reconstruction
of the original input file,
from the content of the generated
.CW troff
intermediate input file;
since it does nothing,
when called,
it is also used internally,
as an alias for other macros,
in any context in which their normal effect
is to be suppressed.
.
.XH-APPENDIX-NH 2 fdl-sh-macro \#
 Introducing Numbered Section Headings\*[em]the \*[FDL SH] \#
 and \*[FDL SM] Macros
.LP
Introduced into the
.CW troff
intermediate input file,
in the form:
.DS I
.fam C
.sp \n[PD]u-\n[DD]u
\&.FDL-SH <input-line-content>
.sp \n[PD]u-\n[DD]u
.DE
when the input line under consideration has been classified as
.EM either
a numbered section heading,
.EM or
an addendum heading,
(either of which will,
typically,
be preceded by one or more blank input lines,
the presence of which will
.EM always
be indicated by the use of
.pdfhref L -D fdl-bl-macro -A ), -- the \*[FDL BL] macro
the implementation of the \*[FDL SH] macro is:
.DS I
.fam C
.sp \n[PD]u-\n[DD]u
\&.de FDL-SH
\&.   FDL-QE
\&.   SH 2
\&.   if dFDL-XH .FDL-XH \(rs\(rs$@
\&.   ds \(rs\(rs$0-1 "\(rs\(rs$1\(rs"
\&.   if \(rsB\(aq\(rs\(rs$1\(aq \(rs{\(rs
\&.      if r XH-APPENDIX-NUMBER .ds \(rs\(rs$0-1 "\(rs\(rsn[XH-APPENDIX-NUMBER].\(rs\(rs$1\(rs"
\&.   \(rs}
\&.   shift
\&.   nop \(rs\(rs*[FDL-SM \(rs\(rs*[\(rs\(rs$0-1] 1] \(rs\(rs$*
\&.   rm \(rs\(rs$0-1
\&..
.sp \n[PD]u-\n[DD]u
.DE
When invoked,
with its argument list representing a verbatim copy
of the input line from whence its use has been advocated,
the \*[FDL SH] macro will first terminate any \%block\[hy]quoted context
which may be active,
(by executing
.pdfhref L -D fdl-blockquote-macros -A ). -- the \*[FDL QE] macro
.
It will then prepare to print a heading,
at a type size corresponding to the containing document's
level two numbered headings,
(reserving level one for the appendix title block),
and,
if the optional,
\%user\[hy]defined \*[FDL XH] hook macro has been provided,
it will be called,
to propagate the heading text to the table of contents,
or to a document outline,
(or to both).
.
.LP
Next,
the the first argument is copied to temporary,
local string storage,
whence it will be interpreted as a heading label,
which will be prefaced by the associated appendix number,
.EM if
it is identified as being numerically valued;
the original specification of this label is then
discarded from the argument list.
.
.LP
.KS
Finally,
the resultant heading is printed,
with the initial label being set at a reduced type size,
by expansion of the variant string macro:
.DS I
.fam C
.sp \n[PD]u-\n[DD]u
\&.ds FDL-SM "\(rss\(aq-\(rs\(rs$2z\(aq\(rs\(rs$1\(rss\(aq+\(rs\(rs$2z\(aq\(rs"
.sp \n[PD]u-\n[DD]u
.DE
and the temporarily stored label is discarded.
.KE
.
.XH-APPENDIX-NH 2 fdl-lp-macro \#
 Marking Paragraph Breaks\*[em]the \*[FDL LP] Macro
.LP
With its implementation defined as:
.DS I
.fam C
.sp \n[PD]u-\n[DD]u
\&.de FDL-LP
\&.   FDL-QE
\&.   LP
\&..
.sp \n[PD]u-\n[DD]u
.DE
the
.CW FDL-LP
macro is inserted into the
.CW troff
intermediate input file,
in the form:
.DS I
.fam C
.sp \n[PD]u-\n[DD]u
\&.FDL-LP <n>
.sp \n[PD]u-\n[DD]u
.DE
to mark any point at which a contiguous sequence of
.CW <n>
input lines has been discarded,
by the blank line filter,
.EM after
the first numbered section heading has been processed,
.EM and
the immediately following input line is
.EM unclassified;
(this represents the context in which
the discarded blank input lines signify a paragraph break,
and thus,
in which the use of
.pdfhref L -D fdl-bl-macro -- the \*[FDL BL] macro
is
.EM not
appropriate).
.
.LP
While the
.CW FDL-LP
macro may be considered as a synonym for
.pdfhref L -D fdl-bl-macro -A , -- the \*[FDL BL] macro
for the purpose of reconstructing the original input file
from the generated
.CW troff
intermediate input file,
(for which purpose the
.CW <n>
argument is significant),
in normal use,
when the
.CW troff
intermediate input file is interpreted,
the
.CW <n>
argument is ignored,
any active \%block\[hy]quoted context is implicitly closed,
(by execution of
.pdfhref L -D fdl-blockquote-macros -A ), -- the \*[FDL QE] macro
and a new paragraph is initiated,
by execution of the
.CW ms
.CW LP
macro.
.
.XH-APPENDIX-NH 2 fdl-ti-macro \#
 Interpreting Input Text Indentation\*[em]the \*[FDL TI] Macro
.LP
Within the
.CW fdl/fdl-v1.3.txt \(rq \%\(lq
input file,
text indentation is indicated by an arbitrary number of spaces,
at the beginning of the indented input line;
within the generated
.CW troff
intermediate input file,
it will be interpreted on a basis which is determined by context:
.sp -\n[PD]u
.QS
.IP \(bu
.EM Before
any numbered section heading has been identified,
the indentation is assumed to introduce centred content,
within the license document's \%front\[hy]matter;
this content,
.EM without
the initial spaces,
will be formatted under the aegis of a
.CW troff
.CW ce
request.
.
.IP \(bu
.EM After
any numbered section heading has been identified,
and when
.EM immediately
preceded by the initial line of an itemized list entry,
(i.e.\& an immediately preceding line which has been marked up
with a call to
.pdfhref L -D fdl-ip-macro -A ), -- the \*[FDL IP] macro
the indentation is interpreted as indicating continuation
of the list item content;
it will be formatted,
(once again,
ignoring
.EM all
initial spaces),
in accordance with the conventions pertaining to indented paragraphs,
as established by calling that macro.
.
.IP \(bu
In any other context,
the indentation will be interpreted as an offset,
which is applied to \%\[lq]block\[hy]quoted\(rq text,
(which,
assuming that its initial input line was preceded by at least
one blank input line,
should have been marked up with a preceding call to
.pdfhref L -D fdl-blockquote-macros -A ); -- the \*[FDL QS] macro
formatting,
(once again,
ignoring all initial spaces),
will be performed in accordance with the conventions
established by calling that macro.
.QE
.
Regardless of which of these contexts may apply,
.EM all
indented input lines,
(after removal of their initial spaces),
are marked up by a macro call of the form:
.DS I
.fam C
.sp \n[PD]u-\n[DD]u
\&.FDL-TI <n> <input-line-content>
.sp \n[PD]u-\n[DD]u
.DE
in which the
.CW <n>
argument represents the number of indenting spaces
which were removed,
while the aggregate of all remaining arguments,
specified in place of
.CW \%<input-line-content> ,
represent the residual content of the input line,
.EM after
removal of the initial spaces.
.
.LP
The implementation of the \*[FDL TI] macro is defined as:
.DS I
.fam C
.sp \n[PD]u-\n[DD]u
\&.de FDL-TI
\&.   shift
\&.   nop \(rs\(rs$*
\&..
.sp \n[PD]u-\n[DD]u
.DE
which,
when invoked,
effectively ignores its
.CW <n>
argument,
and passes the content of the original input line,
excluding any extraneous spaces,
as represented by
.CW \%<input-line-content> ,
to the formatter.
.
.KS
.XH-APPENDIX-NH 2 fdl-ip-macro \#
 Formatting Itemized List Content\*[em]the \*[FDL IP] Macro
.LP
The \*[FDL-APPENDIX-TITLE] includes just one itemized list;
each of its constituent items is labeled with an alphabetically
serialized \%upper\[hy]case letter.
.
.LP
Identified by matching the
.CW awk
regular expression:
.DS I
.fam C
.sp \n[PD]u-\n[DD]u
$1 \(ap /\[thinsp]\[operator^][A-Z]+\(rs.$/
.sp \n[PD]u-\n[DD]u
.DE
the first input line of each constituent items content
is copied to the
.CW troff
intermediate input file,
with the addition of \%mark\[hy]up in the form:
.DS I
.fam C
.sp \n[PD]u-\n[DD]u
\&.FDL-IP <input-line-content>
.sp \n[PD]u-\n[DD]u
.DE
in which the
.CW \%<input-line-content>
argument list represents the entire content of the input line,
.EM including
the initial,
alphabetically serialized,
\%upper\[hy]case item label.
.KE
.LP
The implementation of the \*[FDL IP] macro,
itself,
is defined as:
.DS I
.fam C
.sp \n[PD]u-\n[DD]u
\&.de FDL-IP
\&.   if \(aq\(rs\(rs$1\(aqA.\(aq \(rs{\(rs
\&.      af fdl:item A
\&.      nr fdl:item 0 1
\&.      FDL-QPUSH
\&.   \(rs}
\&.   shift
\&.   IP \(rs\(rs*[FDL-SM \(rs\(rsn+[fdl:item] 1.25]. \(rsw\(aqW.n\(aqu
\&.   nop \(rs\(rs$*
\&..
.sp \n[PD]u-\n[DD]u
.DE
When this is executed,
its first action is to examine its first argument,
which represents the the serialized alphabetic item label,
extracted from the
.CW \%<input-line-content>
argument list.
.
If this is found to be
.EM identically
equivalent to
.CW A. \(rq, \%\(lq
then the associated input line is deemed to represent
the beginning of the content of the first entry
in a new item list;
the internal register,
.CW fdl:item \(rq, \%\(lq
is initialized as an enumeration counter,
with \%upper\[hy]case alphabetic presentation format,
which will be used as the item label for the first,
and all subsequent,
items in the ensuing list.
.
Furthermore,
in addition to initialization of the enumeration counter,
this item list initialization procedure calls the \*[FDL QPUSH] macro,
(which is internally aliased to
.pdfhref L -D fdl-blockquote-macros -A ), -- the \*[FDL QS] macro
thus opening an indented section,
(emulated as a \%block\[hy]quote section),
within which the entire content of the item list will be encapsulated;
(this will be closed
.EM implicitly ,
when the next section heading,
or normally formatted paragraph is encountered).
.
.LP
It may be noted that the preceding initialization is performed
.EM only
when processing the
.EM "first item"
in any item list;
it will be bypassed,
when processing any subsequent item.
.
.LP
Regardless of whether item list initialization is performed,
or bypassed,
execution of the \*[FDL IP] macro concludes
by discarding the representation of the item label,
as propagated from the original input line,
and then invokes the
.CW IP
macro,
from the standard
.CW ms
macro package,
deriving the label from the \%auto\[hy]incrementing
.CW fdl:item \(rq \%\(lq
enumeration counter\Z','\^\**
.FS
The
.CW fdl:item \(rq \%\(lq
enumeration counter is
.EM not
expunged, on completion of any \*[FDL IP] macro call;
it
.EM must
persist,
for use in any subsequent \*[FDL IP] call,
in which initialization is
.EM not
performed.
.FE
(which is set in a reduced type size,
using the same \*[FDL SM] string interpolation macro
as is used by the
.pdfhref L -D fdl-sh-macro -A ), -- the \*[FDL SH] macro
allocating sufficient paragraph indentation
to accommodate the widest possible label,
which is derived from this counter,
and ultimately,
passing the remaining content from the original input line
to the formatter,
as the initial content for the ensuing indented paragraph.
.
.XH-APPENDIX-NH 2 fdl-blockquote-macros \#
 Typesetting Block\(hyQuoted License Text\*[em]the \*[FDL QS] \#
 and \*[FDL QE] Macros
.LP
Any sequence of input lines,
which have been marked up in the form of calls to
.pdfhref L -D fdl-ti-macro -A , -- the \*[FDL TI] macro
and which are
.EM immediately
preceded by one or more blank input lines,
will be classified,
as noted in the preceding discussion of
.pdfhref L -D fdl-ti-macro -A , -- the \*[FDL TI] macro
as \%block\[hy]quoted text;
in this case,
the preceding sequence of blank input lines
will be marked up as a call to the \*[FDL QS] macro,
thus opening a \%block\[hy]quoted document section.
.
This section will,
ultimately,
be closed when the complementary \*[FDL QE] macro is called,
.EM implicitly ,
during the next following execution of either
.pdfhref L -D fdl-sh-macro -A , -- the \*[FDL SH] macro
or the
.pdfhref L -D fdl-lp-macro -A . -- the \*[FDL LP] macro
.
.LP
Internally,
the \*[FDL QS],
and the \*[FDL QE] macros are implemented
by mapping to alternatively named macros,
\*[FDL QPUSH] and \*[FDL QPOP] respectively;
the \*[FDL QS] macro is
.EM persistently
aliased to the \*[FDL QPUSH] macro,
whereas the \*[FDL QE] macro is aliased to the \*[FDL QPOP] macro,
.EM only
when a \%block\[hy]quoted section is open,
and to
.pdfhref L -D fdl-bl-macro -A , -- the \*[FDL BS] macro
otherwise.
.
.LP
The implementation of the \*[FDL QPUSH] macro,
(and thus,
also of the aliased \*[FDL QS] macro),
is defined as:
.DS I
.fam C
.sp \n[PD]u-\n[DD]u
\&.de FDL-QPUSH
\&.   als FDL-QE FDL-QPOP
\&.   QS
\&..
.sp \n[PD]u-\n[DD]u
.DE
while that of the complementary \*[FDL QPOP] macro
(but
.EM not
initially,
as an alias for the \*[FDL QE] macro),
is:
.DS I
.fam C
.sp \n[PD]u-\n[DD]u
\&.de FDL-QPOP
\&.   als FDL-QE FDL-BL
\&.   QE
\&..
.sp \n[PD]u-\n[DD]u
.DE
Initially,
the \*[FDL QE] macro is implemented as
.pdfhref L -D fdl-bl-macro -A ; -- an alias for \*[FDL BL]
thus,
when called implicitly by either
.pdfhref L -D fdl-sh-macro -A , -- the \*[FDL SH] macro
or
.pdfhref L -D fdl-lp-macro -A , -- the \*[FDL LP] macro
and there is no \%block\[hy]quoted section,
which has been opened by a prior invocation of the \*[FDL QS] macro,
the implicit \*[FDL QE] call will exhibit
.pdfhref L -D fdl-bl-macro -A , -- its default \*[FDL BL] personality
with its \%\(lqno\[hy]op\(rq behaviour.
.
.LP
Conversely,
a prior call of the \*[FDL QS] macro will,
through its aliased \*[FDL QPUSH] implementation,
remap \*[FDL QE] to its alternative \*[FDL QPOP] persoality,
and will establish a set of formatting conventions
as prescribed by invocation of the standard
.CW ms
macro package's
.CW QS
macro.
.
This state will persist until
the next subsequent invocation of the \*[FDL QE] macro,
(whether implicit,
or explicit)\Z','\**
.FS
In its present
.CW fdl-v1.3.txt \(rq \%\(lq
incarnation,
the \*[FDL-APPENDIX-TITLE] does not require explict closure
of any \*[FDL QS] \%block\[hy]quoted context,
and the marked up
.CW fdl-v1.3.ms \(rq \%\(lq
intermediate input file never requests it;
for a more robust implementation of the automated mark up procedure,
consider adding an
.DS I 8n
.fam C
.sp -\n[PD]u
END { print ".FDL-QE" }
.sp -\n[DD]u
.DE
.IP \& 5n
statement,
to the current implementation of the
.CW awk
processing script.
.FE
which,
now exhibiting its \*[FDL QPOP] personality,
will remap itself,
so that it reverts to
.pdfhref L -D fdl-bl-macro -A , -- its default \*[FDL BL] personality
(and thus,
to its default \%\[lq]no\[hy]op\(rq behaviour,
for any further subsequent calls which are
.EM not
preceded by another \*[FDL QS] call),
and invokes the standard
.CW ms
macro package's
.CW QE
macro,
to restore the formatting conventions to those
which were in effect
.EM before
the most recently preceding
.CW QS
macro call,
(which is assumed,
nominally,
to have occurred as a result of calling the \*[FDL QS] macro).
.
.XH-APPENDIX-NH 1 fdl-custom-controls \#
 Customizing the \*[FDL-APPENDIX-TITLE] Formatting Process
.LP
The collection of macros,
implemented as described in
.XR-NO-PREFIX fdl-macros ,
provides a sufficient \%mark\[hy]up framework
for typesetting of the license using
.CW groff ;
however,
when incorporated as an appendix,
some customization may be required,
in order to adapt to the formatting conventions
of the containing document.
.
To facilitate this,
the \%mark\[hy]up macro framework provides a pair of hooks,
namely
.CW \%FDL-SETUP ,
and
.CW \%FDL-XH ,
by means of which the default behaviour may be augmented,
by provision of correspondingly named,
\%user\[hy]defined macros.
.
.XH-APPENDIX-NH 2 fdl-setup Initial Customization\*[em]the \*[FDL SETUP] Macro
.LP
Invoked by the
.EM conditional
macro call:
.DS I
.fam C
.sp \n[PD]u-\n[DD]u
\&.if dFDL-SETUP .FDL-SETUP
.sp \n[PD]u-\n[DD]u
.DE
the \%\*[FDL SETUP] macro is invoked,
.EM after
the collection of \%mark\[hy]up macros described in
.pdfhref L -D fdl-macros -- section \*[FDL-DEFN-SECTION]
have been defined,
and
.EM before
proceeding with the formatting of the marked up content of the
.CW fdl/fdl-v1.3.txt \(rq \%\(lq
file,
.EM "only if"
the user has provided a definition of it,
.EM before
the content of the
.CW fdl-v1.3.ms \(rq \%\(lq
intermediate input file is interpreted.
.
.LP
For the purpose of incorporating a copy
of the \*[FDL-APPENDIX-TITLE] into this publication,
customization of the basic
.CW FDL
macros is performed by inclusion of the \%package\[hy]local
.CW fdl-setup.tmac \(rq \%\(lq
macro file;
this defines the \*[FDL SETUP] macro as:
.DS I
.fam C
.sp \n[PD]u-\n[DD]u
\&.de FDL-SETUP
\&.\(rs" Locally initialize txt2roff behaviour, for interpretation
\&.\(rs" of generated mark-up within fdl-v1.3.ms
\&.\(rs"
\&.   ds fdl:replacement.tag START
\&.   FDL-BACKUP-AND-REPLACE FDL-SH FDL-TI
\&.   rm FDL-BACKUP-AND-REPLACE fdl:replacement.tag
\&..
.sp \n[PD]u-\n[DD]u
.DE
.
.KS
Since the \*[FDL SETUP] macro,
itself,
is invoked
.EM without
passing
.EM any
arguments,
the foregoing implementation serves,
primarily,
as a wrapper for the \*[FDL BACKUP-AND-REPLACE] helper macro,
which
.EM does
accept arguments:
.DS I
.fam C
.sp \n[PD]u-\n[DD]u
\&.de FDL-BACKUP-AND-REPLACE
\&.\(rs" Backup, and define temporary overrides for specified macros.
\&.\(rs"
\&.   while \(rs\(rsn(.$ \(rs{\(rs
\&.      rn \(rs\(rs$1 \(rs\(rs$1-BACKUP
\&.      rn \(rs\(rs$1-\(rs\(rs*[fdl:replacement.tag] \(rs\(rs$1
\&.      shift
\&.   \(rs}
\&..
.sp \n[PD]u-\n[DD]u
.DE
.KE
When invoked,
as it is,
with \%\(lq\*[FDL SH]\(rq,
and \%\(lq\*[FDL TI]\(rq as its arguments,
this backs up,
(by renaming the pair as \%\(lq\*[FDL SH-BACKUP]\(rq,
and \%\(lq\*[FDL TI-BACKUP]\(rq,
respectively),
and temporarily replaces their initial implementations,
by substitution of alternatives,
originally named \%\(lq\*[FDL SH-START]\(rq,
and \%\(lq\*[FDL TI-START]\(rq,
respectively.
.
.LP
The combined effect of this pair of temporarily redefined macros,
(which persists
.EM only
until the first instance of
the redefined \%\*[FDL SH] macro is processed),
results in interpretation of any input lines,
which have been marked up with the \%\*[FDL TI] macro,
to be interpreted as specifying the content of a \[lq]title block\(rq,
introducing the content of the \*[FDL-APPENDIX-TITLE] itself;
the redefined \%\*[FDL TI] macro,
which performs this function,
is:
.DS I
.fam C
.sp \n[PD]u-\n[DD]u
\&.de FDL-TI-START
\&.\(rs" Early-use override for FDL-TI; this remains in effect until
\&.\(rs" the first use of (overridden) FDL-SH, taking control of the
\&.\(rs" FDL title block.
\&.\(rs"
\&.   ie !r fdl:title.lines \(rs{\(rs
\&.   \(rs" On first time of use, initialize to accept five lines of
\&.   \(rs" title block, with the first two set at the size of level
\&.   \(rs" two headings, and centred.
\&.   \(rs"
\&.      nr fdl:title.lines 5 1
\&.      SH 2
\&.      ce 2
\&.   \(rs}
\&.   el \(rs{ .ie \(rs\(rsn-[fdl:title.lines]=3 \(rs{\(rs
\&.   \(rs" Set the third and fourth lines at a point size reduced
\&.   \(rs" from normal paragraph text, and still centred.
\&.   \(rs"
\&.      LP
\&.      SM
\&.      vs -3p
\&.      sp 1.5v
\&.      ce 2
\&.   \(rs}
\&.   el .if \(rs\(rsn[fdl:title.lines]=1 \(rs{\(rs
\&.   \(rs" Collect any further title lines into a filled diversion,
\&.   \(rs" to be flushed out, and centred, when FDL-SH is called for
\&.   \(rs" the first time.
\&.   \(rs"
\&.      di fdl:title.block
\&.   \(rs}\(rs}
\&.   \(rs\(rs$0-BACKUP \(rs\(rs$@
\&..
.sp \n[PD]u-\n[DD]u
.DE
Invocation of this redefined \%\*[FDL TI] macro results in up to
.EM four
lines of input text being
.EM immediately
typeset as a centred title,
(with the first
.EM two
lines at an increased type size,
and the following two at reduced size);
any further input lines,
beyond the
.EM fourth ,
are then collected into a diversion,
which will,
ultimately,
be typeset when this specialized interpretation
is terminated.
.
.LP
.KS
Regardless of the ultimate disposition of any input lines,
which are processed while this redefined implementation
of the \%\*[FDL TI] macro remains in effect,
its actual typesetting effect is delegated to
the original \%\*[FDL TI] implementation,
which has been temporarily designated as \%\*[FDL TI-BACKUP].
.KE
.LP
.KS
Cancellation of this modified \%\*[FDL TI] macro behaviour occurs,
eventually,
when
.EM any
instance of the \%\*[FDL SH] macro is encountered,
in
.EM its
modified guise:
.DS I
.fam C
.sp \n[PD]u-\n[DD]u
\&.de FDL-SH-START
\&.\(rs" First-use override for FDL-SH; it completes formatting and
\&.\(rs" output of the title block, cleans up the entire FDL override
\&.\(rs" context, restoring normal behaviour for output of the first
\&.\(rs" section heading, and the remainder of the fdl-v1.3 text.
\&.\(rs"
\&.   if \(aq\(rs\(rsn(.z\(aqfdl:title.block\(aq \(rs{\(rs
\&.      br
\&.      di
\&.      unformat fdl:title.block
\&.      sp 1.5v
\&.      ce 10
\&.      fdl:title.block
\&.      ce 0
\&.   \(rs}
\&.   sp 1i
\&.   FDL-RESTORE \(rs\(rs$0 FDL-TI
\&.   rm FDL-RESTORE fdl:title.block
\&.   rr fdl:title.lines
\&.   \(rs\(rs$0 \(rs\(rs$@
\&..
.sp \n[PD]u-\n[DD]u
.DE
.KE
When this variant of the \%\*[FDL SH] macro is invoked,
its first action is to reprocess,
and typeset,
any residual title block content,
which has been deferred by storing within a local diversion,
created by the preceding variant of the \%\*[FDL TI] macro.
.
It then reverts
.EM both
the \%\*[FDL SH] macro,
and the \%\*[FDL TI] macro,
to their original,
default implementations,
thus restoring their default behaviours,
for any subsequent invocations.
.
Finally,
it cleans up all temporary local storage,
which is associated
.EM exclusively
with its modified initial behaviour,
and then,
it passes its own section heading arguments
to its reinstated original implementation,
for typesetting.
.
.LP
To facilitate reinstatement of the original,
default implementations of the \%\*[FDL SH],
and \%\*[FDL TI] macros,
the modified variant of \%\*[FDL SH] calls a helper macro,
\%\*[FDL RESTORE],
which is implemented as:
.DS I
.fam C
.sp \n[PD]u-\n[DD]u
\&.de FDL-RESTORE
\&.\(rs" Restore original behaviour of overridden macros.
\&.\(rs"
\&.   while \(rs\(rsn(.$ \(rs{\(rs
\&.      rn \(rs\(rs$1-BACKUP \(rs\(rs$1
\&.      shift
\&.   \(rs}
\&..
.sp \n[PD]u-\n[DD]u
.DE
This helper macro is subsequently deleted,
during the \%clean\[hy]up of temporary storage,
by the initially modified variant of the \%\*[FDL SH] macro.
.
.
.XH-APPENDIX-NH 2 fdl-xh Section Header Integration\*[em]the \*[FDL XH] Macro
.LP
The second of the hooks,
which is exposed by the
.CW FDL
macros,
namely the \%\*[FDL XH] macro,
is invoked
.EM exclusively
by the \%\*[FDL SH] macro,
using a
.EM conditional
call of the form:
.DS I
.fam C
.sp \n[PD]u-\n[DD]u
\&.if dFDL-XH .FDL-XH \(rs\(rs$@
.sp \n[PD]u-\n[DD]u
.DE
passing quoted arguments,
which
.EM exactly
reproduce those passed in
the referring \%\*[FDL SH] macro call itself;
the intent is to provide a mechanism for propagation
of the section heading specification,
beyond the immediate internal scope of
this referring \%\*[FDL SH] macro call.
.
.LP
.KS
While the \%\*[FDL XH] macro will be called,
.EM "only if"
the user has actually provided an implementation,
the \%package\[hy]local
.CW fdl-setup.tmac \(rq \%\(lq
macro file,
as used in the production of this publication,
.EM does
provide such an implementation,
which is defined as:
.DS I
.fam C
.sp \n[PD]u-\n[DD]u
\&.de FDL-XH
\&.\(rs" Propagate FDL section headings to the document outline,
\&.\(rs" and to the table of contents.
\&.\(rs"
\&.   ie \(rsB\(aq\(rs\(rs$1\(aq \(rs{\(rs
\&.      pdfhref O 2 \(rs\(rsn[XH-APPENDIX-NUMBER].\(rs\(rs$*
\&.      \(rs\(rs$0-UPDATE-TOC \(rs\(rs$@
\&.   \(rs}
\&.   el \(rs{\(rs
\&.      pdfhref O 2 \(rs\(rs$*
\&.      XH-UPDATE-TOC 3 \(rsh\(aq\(rsw!0.!u\(aq\(rs\(rs$*
\&.   \(rs}
\&..
.sp \n[PD]u-\n[DD]u
.DE
.KE
When called by \%\*[FDL SH],
this \%\*[FDL XH] macro examines its copy of the \%\*[FDL SH] arguments,
in order to discriminate between numbered sections,
and \[lq]addendum\(rq sections;
in the former case,
it adds the appendix number,
(expressed in its designated \%upper\[hy]case alphabetic format),
as a dotted prefix to the assigned section number,
and enters the resultant numbered section heading
into the PDF document outline,
before going on to call a further custom macro,
named \%\*[FDL XH-UPDATE-TOC],
to create a corresponding table of contents entry;
in the latter case,
it simply enters the given section heading,
without change,
into the PDF outline,
and calls the default
.CW \%XH-UPDATE-TOC
macro,
to propagate this to the table of contents.
.
.LP
The implementation of the custom \%\*[FDL XH-UPDATE-TOC] macro,
.\"which may be called by the preceding \%\*[FDL XH] macro,
which is called by the preceding \%\*[FDL XH] macro
when processing numbered section headings,
is defined as:
.DS I
.fam C
.sp \n[PD]u-\n[DD]u
\&.de FDL-XH-UPDATE-TOC
\&.\(rs" Helper for FDL-XH, to propagate table of contents entries,
\&.\(rs" with text alignment for heading levels less than ten, with
\&.\(rs" those for levels of ten or more.
\&.\(rs"
\&.   ie \(rsw\(aq\(rs\(rs$1\(aq<\(rsw\(aq10.\(aq \(rs{\(rs
\&.   \(rs" Heading level is less than ten, so append space equal
\&.   \(rs" to the width of one digit, to achieve alignment, then
\&.   \(rs" recurse to emit the table of contents entry.
\&.   \(rs"
\&.      ds \(rs\(rs$0.$1 "\(rs\(rs$1\(rs0\(rs"
\&.      shift
\&.      \(rs\(rs$0 "\(rs\(rs*[\(rs\(rs$0.$1]" \(rs\(rs$@
\&.      rm \(rs\(rs$0.$1
\&.   \(rs}
\&.   \(rs" When heading level is ten or more, or alignment space
\&.   \(rs" has already been added, emit the entry.
\&.   \(rs"
\&.   el .XH-UPDATE-TOC 2 \(rs\(rsn[XH-APPENDIX-NUMBER].\(rs\(rs$*
\&..
.sp \n[PD]u-\n[DD]u
.DE
The effect of calling this macro
is to adjust the spacing between section numbers
and the following heading text,
when constructing the associated table of contents entries,
to keep the heading text vertically \%left\[hy]aligned,
within the table of contents,
regardless of whether the preceding section number occupies one,
or two digit spaces.
.
.
.KS
.XH-APPENDIX-NH 1 fdl-layout-tweaks \#
 \*[FDL-APPENDIX-TITLE] Finishing Touches
.LP
Although the automated process,
which has been adopted for marking up the
.CW fdl/fdl-v1.3.txt \(rq \%\(lq
file,
such that it is made suitable for formatting with
.CW groff ,
can achieve reasonable results,
it
.EM does
leave some scope for improvement through certain manual adjustments.
In particular:
.sp -\n[PD]u
.QS
.IP \(bu
The automated process makes no attempt
to address the avoidance of widow and orphan lines;
this is best handled by judicious human intervention,
and,
in the case of typesetting for inclusion in this publication,
.CW troff
conditional
.CW .ne\[nbsp]2v \(rq \%\(lq
pagination requests have been manually inserted,
at appropriate points in the generated
.CW fdl-v1.3.ms \(rq \%\(lq
intermediate input file,
.EM after
a critical inspection of the initial typeset result.
.
.IP \(bu
The HTTP references,
which may be found within the
.CW fdl/fdl-v1.3.txt \(rq \%\(lq
file,
are
.EM not
automatically converted to live URL references.
Adaptation of the automation script,
to achieve this objective,
seemed to pose rather more of a challenge than the simple expedient
of manually adding the necessary \%mark\[hy]up,
.EM after
generation of the
.CW fdl-v1.3.ms \(rq \%\(lq
intermediate input file;
thus,
for the purposes of this publication,
suitable
.CW .pdfhref\[nbsp]\[thinsp]W\[nbsp]... \(rq \%\(lq
\%mark\[hy]up has been manually inserted
into the automatically generated file.
.QE
.KE
The application of these finishing touches,
together with the automatically inserted \%mark\[hy]up,
as described in
.XR-NO-PREFIX fdl-macros ,
and the supplementary macros described in
.XR-NO-PREFIX fdl-custom-controls ,
produces the typeset rendition of the \*[FDL-APPENDIX-TITLE]
which is incorporated into
.pdfhref L -D \*[FDL-APPENDIX-LINK] -A . -- \#
 Appendix \*[FDL-APPENDIX-NUMBER] of this publication
.
.\" Local Variables:
.\" mode: nroff
.\" End:
.\" vim: filetype=groff
.\"
.\" $RCSfile: fdl-typesetting.ms,v $: end of file
