Bug#1072879: fonts-conf.5: some remarks and editorial fixes for this man page
Bjarni Ingi Gislason
bjarniig at simnet.is
Sun Jun 9 18:12:09 BST 2024
Package: fontconfig-config
Version: 2.15.0-1.1
Severity: minor
Tags: patch
Dear Maintainer,
* What led up to the situation?
Checking for defects with
[test-]groff -mandoc -t -K utf8 -ww -b -z <man page>
[test-groff is a script in the repository for "groff"]
* What was the outcome of this action?
troff: backtrace: '<stdin>':2: string 'an-extra1'
troff: backtrace: '/home/bg/git/groff/build/s-tmac/an.tmac':221: string 'TH'
troff: backtrace: '/home/bg/git/groff/build/s-tmac/andoc.tmac':46: macro 'TH'
troff: backtrace: file '<stdin>':2
troff:<stdin>:2: warning: special character 'u6708' not defined
[ This is a part of a date and therefore should be coded in ASCII. ]
* What outcome did you expect instead?
No output (warnings).
-.-
Remarks and a patch are in the attachments.
The concerned man page was autogenerated.
auto-generated by docbook2man-spec from docbook-utils package
-.-
-- System Information:
Debian Release: trixie/sid
APT prefers testing
APT policy: (500, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.7.12-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 fontconfig-config depends on:
ii debconf [debconf-2.0] 1.5.86
ii fonts-dejavu-core 2.37-8
ii fonts-urw-base35 20200910-8
fontconfig-config recommends no packages.
fontconfig-config suggests no packages.
-- debconf information excluded
-------------- next part --------------
Any program (person), that produces man pages, should check its content for
defects by using
groff -mandoc -t -ww -b -z [ -K utf8 | k ] <man page>
The same goes for man pages that are used as an input.
For a style guide use
mandoc -T lint
-.-
So any generator should check its products with the above mentioned
'groff' and additionally with 'nroff ...'.
This is just a simple quality control measure.
The generator may have to be corrected to get a better man page,
the source file may, and any additional file may.
-.-
The difference between the formatted outputs can be seen with:
nroff -mandoc <file1> > <out1>
nroff -mandoc <file2> > <out2>
diff -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 of "diff -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 -z"
export MAN_KEEP_STDERR=yes (or any non-empty value)
-.-.
Output from "mandoc -T lint fonts-conf.5": (possibly shortened list)
mandoc: fonts-conf.5:6:2: WARNING: skipping paragraph macro: sp after SH
mandoc: fonts-conf.5:18:2: WARNING: skipping paragraph macro: PP after SH
mandoc: fonts-conf.5:22:2: WARNING: skipping paragraph macro: PP after SH
mandoc: fonts-conf.5:27:2: WARNING: skipping paragraph macro: PP after SS
mandoc: fonts-conf.5:52:2: WARNING: skipping paragraph macro: PP after SS
mandoc: fonts-conf.5:123:2: WARNING: skipping paragraph macro: PP after SS
mandoc: fonts-conf.5:179:2: WARNING: skipping paragraph macro: PP after SS
mandoc: fonts-conf.5:214:2: WARNING: skipping paragraph macro: PP after SH
mandoc: fonts-conf.5:245:2: WARNING: skipping paragraph macro: PP after SH
mandoc: fonts-conf.5:263:2: WARNING: skipping paragraph macro: PP after SH
mandoc: fonts-conf.5:285:2: WARNING: skipping paragraph macro: PP after SS
mandoc: fonts-conf.5:289:2: WARNING: skipping paragraph macro: PP after SS
mandoc: fonts-conf.5:293:394: STYLE: input text line longer than 80 bytes: If 'prefix' is set t...
mandoc: fonts-conf.5:297:2: WARNING: skipping paragraph macro: PP after SS
mandoc: fonts-conf.5:302:218: STYLE: input text line longer than 80 bytes: a directory in the u...
mandoc: fonts-conf.5:303:87: STYLE: input text line longer than 80 bytes: The default director...
mandoc: fonts-conf.5:308:2: WARNING: skipping paragraph macro: PP after SS
mandoc: fonts-conf.5:311:106: STYLE: input text line longer than 80 bytes: ASCII digit (U+0030 ...
mandoc: fonts-conf.5:316:191: STYLE: input text line longer than 80 bytes: the library. If 'pre...
mandoc: fonts-conf.5:318:2: WARNING: skipping paragraph macro: PP after SS
mandoc: fonts-conf.5:323:2: WARNING: skipping paragraph macro: PP after SS
mandoc: fonts-conf.5:324:82: STYLE: input text line longer than 80 bytes: This element is supp...
mandoc: fonts-conf.5:325:102: STYLE: input text line longer than 80 bytes: This string can be t...
mandoc: fonts-conf.5:328:2: WARNING: skipping paragraph macro: PP after SS
mandoc: fonts-conf.5:335:2: WARNING: skipping paragraph macro: PP after SS
mandoc: fonts-conf.5:344:2: WARNING: skipping paragraph macro: PP after SS
mandoc: fonts-conf.5:346:87: STYLE: input text line longer than 80 bytes: This is useful to ov...
mandoc: fonts-conf.5:348:2: WARNING: skipping paragraph macro: PP after SS
mandoc: fonts-conf.5:354:2: WARNING: skipping paragraph macro: PP after SS
mandoc: fonts-conf.5:361:2: WARNING: skipping paragraph macro: PP after SS
mandoc: fonts-conf.5:368:2: WARNING: skipping paragraph macro: PP after SS
mandoc: fonts-conf.5:374:2: WARNING: skipping paragraph macro: PP after SS
mandoc: fonts-conf.5:383:2: WARNING: skipping paragraph macro: PP after SS
mandoc: fonts-conf.5:391:2: WARNING: skipping paragraph macro: PP after SS
mandoc: fonts-conf.5:397:2: WARNING: skipping paragraph macro: PP after SS
mandoc: fonts-conf.5:406:2: WARNING: skipping paragraph macro: PP after SS
mandoc: fonts-conf.5:408:103: STYLE: input text line longer than 80 bytes: ('pattern', 'font', ...
mandoc: fonts-conf.5:409:99: STYLE: input text line longer than 80 bytes: above). 'compare' ca...
mandoc: fonts-conf.5:413:217: STYLE: input text line longer than 80 bytes: match the test value...
mandoc: fonts-conf.5:419:2: WARNING: skipping paragraph macro: PP after SS
mandoc: fonts-conf.5:444:2: WARNING: skipping paragraph macro: PP after SS
mandoc: fonts-conf.5:452:2: WARNING: skipping paragraph macro: PP after SS
mandoc: fonts-conf.5:457:2: WARNING: skipping paragraph macro: PP after SS
mandoc: fonts-conf.5:461:2: WARNING: skipping paragraph macro: PP after SS
mandoc: fonts-conf.5:465:2: WARNING: skipping paragraph macro: PP after SS
mandoc: fonts-conf.5:469:2: WARNING: skipping paragraph macro: PP after SS
mandoc: fonts-conf.5:478:2: WARNING: skipping paragraph macro: PP after SS
mandoc: fonts-conf.5:538:2: WARNING: skipping paragraph macro: PP after SS
mandoc: fonts-conf.5:542:2: WARNING: skipping paragraph macro: PP after SS
mandoc: fonts-conf.5:545:2: WARNING: skipping paragraph macro: PP after SS
mandoc: fonts-conf.5:548:2: WARNING: skipping paragraph macro: PP after SS
mandoc: fonts-conf.5:553:2: WARNING: skipping paragraph macro: PP after SS
mandoc: fonts-conf.5:562:2: WARNING: skipping paragraph macro: PP after SS
mandoc: fonts-conf.5:565:2: WARNING: skipping paragraph macro: PP after SS
mandoc: fonts-conf.5:569:2: WARNING: skipping paragraph macro: PP after SS
mandoc: fonts-conf.5:712:2: WARNING: skipping paragraph macro: PP after SS
mandoc: fonts-conf.5:779:2: WARNING: skipping paragraph macro: PP after SH
mandoc: fonts-conf.5:800:165: STYLE: input text line longer than 80 bytes: actual location is s...
mandoc: fonts-conf.5:804:163: STYLE: input text line longer than 80 bytes: actual location is s...
mandoc: fonts-conf.5:808:188: STYLE: input text line longer than 80 bytes: per-directory caches...
mandoc: fonts-conf.5:810:2: WARNING: skipping paragraph macro: PP after SH
mandoc: fonts-conf.5:821:103: STYLE: input text line longer than 80 bytes: is used to output th...
mandoc: fonts-conf.5:824:181: STYLE: input text line longer than 80 bytes: is used to filter ou...
mandoc: fonts-conf.5:827:153: STYLE: input text line longer than 80 bytes: is used to specify t...
mandoc: fonts-conf.5:830:321: STYLE: input text line longer than 80 bytes: is used to control t...
mandoc: fonts-conf.5:833:437: STYLE: input text line longer than 80 bytes: is used to ensure fc...
mandoc: fonts-conf.5:835:2: WARNING: skipping paragraph macro: PP after SH
mandoc: fonts-conf.5:836:145: STYLE: input text line longer than 80 bytes: fc-cat(1), fc-cache(...
mandoc: fonts-conf.5:838:2: WARNING: skipping paragraph macro: PP after SH
-.-.
Remove space characters at the end of lines.
Use "git apply ... --whitespace=fix" to fix extra space issues, or use
global configuration "core.whitespace".
119:
187:
204:
237:
281:
440:
534:
708:
775:
-.-.
Change two HYPHEN-MINUSES (code 0x2D) to an em-dash (\(em),
if one is intended. An en-dash is usually surrounded by a space,
while an em-dash is used without spaces.
"man" (1 byte characters in input) transforms an en-dash (\(en) to one
HYPHEN-MINUS,
and an em-dash to two HYPHEN-MINUSES without considering the space
around it.
If "--" are two single "-" (end of options) then use "\-\-".
fonts-conf.5:60:--------------------------------------------------------------
fonts-conf.5:150:order -- results of comparing earlier elements of this list weigh more
fonts-conf.5:173:because there are essentially two different operations necessary -- the
fonts-conf.5:198:----------------------------------------------------------
fonts-conf.5:223:---------------------------------------------------------
fonts-conf.5:249:and occur in two parts -- the ISO 639 language tag followed a hyphen and then
fonts-conf.5:431:---------------------------------------------------------------------
fonts-conf.5:447:the parsing of floating point numbers -- fontconfig requires that
fonts-conf.5:484:-------------------------------------
fonts-conf.5:575:<!-- /etc/fonts/fonts.conf file to configure system font access -->
fonts-conf.5:577: <!--
fonts-conf.5:579: -->
fonts-conf.5:583: <!--
fonts-conf.5:585: -->
fonts-conf.5:595: <!--
fonts-conf.5:597: -->
fonts-conf.5:613: <!--
fonts-conf.5:616: -->
fonts-conf.5:621: <!--
fonts-conf.5:624: -->
fonts-conf.5:628: <!--
fonts-conf.5:632: -->
fonts-conf.5:661: <!--
fonts-conf.5:665: -->
fonts-conf.5:685: <--
fonts-conf.5:689: -->
fonts-conf.5:719:<!--
fonts-conf.5:721:-->
fonts-conf.5:724: <!--
fonts-conf.5:726: -->
fonts-conf.5:729: <!--
fonts-conf.5:733: -->
fonts-conf.5:739: <!--
fonts-conf.5:741: -->
fonts-conf.5:743: <!--
fonts-conf.5:749: -->
fonts-conf.5:760: <!--
fonts-conf.5:762: -->
-.-.
Mark a full stop (.) and the exclamation mark (!) with "\&",
if it does not mean an end of a sentence.
This is a preventive action,
the paragraph could be reshaped, e.g., after changes.
When typing, one does not always notice when the line wraps after the
period.
There are too many examples of input lines in manual pages,
that end with an abbreviation point.
This marking is robust, and independent of the position on the line.
It corresponds to "\ " in TeX, and to "@:" in Texinfo.
293:If 'prefix' is set to "default" or "cwd", the current working directory will be added as the path prefix prior to the value. If 'prefix' is set to "xdg", the value in the XDG_DATA_HOME environment variable will be added as the path prefix. please see XDG Base Directory Specification for more details. If 'prefix' is set to "relative", the path of current file will be added prior to the value.
295:\&'salt' property affects to determine cache filename. this is useful for example when having different fonts sets on same path at container and share fonts from host on different font path.
302:a directory in the users home directory. If 'prefix' is set to "xdg", the value in the XDG_CACHE_HOME environment variable will be added as the path prefix. please see XDG Base Directory Specification for more details.
316:the library. If 'prefix' is set to "xdg", the value in the XDG_CONFIG_HOME environment variable will be added as the path prefix. please see XDG Base Directory Specification for more details.
320:information. <config> can contain <blank> and <rescan> elements in any
325:This string can be translated through gettext. 'domain' needs to be set the proper name to apply then.
409:above). 'compare' can be one of "eq", "not_eq", "less", "less_eq", "more", "more_eq", "contains" or
410:"not_contains". 'qual' may either be the default, "any", in which case the match
413:match the test value. 'ignore-blanks' takes a boolean value. if 'ignore-blanks' is set "true", any blanks in the string will be ignored on its comparison. this takes effects only when compare="eq" or compare="not_eq".
416:the original pattern or the font. "default" selects whichever target the
445:These elements hold a single value of the indicated type. <bool>
449:zero for purely fractional values (e.g. use 0.5 instead of .5 and -0.5
540:elements. <or> and <and> are boolean, not bitwise.
800:actual location is specified in the global fonts.conf file. please note that ~/.fonts.conf.d is deprecated now. it will not be read by default in the future version.
804:actual location is specified in the global fonts.conf file. please note that ~/.fonts.conf is deprecated now. it will not be read by default in the future version.
808:per-directory caches. This file is automatically maintained by fontconfig. please note that ~/.fontconfig/*.cache-* is deprecated now. it will not be read by default in the future version.
821:is used to output the detailed debugging messages. see Debugging Applications section for more details.
824:is used to filter out the patterns. this takes a comma-separated list of object names and effects only when FC_DEBUG has MATCH2. see Debugging Applications section for more details.
827:is used to specify the default language as the weak binding in the query. if this isn't set, the default language will be determined from current locale.
830:is used to control the use of mmap(2) for the cache files if available. this take a boolean value. fontconfig will checks if the cache files are stored on the filesystem that is safe to use mmap(2). explicitly setting this environment variable will causes skipping this check and enforce to use or not use mmap(2) anyway.
-.-.
Change - to \- if it shall be printed as a minus sign.
fonts-conf.5:449:zero for purely fractional values (e.g. use 0.5 instead of .5 and -0.5
-.-.
Use "\e" to print the escape character instead of "\\" (which gets
interpreted in copy mode).
208:The '\\', '-', ':' and ',' characters in family names must be preceded by a
209:\&'\\' character to avoid having them misinterpreted. Similarly, values
210:containing '\\', '=', '_', ':' and ',' must also have them preceded by a
211:\&'\\' character. The '\\' characters are stripped out of the family name and
-.-.
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.
60:--------------------------------------------------------------
89: none - subpixel geometry
150:order -- results of comparing earlier elements of this list weigh more
173:because there are essentially two different operations necessary -- the
186:<families>-<point sizes>:<name1>=<values1>:<name2>=<values2>\&...
198:----------------------------------------------------------
208:The '\\', '-', ':' and ',' characters in family names must be preceded by a
223:---------------------------------------------------------
249:and occur in two parts -- the ISO 639 language tag followed a hyphen and then
304:named ``<hash value>-<architecture>\&.cache-<version>\&'',
311:ASCII digit (U+0030 - U+0039) and ending with the string ``.conf'' will be processed in sorted order. When
431:---------------------------------------------------------------------
447:the parsing of floating point numbers -- fontconfig requires that
449:zero for purely fractional values (e.g. use 0.5 instead of .5 and -0.5
450:instead of -.5).
484:-------------------------------------
575:<!-- /etc/fonts/fonts.conf file to configure system font access -->
577: <!--
579: -->
583: <!--
585: -->
595: <!--
597: -->
613: <!--
616: -->
621: <!--
624: -->
628: <!--
632: -->
661: <!--
665: -->
685: <--
689: -->
719:<!--
721:-->
724: <!--
726: -->
729: <!--
733: -->
739: <!--
741: -->
743: <!--
749: -->
760: <!--
762: -->
-.-.
Strings longer than 3/4 of a standard line length (80)
836 fc-cat(1), fc-cache(1), fc-list(1), fc-match(1), fc-query(1), SOURCE_DATE_EPOCH <URL:https://reproducible-builds.org/specs/source-date-epoch/>\&.
-.-.
Add a comma (or \&) after "e.g." and "i.e.", or use English words
(man-pages(7)).
Abbreviation points should be protected against being interpreted as
an end of sentence, if they are not, and that independent of the
current place on the line.
449:zero for purely fractional values (e.g. use 0.5 instead of .5 and -0.5
-.-.
Wrong distance between sentences.
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.
N.B.
The number of lines affected can be too large to be in the patch.
30:data found within. From an external perspective, configuration of the
32:FcConfigParse. The only other mechanism provided to applications for
37:as many applications as possible. It is hoped that this will lead to more
45:perform private matching. The intent is to permit applications to pick and
47:choose between this library and a private configuration mechanism. The hope
49:can be centralized in one place. Centralizing font configuration will
54:well known properties with associated types. Fontconfig uses some of these
55:properties for font matching and font completion. Others are provided as a
63:style String Font style. Overrides weight and slant
125:pattern to all of the available fonts in the system. The closest matching
126:font is selected. This ensures that a font will always be returned, but
129:Font matching starts with an application constructed pattern. The desired
130:attributes of the resulting font are collected together in a pattern. Each
137:predicate and a set of editing operations. They are executed in the order
138:they appeared in the configuration. Each match causes the associated
149:slant, weight, antialias, rasterizer and outline. This list is in priority
154:bindings; strong and weak. Strong family names are given greater precedence
156:precedence than lang elements. This permits the document language to drive
162:matching system. Finally, the list of editing instructions specific to
163:fonts found in the configuration are applied to the pattern. This modified
167:font, including the file name, pixel size and other rendering data. As
175:suitable defaults. The second is to modify how the selected fonts are
176:rasterized. Those must apply to the selected font, not the original pattern
181:can both accept and generate. The representation is in three parts, first a
191:Values in a list are separated with commas. The name needn't include either
192:families or point sizes; they can be elided. In addition, there are
209:\&'\\' character to avoid having them misinterpreted. Similarly, values
211:\&'\\' character. The '\\' characters are stripped out of the family name and
216:large amount of internal debugging left enabled. It is controlled by means
217:of the FC_DEBUG environment variable. The value of this variable is
243:application. Output from these statements is sent to stdout.
246:Each font in the database contains a list of languages it supports. This is
248:of each language. Languages are tagged using an RFC-3066 compatible naming
250:by the ISO 3166 country code. The hyphen and country code may be elided.
254:library. It currently supports 122 of the 139 languages named in ISO 639-1,
256:languages with only three-letter codes. Languages with both two and three
260:character sets, fontconfig includes per-territory orthographies. This
266:they will generate syntactically correct configuration files. As XML
272:directory (/etc/fonts). Each configuration file should contain the
293:If 'prefix' is set to "default" or "cwd", the current working directory will be added as the path prefix prior to the value. If 'prefix' is set to "xdg", the value in the XDG_DATA_HOME environment variable will be added as the path prefix. please see XDG Base Directory Specification for more details. If 'prefix' is set to "relative", the path of current file will be added prior to the value.
295:\&'salt' property affects to determine cache filename. this is useful for example when having different fonts sets on same path at container and share fonts from host on different font path.
299:the cache of font information. If multiple elements are specified in
301:will be used to store the cache files. If it starts with '~', it refers to
302:a directory in the users home directory. If 'prefix' is set to "xdg", the value in the XDG_CACHE_HOME environment variable will be added as the path prefix. please see XDG Base Directory Specification for more details.
310:directory. If a directory, every file within that directory starting with an
311:ASCII digit (U+0030 - U+0039) and ending with the string ``.conf'' will be processed in sorted order. When
314:FcConfigLoadAndParse. If 'ignore_missing' is set to "yes" instead of the
316:the library. If 'prefix' is set to "xdg", the value in the XDG_CONFIG_HOME environment variable will be added as the path prefix. please see XDG Base Directory Specification for more details.
320:information. <config> can contain <blank> and <rescan> elements in any
325:This string can be translated through gettext. 'domain' needs to be set the proper name to apply then.
330:drawn as blanks on the screen. Within the <blank> element, place each
356:against. It holds acceptfont and rejectfont elements. This list is applied
357:only once when caches is loaded. So if you want to filter out by some patterns,
365:by a rejectfont element. Acceptfont elements include glob and pattern
371:they didn't exist in the system. Rejectfont elements include glob and
375:Glob elements hold shell-style filename matching patterns (including ? and
376:*) which match fonts based on their complete pathnames. If it starts with '~',
377:it refers to a directory in the users home directory. This can be used to
380:on filenaming conventions which can't be relied upon. Note that globs
385:they hold a list of elements and associated values. If all of those
386:elements have a matching value, then the pattern matches the font. This can
392:Patelt elements hold a single pattern element and list of values. They must
393:have a 'name' attribute which indicates the pattern element name. Patelt
399:a (possibly empty) list of <edit> elements. Patterns which match all of the
400:tests are subjected to all the edits. If 'target' is set to "font" instead
402:resulting from a match rather than a font pattern to be matched. If 'target'
409:above). 'compare' can be one of "eq", "not_eq", "less", "less_eq", "more", "more_eq", "contains" or
410:"not_contains". 'qual' may either be the default, "any", in which case the match
413:match the test value. 'ignore-blanks' takes a boolean value. if 'ignore-blanks' is set "true", any blanks in the string will be ignored on its comparison. this takes effects only when compare="eq" or compare="not_eq".
416:the original pattern or the font. "default" selects whichever target the
421:operator elements). The expression elements are evaluated at run-time and
422:modify the property "property". The modification depends on whether
424:modification may affect the first matched value. Any values inserted into
445:These elements hold a single value of the indicated type. <bool>
446:elements hold either true or false. An important limitation exists in
449:zero for purely fractional values (e.g. use 0.5 instead of .5 and -0.5
470:Holds a property name. Evaluates to the first value from the property of
471:the pattern. If the 'target' attribute is not present, it will default to
474:match. The attribute can also take the values 'font' or 'pattern' to
475:explicitly choose which pattern to use. It is an error to use a target
540:elements. <or> and <and> are boolean, not bitwise.
555:operations needed to substitute one font family for another. They contain a
557:elements. Fonts matching the <family> element are edited to prepend the
784:match the available fonts. It is in XML format.
788:managed by external applications or the local administrator. The
790:and used as additional configuration files. All of these files are in XML
791:format. The master fonts.conf file references this directory in an
800:actual location is specified in the global fonts.conf file. please note that ~/.fonts.conf.d is deprecated now. it will not be read by default in the future version.
804:actual location is specified in the global fonts.conf file. please note that ~/.fonts.conf is deprecated now. it will not be read by default in the future version.
808:per-directory caches. This file is automatically maintained by fontconfig. please note that ~/.fontconfig/*.cache-* is deprecated now. it will not be read by default in the future version.
821:is used to output the detailed debugging messages. see Debugging Applications section for more details.
824:is used to filter out the patterns. this takes a comma-separated list of object names and effects only when FC_DEBUG has MATCH2. see Debugging Applications section for more details.
827:is used to specify the default language as the weak binding in the query. if this isn't set, the default language will be determined from current locale.
830:is used to control the use of mmap(2) for the cache files if available. this take a boolean value. fontconfig will checks if the cache files are stored on the filesystem that is safe to use mmap(2). explicitly setting this environment variable will causes skipping this check and enforce to use or not use mmap(2) anyway.
833:is used to ensure fc-cache(1) generates files in a deterministic manner in order to support reproducible builds. When set to a numeric representation of UNIX timestamp, fontconfig will prefer this value over using the modification timestamps of the input files in order to identify which cache files require regeneration. If SOURCE_DATE_EPOCH is not set (or is newer than the mtime of the directory), the existing behaviour is unchanged.
-.-.
Split lines longer than 80 characters into two or more lines.
Appropriate break points are the end of a sentence and a subordinate
clause; after punctuation marks.
N.B.
The number of lines affected can be too large to be in the patch.
Line 293, length 394
If 'prefix' is set to "default" or "cwd", the current working directory will be added as the path prefix prior to the value. If 'prefix' is set to "xdg", the value in the XDG_DATA_HOME environment variable will be added as the path prefix. please see XDG Base Directory Specification for more details. If 'prefix' is set to "relative", the path of current file will be added prior to the value.
Line 295, length 190
\&'salt' property affects to determine cache filename. this is useful for example when having different fonts sets on same path at container and share fonts from host on different font path.
Line 302, length 218
a directory in the users home directory. If 'prefix' is set to "xdg", the value in the XDG_CACHE_HOME environment variable will be added as the path prefix. please see XDG Base Directory Specification for more details.
Line 303, length 87
The default directory is ``$XDG_CACHE_HOME/fontconfig'' and it contains the cache files
Line 311, length 106
ASCII digit (U+0030 - U+0039) and ending with the string ``.conf'' will be processed in sorted order. When
Line 316, length 191
the library. If 'prefix' is set to "xdg", the value in the XDG_CONFIG_HOME environment variable will be added as the path prefix. please see XDG Base Directory Specification for more details.
Line 324, length 82
This element is supposed to hold strings which describe what a config is used for.
Line 325, length 102
This string can be translated through gettext. 'domain' needs to be set the proper name to apply then.
Line 346, length 87
This is useful to override fonts directories from system to own fonts directories only.
Line 408, length 103
('pattern', 'font', 'scan' or 'default') property "property" (substitute any of the property names seen
Line 409, length 99
above). 'compare' can be one of "eq", "not_eq", "less", "less_eq", "more", "more_eq", "contains" or
Line 413, length 217
match the test value. 'ignore-blanks' takes a boolean value. if 'ignore-blanks' is set "true", any blanks in the string will be ignored on its comparison. this takes effects only when compare="eq" or compare="not_eq".
Line 541, length 85
.SS "<EQ>, <NOT_EQ>, <LESS>, <LESS_EQ>, <MORE>, <MORE_EQ>, <CONTAINS>, <NOT_CONTAINS"
Line 800, length 165
actual location is specified in the global fonts.conf file. please note that ~/.fonts.conf.d is deprecated now. it will not be read by default in the future version.
Line 804, length 163
actual location is specified in the global fonts.conf file. please note that ~/.fonts.conf is deprecated now. it will not be read by default in the future version.
Line 808, length 188
per-directory caches. This file is automatically maintained by fontconfig. please note that ~/.fontconfig/*.cache-* is deprecated now. it will not be read by default in the future version.
Line 821, length 103
is used to output the detailed debugging messages. see Debugging Applications section for more details.
Line 824, length 181
is used to filter out the patterns. this takes a comma-separated list of object names and effects only when FC_DEBUG has MATCH2. see Debugging Applications section for more details.
Line 827, length 153
is used to specify the default language as the weak binding in the query. if this isn't set, the default language will be determined from current locale.
Line 830, length 321
is used to control the use of mmap(2) for the cache files if available. this take a boolean value. fontconfig will checks if the cache files are stored on the filesystem that is safe to use mmap(2). explicitly setting this environment variable will causes skipping this check and enforce to use or not use mmap(2) anyway.
Line 833, length 437
is used to ensure fc-cache(1) generates files in a deterministic manner in order to support reproducible builds. When set to a numeric representation of UNIX timestamp, fontconfig will prefer this value over using the modification timestamps of the input files in order to identify which cache files require regeneration. If SOURCE_DATE_EPOCH is not set (or is newer than the mtime of the directory), the existing behaviour is unchanged.
Line 836, length 145
fc-cat(1), fc-cache(1), fc-list(1), fc-match(1), fc-query(1), SOURCE_DATE_EPOCH <URL:https://reproducible-builds.org/specs/source-date-epoch/>\&.
-.-.
Use \(en (en-dash) for a dash between space characters,
not a minus (\-) or a hyphen (-), except in the NAME section.
fonts-conf.5:89: none - subpixel geometry
fonts-conf.5:311:ASCII digit (U+0030 - U+0039) and ending with the string ``.conf'' will be processed in sorted order. When
-.-.
Add a zero (0) in front of a decimal fraction that begins with a period
(.)
202:Monospace:matrix=1 .1 0 1 The users preferred monospace font
449:zero for purely fractional values (e.g. use 0.5 instead of .5 and -0.5
-.-.
Protect a period (.) or an apostrophe (') with '\&' from becoming a
control character, if it could end up at the start of a line
(by splitting the line into more lines).
202:Monospace:matrix=1 .1 0 1 The users preferred monospace font
208:The '\\', '-', ':' and ',' characters in family names must be preceded by a
210:containing '\\', '=', '_', ':' and ',' must also have them preceded by a
211:\&'\\' character. The '\\' characters are stripped out of the family name and
293:If 'prefix' is set to "default" or "cwd", the current working directory will be added as the path prefix prior to the value. If 'prefix' is set to "xdg", the value in the XDG_DATA_HOME environment variable will be added as the path prefix. please see XDG Base Directory Specification for more details. If 'prefix' is set to "relative", the path of current file will be added prior to the value.
301:will be used to store the cache files. If it starts with '~', it refers to
302:a directory in the users home directory. If 'prefix' is set to "xdg", the value in the XDG_CACHE_HOME environment variable will be added as the path prefix. please see XDG Base Directory Specification for more details.
314:FcConfigLoadAndParse. If 'ignore_missing' is set to "yes" instead of the
316:the library. If 'prefix' is set to "xdg", the value in the XDG_CONFIG_HOME environment variable will be added as the path prefix. please see XDG Base Directory Specification for more details.
325:This string can be translated through gettext. 'domain' needs to be set the proper name to apply then.
326:fontconfig will tries to retrieve translations with 'domain' from gettext.
337:as the path 'as-path' in cached information.
376:*) which match fonts based on their complete pathnames. If it starts with '~',
393:have a 'name' attribute which indicates the pattern element name. Patelt
400:tests are subjected to all the edits. If 'target' is set to "font" instead
402:resulting from a match rather than a font pattern to be matched. If 'target'
408:('pattern', 'font', 'scan' or 'default') property "property" (substitute any of the property names seen
409:above). 'compare' can be one of "eq", "not_eq", "less", "less_eq", "more", "more_eq", "contains" or
410:"not_contains". 'qual' may either be the default, "any", in which case the match
413:match the test value. 'ignore-blanks' takes a boolean value. if 'ignore-blanks' is set "true", any blanks in the string will be ignored on its comparison. this takes effects only when compare="eq" or compare="not_eq".
449:zero for purely fractional values (e.g. use 0.5 instead of .5 and -0.5
471:the pattern. If the 'target' attribute is not present, it will default to
474:match. The attribute can also take the values 'font' or 'pattern' to
476:of 'font' in a match that has target="pattern".
584: Accept deprecated 'mono' alias, replacing it with 'monospace'
596: Names not including any well known alias are given 'sans-serif'
687: If the 'family' contains 'Courier New' OR 'Courier'
688: add 'monospace' as the alternative
-.-.
Name of a manual is set in bold, the section in roman.
See man-pages(7).
830:is used to control the use of mmap(2) for the cache files if available. this take a boolean value. fontconfig will checks if the cache files are stored on the filesystem that is safe to use mmap(2). explicitly setting this environment variable will causes skipping this check and enforce to use or not use mmap(2) anyway.
-.-.
Show if docman-to-man created this
1:.\" auto-generated by docbook2man-spec from docbook-utils package
-.-.
point size: the typographical term is 'type size'. There exist
several point sizes, like 'Didot point', 'big point' (PostScript point),
and 'pica point' (printer's point, English, USA).
70:size Double Point size
182:list of family names, second a list of point sizes and finally a list of
186:<families>-<point sizes>:<name1>=<values1>:<name2>=<values2>\&...
192:families or point sizes; they can be elided. In addition, there are
-.-.
Change a HYPHEN-MINUS (code 0x55, 2D) to a dash
(\-, minus) if it matches "[[:alph:]]-[[:alpha:]]" in the name of an
option).
Facilitates the copy and paste of an option in UTF-8 text.
Is not needed in ordinary words like "mother-in-law", that are not
copied and pasted to a command line (which needs ASCII code)
836:fc-cat(1), fc-cache(1), fc-list(1), fc-match(1), fc-query(1), SOURCE_DATE_EPOCH <URL:https://reproducible-builds.org/specs/source-date-epoch/>\&.
-.-.
Output from "test-groff -b -mandoc -rF0 -rHY=0 -K utf8 -t -ww -z ":
troff: backtrace: '<stdin>':2: string 'an-extra1'
troff: backtrace: '/home/bg/git/groff/build/s-tmac/an.tmac':221: string 'TH'
troff: backtrace: '/home/bg/git/groff/build/s-tmac/andoc.tmac':46: macro 'TH'
troff: backtrace: file '<stdin>':2
troff:<stdin>:2: warning: special character 'u6708' not defined
This is a part of a date and therefore should be coded in ASCII.
-------------- next part --------------
--- fonts-conf.5 2024-06-09 15:01:24.755483788 +0000
+++ fonts-conf.5.new 2024-06-09 16:46:59.576031220 +0000
@@ -3,7 +3,6 @@
.SH NAME
fonts.conf \- Font configuration files
.SH SYNOPSIS
-.sp
.nf
/etc/fonts/fonts.conf
/etc/fonts/fonts.dtd
@@ -15,16 +14,13 @@ fonts.conf \- Font configuration files
.sp
.fi
.SH "DESCRIPTION"
-.PP
Fontconfig is a library designed to provide system-wide font configuration,
customization and application access.
.SH "FUNCTIONAL OVERVIEW"
-.PP
Fontconfig contains two essential modules, the configuration module which
builds an internal configuration from XML files and the matching module
which accepts font patterns and returns the nearest matching font.
.SS "FONT CONFIGURATION"
-.PP
The configuration module consists of the FcConfig datatype, libexpat and
FcConfigParse which walks over an XML tree and amends a configuration with
data found within. From an external perspective, configuration of the
@@ -49,7 +45,6 @@ is that this will ensure that configurat
can be centralized in one place. Centralizing font configuration will
simplify and regularize font installation and customization.
.SS "FONT PROPERTIES"
-.PP
While font patterns may contain essentially any properties, there are some
well known properties with associated types. Fontconfig uses some of these
properties for font matching and font completion. Others are provided as a
@@ -60,14 +55,14 @@ Property Type Description
--------------------------------------------------------------
family String Font family names
familylang String Languages corresponding to each family
-style String Font style. Overrides weight and slant
+style String Font style. Overrides weight and slant
stylelang String Languages corresponding to each style
fullname String Font full names (often includes style)
fullnamelang String Languages corresponding to each fullname
slant Int Italic, oblique or roman
weight Int Light, medium, demibold, bold or black
width Int Condensed, normal or expanded
-size Double Point size
+size Double Type size
aspect Double Stretches glyphs horizontally before hinting
pixelsize Double Pixel size
spacing Int Proportional, dual-width, monospace or charcell
@@ -86,7 +81,7 @@ outline Bool Whether the glyp
scalable Bool Whether the glyphs are outlines or have color
dpi Double Target dots per inch
rgba Int unknown, rgb, bgr, vrgb, vbgr,
- none - subpixel geometry
+ none \(en subpixel geometry
scale Double Scale factor for point->pixel conversions
(deprecated)
minspace Bool Eliminate leading from line spacing
@@ -116,11 +111,10 @@ namedinstance Bool Whether font is
fontwarapper String The font wrapper format, current values are WOFF, WOFF2,
SFNT for any other SFNT font, and CFF for standalone
CFF fonts.
-
+
.sp
.fi
.SS "FONT MATCHING"
-.PP
Fontconfig performs matching by measuring the distance from a provided
pattern to all of the available fonts in the system. The closest matching
font is selected. This ensures that a font will always be returned, but
@@ -147,7 +141,7 @@ The canonical font pattern is finally ma
The distance from the pattern to the font is measured for each of several
properties: foundry, charset, family, lang, spacing, pixelsize, style,
slant, weight, antialias, rasterizer and outline. This list is in priority
-order -- results of comparing earlier elements of this list weigh more
+order \(en results of comparing earlier elements of this list weigh more
heavily than later elements.
.PP
There is one special case to this rule; family names are split into two
@@ -170,26 +164,25 @@ applications are free to use any rasteri
the identified font file and access it directly.
.PP
The match/edit sequences in the configuration are performed in two passes
-because there are essentially two different operations necessary -- the
+because there are essentially two different operations necessary \(en the
first is to modify how fonts are selected; aliasing families and adding
suitable defaults. The second is to modify how the selected fonts are
rasterized. Those must apply to the selected font, not the original pattern
as false matches will often occur.
.SS "FONT NAMES"
-.PP
Fontconfig provides a textual representation for patterns that the library
can both accept and generate. The representation is in three parts, first a
-list of family names, second a list of point sizes and finally a list of
+list of family names, second a list of type sizes and finally a list of
additional properties:
.sp
.nf
-<families>-<point sizes>:<name1>=<values1>:<name2>=<values2>\&...
-
+<families>\-<type sizes>:<name1>=<values1>:<name2>=<values2>...
+
.sp
.fi
.PP
Values in a list are separated with commas. The name needn't include either
-families or point sizes; they can be elided. In addition, there are
+families or type sizes; they can be elided. In addition, there are
symbolic constants that simultaneously indicate both a name and a value.
Here are some examples:
.sp
@@ -199,19 +192,19 @@ Name Meaning
Times-12 12 point Times Roman
Times-12:bold 12 point Times Bold
Courier:italic Courier Italic in the default size
-Monospace:matrix=1 .1 0 1 The users preferred monospace font
+Monospace:matrix=1 0.1 0 1 The users preferred monospace font
with artificial obliquing
-
+
.sp
.fi
.PP
-The '\\', '-', ':' and ',' characters in family names must be preceded by a
-\&'\\' character to avoid having them misinterpreted. Similarly, values
-containing '\\', '=', '_', ':' and ',' must also have them preceded by a
-\&'\\' character. The '\\' characters are stripped out of the family name and
+The \&'\e', \&'\-', \&':' and \&',' characters in family names must be
+preceded by a \&'\e' character to avoid having them misinterpreted.
+Similarly, values containing \&'\e', \&'=', \&'_', \&':' and \&',' must also
+have them preceded by a \&'\e' character.
+The \&'\e' characters are stripped out of the family name and
values as the font name is read.
.SH "DEBUGGING APPLICATIONS"
-.PP
To help diagnose font and applications problems, fontconfig is built with a
large amount of internal debugging left enabled. It is controlled by means
of the FC_DEBUG environment variable. The value of this variable is
@@ -234,7 +227,7 @@ MEMORY 512 Monitor fontconfig
CONFIG 1024 Monitor which config files are loaded
LANGSET 2048 Dump char sets used to construct lang values
MATCH2 4096 Display font-matching transformation in patterns
-
+
.sp
.fi
.PP
@@ -242,11 +235,10 @@ Add the value of the desired debug level
base 10) to the FC_DEBUG environment variable before running the
application. Output from these statements is sent to stdout.
.SH "LANG TAGS"
-.PP
Each font in the database contains a list of languages it supports. This is
computed by comparing the Unicode coverage of the font with the orthography
of each language. Languages are tagged using an RFC-3066 compatible naming
-and occur in two parts -- the ISO 639 language tag followed a hyphen and then
+and occur in two parts \(en the ISO 639 language tag followed a hyphen and then
by the ISO 3166 country code. The hyphen and country code may be elided.
.PP
Fontconfig has orthographies for several languages built into the library.
@@ -260,7 +252,6 @@ For languages used in multiple territori
character sets, fontconfig includes per-territory orthographies. This
includes Azerbaijani, Kurdish, Pashto, Tigrinya and Chinese.
.SH "CONFIGURATION FILE FORMAT"
-.PP
Configuration files for fontconfig are stored in XML format; this
format makes external configuration tools easier to write and ensures that
they will generate syntactically correct configuration files. As XML
@@ -276,111 +267,120 @@ following structure:
<?xml version="1.0"?>
<!DOCTYPE fontconfig SYSTEM "urn:fontconfig:fonts.dtd">
<fontconfig>
-\&...
+\&...\&
</fontconfig>
-
+
.sp
.fi
.SS "<FONTCONFIG>"
-.PP
This is the top level element for a font configuration and can contain
<dir>, <cachedir>, <include>, <match> and <alias> elements in any order.
.SS "<DIR PREFIX=""DEFAULT"" SALT="""">"
-.PP
This element contains a directory name which will be scanned for font files
to include in the set of available fonts.
.PP
-If 'prefix' is set to "default" or "cwd", the current working directory will be added as the path prefix prior to the value. If 'prefix' is set to "xdg", the value in the XDG_DATA_HOME environment variable will be added as the path prefix. please see XDG Base Directory Specification for more details. If 'prefix' is set to "relative", the path of current file will be added prior to the value.
+If \&'prefix' is set to "default" or "cwd",
+the current working directory will be added as the path prefix prior to the
+value.
+If \&'prefix' is set to "xdg",
+the value in the XDG_DATA_HOME environment variable will be added as the path
+prefix.
+Please see XDG Base Directory Specification for more details.
+If \&'prefix' is set to "relative",
+the path of current file will be added prior to the value.
.PP
-\&'salt' property affects to determine cache filename. this is useful for example when having different fonts sets on same path at container and share fonts from host on different font path.
+\&'salt' property affects to determine cache filename.
+This is useful for example when having different fonts sets on same path at
+container
+and share fonts from host on different font path.
.SS "<CACHEDIR PREFIX=""DEFAULT"">"
-.PP
This element contains a directory name that is supposed to be stored or read
-the cache of font information. If multiple elements are specified in
-the configuration file, the directory that can be accessed first in the list
-will be used to store the cache files. If it starts with '~', it refers to
-a directory in the users home directory. If 'prefix' is set to "xdg", the value in the XDG_CACHE_HOME environment variable will be added as the path prefix. please see XDG Base Directory Specification for more details.
-The default directory is ``$XDG_CACHE_HOME/fontconfig'' and it contains the cache files
-named ``<hash value>-<architecture>\&.cache-<version>\&'',
-where <version> is the fontconfig cache file
-version number (currently 8).
+the cache of font information.
+If multiple elements are specified in the configuration file,
+the directory that can be accessed first in the list
+will be used to store the cache files.
+If it starts with \&'~', it refers to a directory in the users home directory.
+If \&'prefix' is set to "xdg",
+the value in the XDG_CACHE_HOME environment variable will be added as the path
+prefix.
+Please see XDG Base Directory Specification for more details.
+The default directory is ``$XDG_CACHE_HOME/fontconfig'' and it contains the
+cache files named ``<hash value>\-<architecture>.cache-<version>\&'',
+where <version> is the fontconfig cache file version number (currently 8).
.SS "<INCLUDE IGNORE_MISSING=""NO"" PREFIX=""DEFAULT"">"
-.PP
This element contains the name of an additional configuration file or
directory. If a directory, every file within that directory starting with an
-ASCII digit (U+0030 - U+0039) and ending with the string ``.conf'' will be processed in sorted order. When
-the XML datatype is traversed by FcConfigParse, the contents of the file(s)
+ASCII digit (U+0030 \(en U+0039) and ending with the string ``.conf'' will
+be processed in sorted order.
+When the XML datatype is traversed by FcConfigParse,
+the contents of the file(s)
will also be incorporated into the configuration by passing the filename(s) to
-FcConfigLoadAndParse. If 'ignore_missing' is set to "yes" instead of the
+FcConfigLoadAndParse. If \&'ignore_missing' is set to "yes" instead of the
default "no", a missing file or directory will elicit no warning message from
-the library. If 'prefix' is set to "xdg", the value in the XDG_CONFIG_HOME environment variable will be added as the path prefix. please see XDG Base Directory Specification for more details.
+the library.
+If \&'prefix' is set to "xdg",
+the value in the XDG_CONFIG_HOME environment variable will be added as the path
+prefix.
+Please see XDG Base Directory Specification for more details.
.SS "<CONFIG>"
-.PP
This element provides a place to consolidate additional configuration
-information. <config> can contain <blank> and <rescan> elements in any
-order.
+information.
+<config> can contain <blank> and <rescan> elements in any order.
.SS "<DESCRIPTION DOMAIN=""FONTCONFIG-CONF"">"
-.PP
-This element is supposed to hold strings which describe what a config is used for.
-This string can be translated through gettext. 'domain' needs to be set the proper name to apply then.
-fontconfig will tries to retrieve translations with 'domain' from gettext.
+This element is supposed to hold strings which describe what a config is
+used for.
+This string can be translated through gettext.
+\&'domain' needs to be set the proper name to apply then.
+fontconfig will tries to retrieve translations with \&'domain' from gettext.
.SS "<BLANK>"
-.PP
Fonts often include "broken" glyphs which appear in the encoding but are
drawn as blanks on the screen. Within the <blank> element, place each
Unicode characters which is supposed to be blank in an <int> element.
Characters outside of this set which are drawn as blank will be elided from
the set of characters supported by the font.
.SS "<REMAP-DIR PREFIX=""DEFAULT"" AS-PATH="""" SALT="""">"
-.PP
This element contains a directory name where will be mapped
-as the path 'as-path' in cached information.
+as the path \&'as-path' in cached information.
This is useful if the directory name is an alias
(via a bind mount or symlink) to another directory in the system for
which cached font information is likely to exist.
.PP
\&'salt' property affects to determine cache filename as same as <dir> element.
.SS "<RESET-DIRS />"
-.PP
This element removes all of fonts directories where added by <dir> elements.
-This is useful to override fonts directories from system to own fonts directories only.
+This is useful to override fonts directories from system to own fonts
+directories only.
.SS "<RESCAN>"
-.PP
The <rescan> element holds an <int> element which indicates the default
interval between automatic checks for font configuration changes.
Fontconfig will validate all of the configuration files and directories and
automatically rebuild the internal datastructures when this interval passes.
.SS "<SELECTFONT>"
-.PP
This element is used to deny/allow list fonts from being listed or matched
against. It holds acceptfont and rejectfont elements. This list is applied
only once when caches is loaded. So if you want to filter out by some patterns,
patterns is evaluated with something in cache only.
In other words, target patterns except "scan" won't takes any effects.
.SS "<ACCEPTFONT>"
-.PP
Fonts matched by an acceptfont element are "allowlisted"; such fonts are
explicitly included in the set of fonts used to resolve list and match
requests; including them in this list protects them from being "denylisted"
by a rejectfont element. Acceptfont elements include glob and pattern
elements which are used to match fonts.
.SS "<REJECTFONT>"
-.PP
Fonts matched by an rejectfont element are "denylisted"; such fonts are
excluded from the set of fonts used to resolve list and match requests as if
they didn't exist in the system. Rejectfont elements include glob and
pattern elements which are used to match fonts.
.SS "<GLOB>"
-.PP
Glob elements hold shell-style filename matching patterns (including ? and
-*) which match fonts based on their complete pathnames. If it starts with '~',
+*) which match fonts based on their complete pathnames. If it starts with \&'~',
it refers to a directory in the users home directory. This can be used to
exclude a set of directories (/usr/share/fonts/uglyfont*), or particular
font file types (*.pcf.gz), but the latter mechanism relies rather heavily
on filenaming conventions which can't be relied upon. Note that globs
only apply to directories, not to individual fonts.
.SS "<PATTERN>"
-.PP
Pattern elements perform list-style matching on incoming fonts; that is,
they hold a list of elements and associated values. If all of those
elements have a matching value, then the pattern matches the font. This can
@@ -388,35 +388,38 @@ be used to select fonts based on attribu
etc), which is a more reliable mechanism than using file extensions.
Pattern elements include patelt elements.
.SS "<PATELT NAME=""PROPERTY"">"
-.PP
Patelt elements hold a single pattern element and list of values. They must
-have a 'name' attribute which indicates the pattern element name. Patelt
+have a \&'name' attribute which indicates the pattern element name. Patelt
elements include int, double, string, matrix, bool, charset and const
elements.
.SS "<MATCH TARGET=""PATTERN"">"
-.PP
This element holds first a (possibly empty) list of <test> elements and then
a (possibly empty) list of <edit> elements. Patterns which match all of the
-tests are subjected to all the edits. If 'target' is set to "font" instead
+tests are subjected to all the edits. If \&'target' is set to "font" instead
of the default "pattern", then this element applies to the font name
-resulting from a match rather than a font pattern to be matched. If 'target'
+resulting from a match rather than a font pattern to be matched. If \&'target'
is set to "scan", then this element applies when the font is scanned to
build the fontconfig database.
.SS "<TEST QUAL=""ANY"" NAME=""PROPERTY"" TARGET=""DEFAULT"" COMPARE=""EQ"">"
-.PP
This element contains a single value which is compared with the target
-('pattern', 'font', 'scan' or 'default') property "property" (substitute any of the property names seen
-above). 'compare' can be one of "eq", "not_eq", "less", "less_eq", "more", "more_eq", "contains" or
-"not_contains". 'qual' may either be the default, "any", in which case the match
+('pattern', \&'font', \&'scan' or \&'default') property "property"
+(substitute any of the property names seen above).
+\&'compare' can be one of "eq", "not_eq", "less", "less_eq", "more",
+"more_eq", "contains" or "not_contains".
+\&'qual' may either be the default, "any", in which case the match
succeeds if any value associated with the property matches the test value, or
"all", in which case all of the values associated with the property must
-match the test value. 'ignore-blanks' takes a boolean value. if 'ignore-blanks' is set "true", any blanks in the string will be ignored on its comparison. this takes effects only when compare="eq" or compare="not_eq".
+match the test value.
+\&'ignore-blanks' takes a boolean value.
+If \&'ignore-blanks' is set "true",
+any blanks in the string will be ignored on its comparison.
+This takes effects only when compare="eq" or
+compare="not_eq".
When used in a <match target="font"> element,
the target= attribute in the <test> element selects between matching
-the original pattern or the font. "default" selects whichever target the
-outer <match> element has selected.
+the original pattern or the font.
+"default" selects whichever target the outer <match> element has selected.
.SS "<EDIT NAME=""PROPERTY"" MODE=""ASSIGN"" BINDING=""WEAK"">"
-.PP
This element contains a list of expression elements (any of the value or
operator elements). The expression elements are evaluated at run-time and
modify the property "property". The modification depends on whether
@@ -437,45 +440,39 @@ Mode With Match
"append_last" Append at end of list Append at end of list
"delete" Delete matching value Delete all values
"delete_all" Delete all values Delete all values
-
+
.sp
.fi
.SS "<INT>, <DOUBLE>, <STRING>, <BOOL>"
-.PP
-These elements hold a single value of the indicated type. <bool>
-elements hold either true or false. An important limitation exists in
-the parsing of floating point numbers -- fontconfig requires that
+These elements hold a single value of the indicated type.
+<bool> elements hold either true or false.
+An important limitation exists in
+the parsing of floating point numbers \(en fontconfig requires that
the mantissa start with a digit, not a decimal point, so insert a leading
-zero for purely fractional values (e.g. use 0.5 instead of .5 and -0.5
-instead of -.5).
+zero for purely fractional values (e.g., use 0.5 instead of \&.5 and \-0.5
+instead of \-.5).
.SS "<MATRIX>"
-.PP
This element holds four numerical expressions of an affine transformation.
At their simplest these will be four <double> elements
but they can also be more involved expressions.
.SS "<RANGE>"
-.PP
This element holds the two <int> elements of a range
representation.
.SS "<CHARSET>"
-.PP
This element holds at least one <int> element of
an Unicode code point or more.
.SS "<LANGSET>"
-.PP
This element holds at least one <string> element of
a RFC-3066-style languages or more.
.SS "<NAME>"
-.PP
Holds a property name. Evaluates to the first value from the property of
-the pattern. If the 'target' attribute is not present, it will default to
+the pattern. If the \&'target' attribute is not present, it will default to
\&'default', in which case the property is returned from the font pattern
during a target="font" match, and to the pattern during a target="pattern"
-match. The attribute can also take the values 'font' or 'pattern' to
+match. The attribute can also take the values \&'font' or \&'pattern' to
explicitly choose which pattern to use. It is an error to use a target
-of 'font' in a match that has target="pattern".
+of \&'font' in a match that has target="pattern".
.SS "<CONST>"
-.PP
Holds the name of a constant; these are always integers and serve as
symbolic names for common font values:
.sp
@@ -531,26 +528,23 @@ hintnone hintstyle 0
hintslight hintstyle 1
hintmedium hintstyle 2
hintfull hintstyle 3
-
+
.sp
.fi
.SS "<OR>, <AND>, <PLUS>, <MINUS>, <TIMES>, <DIVIDE>"
-.PP
These elements perform the specified operation on a list of expression
-elements. <or> and <and> are boolean, not bitwise.
-.SS "<EQ>, <NOT_EQ>, <LESS>, <LESS_EQ>, <MORE>, <MORE_EQ>, <CONTAINS>, <NOT_CONTAINS"
-.PP
+elements.
+<or> and <and> are boolean, not bitwise.
+.SS "<EQ>, <NOT_EQ>, <LESS>, <LESS_EQ>, <MORE>, <MORE_EQ>, <CONTAINS>, \
+<NOT_CONTAINS"
These elements compare two values, producing a boolean result.
.SS "<NOT>"
-.PP
Inverts the boolean sense of its one expression element
.SS "<IF>"
-.PP
This element takes three expression elements; if the value of the first is
true, it produces the value of the second, otherwise it produces the value
of the third.
.SS "<ALIAS>"
-.PP
Alias elements provide a shorthand notation for the set of common match
operations needed to substitute one font family for another. They contain a
<family> element followed by optional <prefer>, <accept> and <default>
@@ -559,30 +553,27 @@ list of <prefer>ed families before the m
<accept>able families after the matching <family> and append the <default>
families to the end of the family list.
.SS "<FAMILY>"
-.PP
Holds a single font family name
.SS "<PREFER>, <ACCEPT>, <DEFAULT>"
-.PP
These hold a list of <family> elements to be used by the <alias> element.
.SH "EXAMPLE CONFIGURATION FILE"
.SS "SYSTEM CONFIGURATION FILE"
-.PP
This is an example of a system-wide configuration file
.sp
.nf
<?xml version="1.0"?>
<!DOCTYPE fontconfig SYSTEM "urn:fontconfig:fonts.dtd">
-<!-- /etc/fonts/fonts.conf file to configure system font access -->
+<!\-\- /etc/fonts/fonts.conf file to configure system font access \-\->
<fontconfig>
- <!--
+ <!\-\-
Find fonts in these directories
- -->
+ \-\->
<dir>/usr/share/fonts</dir>
<dir>/usr/X11R6/lib/X11/fonts</dir>
- <!--
- Accept deprecated 'mono' alias, replacing it with 'monospace'
- -->
+ <!\-\-
+ Accept deprecated \&'mono' alias, replacing it with \&'monospace'
+ \-\->
<match target="pattern">
<test qual="any" name="family">
<string>mono</string>
@@ -592,9 +583,9 @@ This is an example of a system-wide conf
</edit>
</match>
- <!--
- Names not including any well known alias are given 'sans-serif'
- -->
+ <!\-\-
+ Names not including any well known alias are given \&'sans-serif'
+ \-\->
<match target="pattern">
<test qual="all" name="family" compare="not_eq">
<string>sans-serif</string>
@@ -610,26 +601,26 @@ This is an example of a system-wide conf
</edit>
</match>
- <!--
+ <!\-\-
Load per-user customization file, but don't complain
if it doesn't exist
- -->
+ \-\->
<include ignore_missing="yes" prefix="xdg">
fontconfig/fonts.conf
</include>
- <!--
+ <!\-\-
Load local customization files, but don't complain
if there aren't any
- -->
+ \-\->
<include ignore_missing="yes">conf.d</include>
<include ignore_missing="yes">local.conf</include>
- <!--
+ <!\-\-
Alias well known font names to available TrueType fonts.
These substitute TrueType faces for similar Type1
faces to improve screen appearance.
- -->
+ \-\->
<alias>
<family>Times</family>
<prefer>
@@ -658,11 +649,11 @@ This is an example of a system-wide conf
</default>
</alias>
- <!--
+ <!\-\-
Provide required aliases for standard names
Do these after the users configuration file so that
any aliases there are used preferentially
- -->
+ \-\->
<alias>
<family>serif</family>
<prefer>
@@ -682,11 +673,11 @@ This is an example of a system-wide conf
</prefer>
</alias>
- <--
+ <\-\-
The example of the requirements of OR operator;
- If the 'family' contains 'Courier New' OR 'Courier'
- add 'monospace' as the alternative
- -->
+ If the \&'family' contains \&'Courier New' OR \&'Courier'
+ add \&'monospace' as the alternative
+ \-\->
<match target="pattern">
<test name="family" compare="eq">
<string>Courier New</string>
@@ -705,48 +696,47 @@ This is an example of a system-wide conf
</match>
</fontconfig>
-
+
.sp
.fi
.SS "USER CONFIGURATION FILE"
-.PP
This is an example of a per-user configuration file that lives in
$XDG_CONFIG_HOME/fontconfig/fonts.conf
.sp
.nf
<?xml version="1.0"?>
<!DOCTYPE fontconfig SYSTEM "urn:fontconfig:fonts.dtd">
-<!--
+<!\-\-
$XDG_CONFIG_HOME/fontconfig/fonts.conf for per-user font configuration
--->
+\-\->
<fontconfig>
- <!--
+ <!\-\-
Private font directory
- -->
+ \-\->
<dir prefix="xdg">fonts</dir>
- <!--
+ <!\-\-
use rgb sub-pixel ordering to improve glyph appearance on
LCD screens. Changes affecting rendering, but not matching
should always use target="font".
- -->
+ \-\->
<match target="font">
<edit name="rgba" mode="assign">
<const>rgb</const>
</edit>
</match>
- <!--
+ <!\-\-
use WenQuanYi Zen Hei font when serif is requested for Chinese
- -->
+ \-\->
<match>
- <!--
+ <!\-\-
If you don't want to use WenQuanYi Zen Hei font for zh-tw etc,
you can use zh-cn instead of zh.
Please note, even if you set zh-cn, it still matches zh.
if you don't like it, you can use compare="eq"
instead of compare="contains".
- -->
+ \-\->
<test name="lang" compare="contains">
<string>zh</string>
</test>
@@ -757,9 +747,9 @@ $XDG_CONFIG_HOME/fontconfig/fonts.conf
<string>WenQuanYi Zen Hei</string>
</edit>
</match>
- <!--
+ <!\-\-
use VL Gothic font when sans-serif is requested for Japanese
- -->
+ \-\->
<match>
<test name="lang" compare="contains">
<string>ja</string>
@@ -772,11 +762,10 @@ $XDG_CONFIG_HOME/fontconfig/fonts.conf
</edit>
</match>
</fontconfig>
-
+
.sp
.fi
.SH "FILES"
-.PP
\fBfonts.conf\fR
contains configuration information for the fontconfig library
consisting of directories to look at for font information as well as
@@ -797,17 +786,23 @@ is a DTD that describes the format of th
\fB$XDG_CONFIG_HOME/fontconfig/conf.d\fR and \fB~/.fonts.conf.d\fR
is the conventional name for a per-user directory of (typically
auto-generated) configuration files, although the
-actual location is specified in the global fonts.conf file. please note that ~/.fonts.conf.d is deprecated now. it will not be read by default in the future version.
+actual location is specified in the global fonts.conf file.
+Please note that ~/.fonts.conf.d is deprecated now.
+It will not be read by default in the future version.
.PP
\fB$XDG_CONFIG_HOME/fontconfig/fonts.conf\fR and \fB~/.fonts.conf\fR
is the conventional location for per-user font configuration, although the
-actual location is specified in the global fonts.conf file. please note that ~/.fonts.conf is deprecated now. it will not be read by default in the future version.
+actual location is specified in the global fonts.conf file.
+Please note that ~/.fonts.conf is deprecated now.
+It will not be read by default in the future version.
.PP
\fB$XDG_CACHE_HOME/fontconfig/*.cache-*\fR and \fB ~/.fontconfig/*.cache-*\fR
is the conventional repository of font information that isn't found in the
-per-directory caches. This file is automatically maintained by fontconfig. please note that ~/.fontconfig/*.cache-* is deprecated now. it will not be read by default in the future version.
+per-directory caches.
+This file is automatically maintained by fontconfig.
+Please note that ~/.fontconfig/*.cache-* is deprecated now.
+It will not be read by default in the future version.
.SH "ENVIRONMENT VARIABLES"
-.PP
\fBFONTCONFIG_FILE\fR
is used to override the default configuration file.
.PP
@@ -818,22 +813,41 @@ is used to override the default configur
is used to set a default sysroot directory.
.PP
\fBFC_DEBUG\fR
-is used to output the detailed debugging messages. see Debugging Applications section for more details.
+is used to output the detailed debugging messages.
+See Debugging Applications section for more details.
.PP
\fBFC_DBG_MATCH_FILTER\fR
-is used to filter out the patterns. this takes a comma-separated list of object names and effects only when FC_DEBUG has MATCH2. see Debugging Applications section for more details.
+is used to filter out the patterns.
+This takes a comma-separated list of object names and effects only when
+FC_DEBUG has MATCH2.
+See Debugging Applications section for more details.
.PP
\fBFC_LANG\fR
-is used to specify the default language as the weak binding in the query. if this isn't set, the default language will be determined from current locale.
+is used to specify the default language as the weak binding in the query.
+If this isn't set, the default language will be determined from current locale.
.PP
\fBFONTCONFIG_USE_MMAP\fR
-is used to control the use of mmap(2) for the cache files if available. this take a boolean value. fontconfig will checks if the cache files are stored on the filesystem that is safe to use mmap(2). explicitly setting this environment variable will causes skipping this check and enforce to use or not use mmap(2) anyway.
+is used to control the use of
+.BR mmap (2)
+for the cache files if available.
+This takes a boolean value.
+fontconfig will check if the cache files are stored on the filesystem that
+is safe to use
+.BR mmap (2).
+explicitly setting this environment variable will
+causes skipping this check and enforce to use or not use mmap(2) anyway.
.PP
\fBSOURCE_DATE_EPOCH\fR
-is used to ensure fc-cache(1) generates files in a deterministic manner in order to support reproducible builds. When set to a numeric representation of UNIX timestamp, fontconfig will prefer this value over using the modification timestamps of the input files in order to identify which cache files require regeneration. If SOURCE_DATE_EPOCH is not set (or is newer than the mtime of the directory), the existing behaviour is unchanged.
+is used to ensure fc-cache(1) generates files in a deterministic manner in
+order to support reproducible builds.
+When set to a numeric representation of UNIX timestamp,
+fontconfig will prefer this value over using the modification timestamps of
+the input files in order to identify which cache files require regeneration.
+If SOURCE_DATE_EPOCH is not set (or is newer than the mtime of the directory),
+the existing behaviour is unchanged.
.SH "SEE ALSO"
-.PP
-fc-cat(1), fc-cache(1), fc-list(1), fc-match(1), fc-query(1), SOURCE_DATE_EPOCH <URL:https://reproducible-builds.org/specs/source-date-epoch/>\&.
+fc\-cat(1), fc\-cache(1), fc\-list(1), fc\-match(1), fc\-query(1),
+SOURCE_DATE_EPOCH
+<URL:https://reproducible\-builds.org/specs/source\-date\-epoch/>.
.SH "VERSION"
-.PP
Fontconfig version 2.15.0
More information about the Pkg-freedesktop-maintainers
mailing list