commit: 0dc114365e5e42c97d0f5afeb6155a6e6e5836b7 Author: Kerin Millar <kfm <AT> plushkava <DOT> net> AuthorDate: Tue Jan 13 21:50:39 2026 +0000 Commit: Kerin Millar <kfm <AT> plushkava <DOT> net> CommitDate: Tue Jan 13 22:01:15 2026 +0000 URL: https://gitweb.gentoo.org/proj/locale-gen.git/commit/?id=0dc11436
Improve the hyphenation/wrapping of man pages Presently, the way in which troff(1) hyphenates and reflows the man pages is aesthetically displeasing. This becomes especially apparent where the number of available columns is low. Address this issue by better making use of the \% and \: escape sequences provided by groff(1). The exact nature of the changes is described herewith. Use \% to prevent several terms from being hyphenated. Examples of these include \fI%config\fR, \fI%localename\fR and \fI%charmap\fR, as well as the references to other man pages. Treat the "locale-gen" term similarly but allow for it to be hyphenated in accordance with where its <hyphen-minus> character is situated. Permit wrapping after the directory portions of pathnames, without rendering any hyphens. For instance, /usr/share/i18n/SUPPORTED can potentially be rendered as: /usr/share/i18n/ SUPPORTED Permit wrapping after the underscore characters of environment variable names, without rendering any hyphens. For example, LOCALEGEN_ALLOW_UNSUPPORTED can potentially be rendered as: LOCALEGEN_ ALLOW_ UNSUPPORTED Permit wrapping after the scheme and hostname portions of URLs, along with any of the components of its path, without rendering any hyphens. For example, https://pubs.opengroup.org/onlinepubs/009656599/toc.pdf can potentially be rendered as: https:// pubs.opengroup.org/ onlinepubs/ 009656599/ toc.pdf Signed-off-by: Kerin Millar <kfm <AT> plushkava.net> locale-gen.8 | 46 +++++++++++++++++++++++----------------------- locale.gen.5 | 42 +++++++++++++++++++++--------------------- 2 files changed, 44 insertions(+), 44 deletions(-) diff --git a/locale-gen.8 b/locale-gen.8 index bc59a91..818d4f1 100644 --- a/locale-gen.8 +++ b/locale-gen.8 @@ -20,25 +20,25 @@ locale-gen \[em] safely compile and install a glibc locale archive .B -V .YS .SH "DESCRIPTION" -The locale-gen utility provides a means by which a system administrator may conveniently manage the set of locales that are made available to the GNU C Library. It accomplishes this by acting as a user-friendly frontend for the \fBlocaledef\fR(1) utility, which is used to compile locales and integrate them into a central archive. +The \%locale-\:\%gen utility provides a means by which a system administrator may conveniently manage the set of locales that are made available to the GNU C Library. It accomplishes this by acting as a user-friendly frontend for the \fB\%localedef\fR(1) utility, which is used to compile locales and integrate them into a central archive. .P -By default, locale-gen generates an archive containing a full complement of supported locales, numbering 500 or more. However, it is typical for an administrator to require only a few of them. In that case, the \fIconfig\fR file may be populated with a list of the required locales. Consequently, locale-gen shall compile only those, saving both time and space in the longer term. +By default, \%locale-\:\%gen generates an archive containing a full complement of supported locales, numbering 500 or more. However, it is typical for an administrator to require only a few of them. In that case, the \fIconfig\fR file may be populated with a list of the required locales. Consequently, \%locale-\:\%gen shall compile only those, saving both time and space in the longer term. .SH "OPTIONS" .TP \fB-A\fR, \fB--all\fR Compile all locales that are officially supported by glibc. Cannot be combined with the \fB-c\fR option. .TP \fB-c\fR, \fB--config\fR \fIconfig\fR -Read the given \fIconfig\fR file (defaults to \fIprefix\fR/etc/locale.gen). If specified as a \%<hyphen-minus>, the configuration shall be read from standard input. If the file contains no locales or is missing, locale-gen shall act as if the \fB-A\fR option had been specified. +Read the given \fI\%config\fR file (defaults to \fI\%prefix\fR/\:\%etc/\:\%locale.gen). If specified as a <hyphen-minus>, the configuration shall be read from standard input. If the file contains no locales or is missing, \%locale-\:\%gen shall act as if the \fB-A\fR option had been specified. .TP \fB-h\fR, \fB--help\fR Write out a synopsis and summary of the supported options then exit. .TP \fB-j\fR, \fB--jobs\fR \fIjobs\fR -Spawn up to the specified number of \fIjobs\fR to compile locales in parallel (defaults to the number of logical processors). +Spawn up to the specified number of \fI\%jobs\fR to compile locales in parallel (defaults to the number of logical processors). .TP \fB-p\fR, \fB--prefix\fR \fIprefix\fR -Treat FILES as being relative to the specified \fIprefix\fR (defaults to / if not a Gentoo Prefix system). Where explicitly specified, the \fIconfig\fR file shall be exempted from this behaviour. +Treat \%FILES as being relative to the specified \fI\%prefix\fR (defaults to / if not a Gentoo Prefix system). Where explicitly specified, the \fI\%config\fR file shall be exempted from this behaviour. .TP \fB-q\fR, \fB--quiet\fR Suppress the writing of informational messages to standard output. @@ -50,29 +50,29 @@ Suppress the compilation of locales that are already installed (not recommended) Write out some details regarding the program then exit. .SH "FILES" .TP -.I /etc/locale.gen -The default location of the \fIconfig\fR file. It specifies the locales to be compiled. +.I \%/etc/\:\%locale.gen +The default location of the \fI\%config\fR file. It specifies the locales to be compiled. .TP -.I /usr/share/i18n/SUPPORTED +.I \%/usr/share/i18n/\:\%SUPPORTED A complete list of valid locale declarations, as provided by glibc. .TP -.I /usr/lib/locale/locale-archive +.I \%/usr/lib/locale/\:\%locale-archive Contains the currently installed locales. .TP -.I /usr/share/i18n/locales -Contains locale definition files that serve as inputs to \fBlocaledef\fR(1). +.I \%/usr/share/i18n/\:\%locales +Contains locale definition files that serve as inputs to \fB\%localedef\fR(1). .TP -.I /usr/share/i18n/charmaps -Contains character map files that serve as inputs to \fBlocaledef\fR(1). +.I \%/usr/share/i18n/\:\%charmaps +Contains character map files that serve as inputs to \fB\%localedef\fR(1). .SH "ENVIRONMENT" .TP -LOCALEGEN_ALLOW_UNSUPPORTED -If set as a non-empty string, locale-gen shall convey validation errors as warnings. Validation is performed by comparing the entries of the \fIconfig\fR file against the \fI/usr/share/i18n/SUPPORTED\fR file. +\%LOCALEGEN_\:\%ALLOW_\:\%UNSUPPORTED +If set as a non-empty string, \%locale-\:\%gen shall convey validation errors as warnings. Validation is performed by comparing the entries of the \fI\%config\fR file against the \fI\%/usr/share/i18n/\:\%SUPPORTED\fR file. .TP -LOCALEGEN_CONFIG -Defines the path of the \fIconfig\fR file in the absence of the \fB-A\fR and \fB-c\fR options. +\%LOCALEGEN_\:\%CONFIG +Defines the path of the \fI\%config\fR file in the absence of the \fB-A\fR and \fB-c\fR options. .TP -NO_COLOR +\%NO_\:\%COLOR If set as a non-empty string, coloured output shall be disabled. .SH "EXIT STATUS" The exit status shall be 0 under any of these conditions: @@ -81,14 +81,14 @@ the \fB-h\fR and/or \fB-V\fR options were specified .IP \[bu] 2 the \fB-u\fR option was specified but no locales need compiling .IP \[bu] 2 -the options and \fIconfig\fR were validated, the specified locales compiled and the resulting archive installed, without error +the options and \fI\%config\fR were validated, the specified locales compiled and the resulting archive installed, without error .P Otherwise, the exit status shall be greater than 0. .SH "SEE ALSO" -.BR locale.gen (5), -.BR localectl (1), -.BR locale (1), -.BR localedef (1) +.BR \%locale.gen (5), +.BR \%localectl (1), +.BR \%locale (1), +.BR \%localedef (1) .SH "AUTHORS" .MT kfm@\:plushkava\:.net Kerin Millar diff --git a/locale.gen.5 b/locale.gen.5 index 59e261e..13c3c74 100644 --- a/locale.gen.5 +++ b/locale.gen.5 @@ -2,9 +2,9 @@ .SH "NAME" locale.gen \[em] configuration file for locale-gen .SH "DESCRIPTION" -The \fBlocale-gen\fR(8) utility compiles the locales specified by the \fI/etc/locale.gen\fR file and integrates them into a locale archive. +The \fB\%locale-\:\%gen\fR(8) utility compiles the locales specified by the \fI\%/etc/\:\%locale.gen\fR file and integrates them into a locale archive. .P -The file is comprised of zero or more lines containing one or two fields separated by one or more <blank> characters. The first field defines the \fIlocalename\fR. The second field defines the \fIcharmap\fR, also known as a character set or codeset. The <slash> character is forbidden within both fields. If only one field is specified, the \fIcharmap\fR value shall be taken as "UTF-8". +The file is comprised of zero or more lines containing one or two fields separated by one or more <blank> characters. The first field defines the \fI\%localename\fR. The second field defines the \fI\%charmap\fR, also known as a character set or codeset. The <slash> character is forbidden within both fields. If only one field is specified, the \fI\%charmap\fR value shall be taken as "UTF-8". .P Empty lines and lines beginning with zero or more <blank> characters followed by a <number-sign> character shall be ignored. .P @@ -12,10 +12,10 @@ A <number-sign> character surrounded by <blank> characters may appear after the .P The definition of a <blank> character is that it is either the <tab> or <space> character. .P -Consult the provided \fI/usr/share/i18n/SUPPORTED\fR file for all valid combinations of the \fIlocalename\fR field and \fIcharmap\fR field. +Consult the provided \fI\%/usr/share/i18n/\:\%SUPPORTED\fR file for all valid combinations of the \fI\%localename\fR field and \fI\%charmap\fR field. .P .SH "LOCALE NAMES" -A valid \fIlocalename\fR is of the following format: +A valid \fI\%localename\fR is of the following format: .P .RS .EX @@ -23,12 +23,12 @@ language[_territory][.charmap][@modifier] .EE .RE .P -The complete list of supported \fIlanguage[_territory][@modifier]\fR values can be obtained by reading the first column of the \fI/usr/share/i18n/SUPPORTED\fR file. The values map directly to the names of files within the \fI/usr/share/i18n/locales\fR directory. +The complete list of supported \fI\%language\:\%[_territory]\:\%[@modifier]\fR values can be obtained by reading the first column of the \fI\%/usr/share/i18n/\:\%SUPPORTED\fR file. The values map directly to the names of files within the \fI\%/usr/share/i18n/\:\%locales\fR directory. .P .SH "CHARACTER MAPS" -A \fIcharmap\fR represents a mapping of character symbols and collating element symbols to actual character encodings that enables a standard way to decode, process, and encode text. +A \fI\%charmap\fR represents a mapping of character symbols and collating element symbols to actual character encodings that enables a standard way to decode, process, and encode text. .P -The complete list of supported \fIcharmap\fR values can be obtained by reading the second column of the \fI/usr/share/i18n/SUPPORTED\fR file. The values map directly to the names of files within the \fI/usr/share/i18n/charmaps\fR directory. +The complete list of supported \fI\%charmap\fR values can be obtained by reading the second column of the \fI\%/usr/share/i18n/\:\%SUPPORTED\fR file. The values map directly to the names of files within the \fI\%/usr/share/i18n/\:\%charmaps\fR directory. .SH "EXAMPLES" .EX # These three declarations are considered identical. @@ -47,36 +47,36 @@ en_US GB2312 .I /etc/locale.gen The default location of the configuration file. .TP -.I /usr/share/i18n/SUPPORTED -A list of supported \fIlocalename\fR and \fIcharmap\fR combinations. +.I \%/usr/share/i18n/\:\%SUPPORTED +A list of supported \fI\%localename\fR and \fI\%charmap\fR combinations. .TP -.I /usr/share/i18n/locales -Contains locale definition files that serve as inputs to \fBlocaledef\fR(1). +.I \%/usr/share/i18n/\:\%locales +Contains locale definition files that serve as inputs to \fB\%localedef\fR(1). .TP -.I /usr/share/i18n/charmaps -Contains character map files that serve as inputs to \fBlocaledef\fR(1). +.I \%/usr/share/i18n/\:\%charmaps +Contains character map files that serve as inputs to \fB\%localedef\fR(1). .SH "SEE ALSO" -.BR locale-gen (8), -.BR localectl (1), -.BR locale (1), -.BR localedef (1) +.BR \%locale-gen (8), +.BR \%localectl (1), +.BR \%locale (1), +.BR \%localedef (1) .SH "STANDARDS" System Interface Definitions, Issue 4, Version 2 (XBD) (1994) .br -.UR https:\://pubs\:.opengroup\:.org/onlinepubs/009656599/toc\:.pdf +.UR https://\:pubs.opengroup.org/\:onlinepubs/\:009656599/\:toc.pdf .UE .P XPG3-XPG4 Base Migration Guide, Version 2 (1995). .br -.UR https://\:archive\:.opengroup\:.org/publications/archive/CDROM/g501\:.pdf +.UR https://\:archive.opengroup.org/\:publications/\:archive/\:CDROM/\:g501.pdf .UE .P The Open Group Standard Base Specifications, Issue 8 (POSIX-1.2024). .br -.UR https://\:pubs\:.opengroup\:.org/onlinepubs/9799919799/basedefs/V1\:_chap03\:.html +.UR https://\:pubs.opengroup.org/\:onlinepubs/\:9799919799/\:basedefs/\:V1_chap03.html .UE .br -.UR https://\:pubs\:.opengroup\:.org/onlinepubs/9799919799/basedefs/V1\:_chap07\:.html +.UR https://\:pubs.opengroup.org/\:onlinepubs/\:9799919799/\:basedefs/\:V1_chap07.html .UE .SH "AUTHORS" .MT kfm@\:plushkava\:.net
