[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 28/39: [docs]: Update discussion of font positions.
From: |
G. Branden Robinson |
Subject: |
[groff] 28/39: [docs]: Update discussion of font positions. |
Date: |
Tue, 31 May 2022 20:32:30 -0400 (EDT) |
gbranden pushed a commit to branch master
in repository groff.
commit f76ab61df5425d62b0d8499294912583a2a4d191
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Mon May 30 20:28:05 2022 -0500
[docs]: Update discussion of font positions.
* doc/groff.texi (Font Positions): Identify groff's "styles" feature as
a motivator for the font positions feature, not just AT&T
compatibility. Talk about "font selection" rather than "font
changing" (it is not in groff's power to alter a font per se).
Describe how the initial set of mounting positions is populated in
more detail. Drop footnote about position 0 "usually" being unused;
none of our output devices populates it by default. Describe what the
second argument to the `fp` request really is--a font description file
name. Better separate formal presentation of `.f` register from an
example of its use. Clarify that the `.fp` register won't report the
availablity of position 0. Clarify what an "external name", the third
argument to the `fp` request, really is, and how its presence changes
how the second argument is handled. Document that GNU troff won't
traverse directories to locate a font description file (see Savannah
#61424). Elaborate upon how this feature enables use of long font
names in compatibility mode. Say "escape sequence" instead of
"escape". Stop calling the two different interpretation modes of `ft`
different "syntax forms"; this is false. They are only _semantically_
different (particularly since integers are valid *roff identifiers
anyway).
* man/groff.7.man (Request short reference) <ft>: As above, talk about
"font selection" rather than "font changing". Clarify that the
argument can be a style, font name, or mounting position. Parallelize
summaries of the two invocation forms grammatically.
---
doc/groff.texi | 100 +++++++++++++++++++++++++++++---------------------------
man/groff.7.man | 16 +++++----
2 files changed, 60 insertions(+), 56 deletions(-)
diff --git a/doc/groff.texi b/doc/groff.texi
index 475cb57d..8e36060b 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -9940,66 +9940,73 @@ A solution to this problem is to use a dummy font like
the following:
@c ---------------------------------------------------------------------
+@codequotebacktick on
+@codequoteundirected on
+
@node Font Positions, Using Symbols, Font Families, Fonts and Symbols
@subsection Font Positions
@cindex font positions
@cindex positions, font
-For compatibility with @acronym{AT&T} @code{troff}, GNU @code{troff}
-has the concept of font @dfn{positions} at which various fonts are
-@dfn{mounted}.
+To support typeface indirection through styles, and for compatibility
+with @acronym{AT&T} @code{troff}, GNU @code{troff} has the concept of
+font @dfn{positions}, at which various fonts are @dfn{mounted}.
@DefreqList {fp, pos font [@Var{external-name}]}
@DefregItemx {.f}
@DefregListEndx {.fp}
@cindex mounting font (@code{fp})
@cindex font, mounting (@code{fp})
-Mount font @var{font} at position @var{pos} (which must be a
-non-negative integer). This numeric index can then be referred to with
-font-changing commands. When GNU @code{troff} starts, it uses font
-position@tie{}1 (which must exist; position@tie{}0 is unused at
-startup.@footnote{Usually.})
+Mount the font named @var{font} at position @var{pos}, a non-negative
+integer. This numeric index can then be referred to with font selection
+instructions. When the formatter starts up, it reads the output
+device's description to mount an initial set of faces, and selects font
+position@tie{}1. Position@tie{}0 is unused by default. Unless the
+@var{external-name} argument is given, the name @var{font} should be
+that of a font description file stored in a directory corresponding to
+the selected output device.@footnote{In other words, the font
+description file must be located in the same directory as the output
+device's @file{DESC} file; see @ref{Device and Font Description Files}.}
@cindex font position register (@code{.f})
-The current font in use, as a font position, is available in the
-read-only register @samp{.f}. This can be useful to save the current
-font for later recall. It is associated with the environment
+The position of the currently selected font (or style) is available in
+the read-only register @samp{.f}. It is associated with the environment
(@pxref{Environments}).
+The value of @code{.f} can be copied to another register to save the
+current font or style for later recall.
+
@Example
-.nr save-font \n[.f]
+.nr saved-font \n[.f]
.ft B
-... text text text ...
-.ft \n[save-font]
+@r{@dots{}} text text text @r{@dots{}}
+.ft \n[saved-font]
@endExample
@cindex next free font position register (@code{.fp})
-The index of the next free font position is available in the read-only
-register @samp{.fp}. This is useful when mounting a new font, like so:
-
-@Example
-.fp \n[.fp] NEATOFONT
-@endExample
-
+The index of the next (nonzero) free font position is available in the
+read-only register @samp{.fp}.
@cindex @file{DESC} file, and font mounting
-Fonts not listed in the @file{DESC} file are automatically mounted on
-the next available font position when they are referenced. If a font is
-to be mounted explicitly with the @code{fp} request on an unused font
-position, it should be mounted on the first unused font position, which
-can be found in the @code{.fp} register, although GNU @code{troff} does
-not enforce this strictly.
-
-The @code{fp} request has an optional third argument. This argument
-gives the external name of the font, which is used for finding the font
-description file. The second argument gives the internal name of the
-font, which is used to refer to the font in @code{gtroff} after it has
-been mounted. If there is no third argument then the internal name is
-used as the external name. This feature makes it possible to use fonts
-with long names in compatibility mode.
+Fonts not listed in the @file{DESC} file are automatically mounted at
+position @samp{\n[.fp]} when selected. When mounting a font at a
+position explicitly with the @code{fp} request, this same practice
+should be followed, although GNU @code{troff} does not enforce this
+strictly.
+
+The optional third argument @var{external-name} is the name of a font
+description file in the operating environment. GNU @code{troff} refuses
+to traverse directories to locate the font description. The second
+argument @var{font} is then the internal name of the font, which
+identifies it to GNU @code{troff} once it has been mounted. If there is
+no third argument, the font description is sought in the file system
+under its internal name. This feature enables font names to be aliased,
+which can be necessary in compatibility mode since AT&T @code{troff}
+syntax affords no means of loading fonts with names longer than two
+characters, like @samp{TBI} or @samp{ZCMI}. @xref{Compatibility Mode}.
@endDefreq
-Both the @code{ft} request and the @code{\f} escape have alternative
-syntax forms to access font positions.
+The @code{ft} request and @code{\f} escape sequence accept mounting
+positions in the place of font or style names.
@DefreqList {ft, nnn}
@DefescItemx {\\f, , n, }
@@ -10013,14 +10020,12 @@ syntax forms to access font positions.
@kindex styles
@kindex family
@pindex DESC
-Change the current font position to @var{nnn} (one-digit
-position@tie{}@var{n}, two-digit position @var{nn}), which must be a
-non-negative integer.
-
-If @var{nnn} is associated with a style (as set with the @code{sty}
-request or with the @code{styles} command in the @file{DESC} file), use
-it within the current font family (as set with the @code{fam} request,
-the @code{\F} escape, or the @code{family} command in the
+Select font position @var{nnn} (one-digit position@tie{}@var{n},
+two-digit position @var{nn}), which must be a non-negative integer. If
+@var{nnn} is associated with a style (as set with the @code{sty} request
+or with the @code{styles} command in the @file{DESC} file), use it
+within the current font family (as set with the @code{fam} request, the
+@code{\F} escape sequence, or the @code{family} command in the
@file{DESC} file).
@Example
@@ -10034,14 +10039,11 @@ this is font 3
this is font 1 again
@endExample
-@xref{Changing Fonts}, for the standard syntax form.
+@xref{Changing Fonts}, for font selection by name.
@endDefreq
@c ---------------------------------------------------------------------
-@codequotebacktick on
-@codequoteundirected on
-
@node Using Symbols, Character Classes, Font Positions, Fonts and Symbols
@subsection Using Symbols
@cindex using symbols
diff --git a/man/groff.7.man b/man/groff.7.man
index 3e0ca588..92e2d55e 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -2230,16 +2230,16 @@ Flush output buffer.
.REQ .fp "n font"
Mount
.I font
-on position
+at position
.IR n .
.
.TPx
.REQ .fp "n internal external"
-Mount font with long
+Mount font with description file
.I external
-name to short
+under the name
.I internal
-name on position
+at position
.IR n .
.
.TPx
@@ -2269,15 +2269,17 @@ are special.
.
.TPx
.REQ .ft
-Return to previous font.
-Same as
+Select previous style or font;
+same as
.esc f[]
or
.esc fP .
.
.TPx
.REQ .ft "font"
-Change to font name or number
+Select style,
+font name,
+or mounting position
.IR font ;
same as
.esc[] f font
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 28/39: [docs]: Update discussion of font positions.,
G. Branden Robinson <=