10564b1175
groff 1.23.0 added .MR to its -man macro package. The NEWS file states
that the inclusion of the macro "was prompted by its introduction to
Plan 9 from User Space's troff in August 2020." From d32deab it seems
that the name for Plan 9 from User Space's implementation was suggested
by groff maintainer G. Brandon Robinson.
Not sure if the intention was to make these definitions compatible, but
it would be nice if they were.
Currently, Plan 9 from User Space's .MR expects its second argument to
be parenthesized. groff's .MR does not. This results in extra
parentheses appearing in manual references when viewing Plan 9 from User
Space's manual pages on a system using groff.
191 lines
5.2 KiB
Groff
191 lines
5.2 KiB
Groff
.TH FONT 7
|
|
.SH NAME
|
|
font, subfont \- external format for fonts and subfonts
|
|
.SH SYNOPSIS
|
|
.B #include <draw.h>
|
|
.SH DESCRIPTION
|
|
Fonts and subfonts are described in
|
|
.MR cachechars 3 .
|
|
.PP
|
|
External bitmap fonts are described by a plain text file that can be read using
|
|
.IR openfont .
|
|
The format of the file is a header followed by any number of
|
|
subfont range specifications.
|
|
The header contains two numbers: the height and the ascent, both in pixels.
|
|
The height is the inter-line spacing and the ascent is the distance
|
|
from the top of the line to the baseline. These numbers are chosen
|
|
to display consistently all the subfonts of the font.
|
|
A subfont range specification contains two or three numbers and a file name.
|
|
The numbers are the inclusive range of characters covered by the subfont,
|
|
with an optional starting position within the subfont,
|
|
and the file name names an external file suitable for
|
|
.I readsubfont
|
|
(see
|
|
.MR graphics 3 ).
|
|
The minimum number of a covered range is mapped to the specified starting position
|
|
(default zero) of the
|
|
corresponding subfont.
|
|
If the subfont file name does not begin with a slash, it is taken relative to the
|
|
directory containing the font file.
|
|
Each field must be followed by some white space.
|
|
Each numeric field may be C-format decimal, octal, or hexadecimal.
|
|
.PP
|
|
External subfonts are represented in a more rigid format
|
|
that can be read and written using
|
|
.I readsubfont
|
|
and
|
|
.I writesubfont
|
|
(see
|
|
.MR subfont 3 ).
|
|
The format for subfont files is: an image containing character glyphs,
|
|
followed by a subfont header, followed by character information.
|
|
The image has the format for external image files described in
|
|
.MR image 7 .
|
|
The subfont header has 3
|
|
decimal strings:
|
|
.BR n ,
|
|
.BR height ,
|
|
and
|
|
.BR ascent .
|
|
Each number is right-justified and blank padded in 11 characters, followed by a blank.
|
|
The character
|
|
.B info
|
|
consists of
|
|
.BR n +1
|
|
6-byte entries, each giving the
|
|
.B Fontchar
|
|
.B x
|
|
(2 bytes, low order byte first),
|
|
.BR top ,
|
|
.BR bottom ,
|
|
.BR left ,
|
|
and
|
|
.BR width .
|
|
The
|
|
.B x
|
|
field of the last
|
|
.B Fontchar
|
|
is used to calculate the image width
|
|
of the previous character; the other fields in the last
|
|
.B Fontchar
|
|
are irrelevant.
|
|
.PP
|
|
Note that the convention of using the character with value zero (NUL) to represent
|
|
characters of zero width (see
|
|
.MR draw 3 )
|
|
means that fonts should have, as their zeroth character,
|
|
one with non-zero width.
|
|
.SS "Font Names
|
|
.PP
|
|
Font names in Plan 9 from User Space are
|
|
a small language describing a font.
|
|
The most basic form is the name of an existing bitmap font file,
|
|
following the convention:
|
|
.IP
|
|
.B /lib/font/bit/\fIname\fP/\fIrange\fP.\fIsize\fP.font
|
|
.PD
|
|
.PP
|
|
where
|
|
.I size
|
|
is approximately the height in pixels of the lower case letters
|
|
(without ascenders or descenders).
|
|
.I Range
|
|
gives some indication of which characters will be available: for example
|
|
.BR ascii ,
|
|
.BR latin1 ,
|
|
.BR euro ,
|
|
or
|
|
.BR unicode .
|
|
.B Euro
|
|
includes most European languages, punctuation marks, the International Phonetic
|
|
Alphabet, etc., but no Asian languages.
|
|
.B Unicode
|
|
includes every character for which appropriate-sized images exist on the system.
|
|
.PP
|
|
In Plan 9 from User Space, the font files are rooted in
|
|
.B $PLAN9/font
|
|
instead of
|
|
.BR /lib/font/bit ,
|
|
but to keep old references working, paths beginning with
|
|
.B /lib/font/bit
|
|
are interpreted as references to the actual font directory.
|
|
.PP
|
|
Fonts need not be stored on disk in the Plan 9 format.
|
|
If the font name has the form
|
|
.BR /mnt/font/\fIname\fP/\fIsize\fP/font ,
|
|
.I fontsrv
|
|
is invoked to synthesize a bitmap font from the operating system's installed vector fonts.
|
|
The command
|
|
.B fontsrv
|
|
.B -p
|
|
.B .
|
|
lists the available fonts.
|
|
See
|
|
.MR fontsrv 4
|
|
for more.
|
|
.PP
|
|
If the font name has the form
|
|
.BR \fIscale\fP*\fIfontname\fP ,
|
|
where
|
|
.I scale
|
|
is a small decimal integer, the
|
|
.I fontname
|
|
is loaded and then scaled by pixel repetition.
|
|
.PP
|
|
The Plan 9 bitmap fonts were designed for screens with pixel density around 100 DPI.
|
|
When used on screens with pixel density above 200 DPI,
|
|
the bitmap fonts are automatically pixel doubled.
|
|
Similarly, fonts loaded from
|
|
.MR fontsrv 4
|
|
are automatically doubled in size by varying the effective
|
|
.I size
|
|
path element.
|
|
In both cases, the effect is that a single font name
|
|
can be used on both low- and high-density displays (or even in a window moved between differing displays)
|
|
while keeping roughly the same effective size.
|
|
.PP
|
|
For more control over the fonts used on low- and high-density displays,
|
|
if the font name has the form
|
|
.BR \fIlowfont\fP,\fIhighfont\fP ,
|
|
.I lowfont
|
|
is used on low-density displays and
|
|
.I highfont
|
|
on high-density displays.
|
|
In effect, the behavior described above is that the font name
|
|
.IP
|
|
.B /lib/font/bit/lucsans/euro.8.font
|
|
.PD
|
|
.PP
|
|
really means
|
|
.IP
|
|
.B /lib/font/bit/lucsans/euro.8.font,2*/lib/font/bit/lucsans/euro.8.font
|
|
.PD
|
|
.PP
|
|
and similarly
|
|
.IP
|
|
.B /mnt/font/LucidaGrande/15a/font
|
|
.PD
|
|
.PP
|
|
really means
|
|
.IP
|
|
.B /mnt/font/LucidaGrande/15a/font,/mnt/font/LucidaGrande/30a/font
|
|
.PD
|
|
.PP
|
|
Using an explicit comma-separated font pair allows finer control, such as
|
|
using a Plan 9 bitmap font on low-density displays but switching to
|
|
a system-installed vector font on high-density displays:
|
|
.IP
|
|
.B /lib/font/bit/lucsans/euro.8.font,/mnt/font/LucidaGrande/30a/font
|
|
.PD
|
|
.PP
|
|
.SH FILES
|
|
.TF \*9/font/*
|
|
.TP
|
|
.B \*9/font/*
|
|
font directories
|
|
.SH "SEE ALSO"
|
|
.MR graphics 3 ,
|
|
.MR draw 3 ,
|
|
.MR cachechars 3 ,
|
|
.MR subfont 3
|