This email submits to the Linux man-pages project the new manual page
filename(7). The manual page's groff source follows in patch format.
This email is copied to two other, relevant lists as a courtesy, but its
main target is the list <[email protected]>, whose archives are
at [https://www.spinics.net/lists/linux-man/].
CONTENTS
I. NAME AND BRIEF DESCRIPTION
II. HOW INFORMATION TO WRITE THE MANUAL PAGE HAS BEEN OBTAINED
III. WHY THE MANUAL PAGE HAS BEEN WRITTEN
IV. DISTRIBUTIONS AND LOCALES
V. GROFF SOURCE (IN PATCH FORMAT)
---------------------------------------------------------------------------
I. NAME AND BRIEF DESCRIPTION
---------------------------------------------------------------------------
FILENAME(7) Linux Programmer's Manual FILENAME(7)
NAME
filename - requirements and conventions for the naming of files
DESCRIPTION
This manual page sets forth requirements for and delineates conven‐
tions regarding filenames on a Linux system, where a filename is ei‐
ther (as the word suggests) the name of a regular file or the name
of another object held by the system's filesystem such as a direc‐
tory, symbolic link, named pipe or device.
---------------------------------------------------------------------------
II. HOW INFORMATION TO WRITE THE MANUAL PAGE HAS BEEN OBTAINED
---------------------------------------------------------------------------
The web page [https://www.kernel.org/doc/man-pages/patches.html] asks
how the information to write the manual page has been obtained. I have
obtained the information in eight ways.
[1] From POSIX.1-2008, SUSv4, sects. 3.281, 3.282 and 4.13.
Excerpts follow.
3.281 Portable Filename
A filename consisting only of characters from the portable filename
character set.
Note: Applications should avoid using filenames that have
the <hyphen-minus> character as the first character since this may cause
problems when filenames are passed as command line arguments.
3.282 Portable Filename Character Set
The set of characters from which portable filenames are constructed.
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
a b c d e f g h i j k l m n o p q r s t u v w x y z
0 1 2 3 4 5 6 7 8 9 . _ -
The last three characters are the <period>, <underscore>, and
<hyphen-minus> characters, respectively. See also Pathname.
4.13 Pathname Resolution
Pathname resolution is performed for a process to resolve a pathname to a
particular directory entry for a file in the file hierarchy....
Each filename in the pathname is located in the directory specified by its
predecessor (for example, in the pathname fragment a/b, file b is located
in directory a). Pathname resolution shall fail if this cannot be
accomplished. If the pathname begins with a <slash>, the predecessor of the
first filename in the pathname shall be taken to be the root directory of
the process (such pathnames are referred to as "absolute pathnames"). If
the pathname does not begin with a <slash>, the predecessor of the first
filename of the pathname shall be taken to be either the current working
directory of the process or for certain interfaces the directory identified
by a file descriptor passed to the interface (such pathnames are referred
to as "relative pathnames")....
The special filename dot shall refer to the directory specified by its
predecessor. The special filename dot-dot shall refer to the parent
directory of its predecessor directory. As a special case, in the root
directory, dot-dot may refer to the root directory itself....
A pathname consisting of a single <slash> shall resolve to the root
directory of the process. A null pathname shall not be
successfully resolved....
[2] From the GNU Coreutils manual, ver. 8.32, especially chapter 2 and
sect. 10.1.1. Excerpts follow.
2 Common options....
'--' Delimit the option list. Later arguments, if any, are treated as
operands even if they begin with '-'. For example, 'sort -- -r' reads from
the file named '-r'.
A single '-' operand is not really an option, though it looks like one. It
stands for a file operand, and some tools treat it as standard input, or as
standard output if that is clear from the context....
10.1.1 Which files are listed....
By default, 'ls' lists files and the contents of any directories on the
command line, except that in directories it ignores files whose names start
with '.'.
[3] From dash(1) and bash(1).
[4] From the Unicode Standard, ver. 13.0,
especially Table 4-4. General Category.
[5] From the Unicode Character Database, which on a Debian GNU/Linux
system appears at /usr/share/unicode/UnicodeData.txt. Incidentally, it
is because of the Unicode Character Database that the manual page calls
the period a full stop, the slash a solidus, the underscore a low line,
and the hyphen a hyphen-minus.
[6] From utf-8(7) and ascii(7).
[7] From a discussion on the debian-devel mailing list regarding MIME
types: [https://lists.debian.org/debian-devel/2021/08/msg00557.html].
[8] From general experience as a Linux user and, since 2005, as
a Debian Developer.
---------------------------------------------------------------------------
III. WHY THE MANUAL PAGE HAS BEEN WRITTEN
---------------------------------------------------------------------------
The chief reason the manual page has been written is that newcomers
to Linux are often advised by experienced users, ad hoc, to avoid
unconventional filenames like "My Document.txt" in favor of,
say, "my-document.txt"; only nowhere in basic, conveniently accessible,
widely installed free documentation is it cogently explained which
filenames are conventional and, indeed, which are even legal. Filenames
being ubiquitous, a proper introduction to them seems due; and anyway
between ext4(5) and utf-8(7) lies a gap. Hence the new manual page,
which fills the gap.
---------------------------------------------------------------------------
IV. DISTRIBUTIONS AND LOCALES
---------------------------------------------------------------------------
Since I do not use Arch or Fedora, but only Debian, I would appreciate
reviews from an Arch user and a Fedora user to ensure that the manual page
is as correct for those systems as it is for Debian. The most likely
point of discrepancy regards MIME types: see the manual page's
subsection "The full stop to introduce a format extension."
I would also appreciate a review by a native Chinese or Japanese speaker
of the manual page's section "LOCALES AND UNICODE," if any native Chinese
or Japanese speaker is reading. (As far as I know, spaces in
local Chinese and Japanese filenames are as deprecated as they are, say,
in local French and German filenames. However, I don't really know.
The manual page should not descend into a dissertation regarding every
possible locale, but I would at least like it to avoid inadvertent false
statements regarding local filenaming conventions in the
major Han/Kanji-using languages.)
---------------------------------------------------------------------------
V. GROFF SOURCE (IN PATCH FORMAT)
---------------------------------------------------------------------------
--- /dev/null 2021-09-06 09:32:09.234024621 +0000
+++ b/man7/filename.7 2021-09-06 11:16:45.600516972 +0000
@@ -0,0 +1,519 @@
+.\" Copyright (C) 2021 Thaddeus H. Black <[email protected]>
+.\"
+.\" %%%LICENSE_START(VERBATIM)
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of this
+.\" manual under the conditions for verbatim copying, provided that the
+.\" entire resulting derived work is distributed under the terms of a
+.\" permission notice identical to this one.
+.\"
+.\" Since the Linux kernel and libraries are constantly changing, this
+.\" manual page may be incorrect or out-of-date. The author(s) assume no
+.\" responsibility for errors or omissions, or for damages resulting from
+.\" the use of the information contained herein. The author(s) may not
+.\" have taken the same level of care in the production of this manual,
+.\" which is licensed free of charge, as they might when working
+.\" professionally.
+.\"
+.\" Formatted or processed versions of this manual, if unaccompanied by
+.\" the source, must acknowledge the copyright and authors of this work.
+.\" %%%LICENSE_END
+.\"
+.\" 2021-09-06, Thaddeus H. Black <[email protected]>
+.\" Wrote the manual page's initial version.
+.\"
+.TH FILENAME 7 2021-09-06 "Linux" "Linux Programmer's Manual"
+.SH NAME
+.P
+filename \- requirements and conventions for the naming of files
+.SH DESCRIPTION
+.P
+This manual page sets forth requirements for and delineates conventions
+regarding filenames on a Linux system, where a
+.I filename
+is either (as the word suggests) the name of a regular file or the name of
+another object held by the system's filesystem such as a directory,
+symbolic link, named pipe or device.
+.SH LEGAL FILENAMES
+.P
+A filename on a Linux system can consist of almost any sequence of UTF-8
+characters or, indeed, almost any sequence of bytes.
+The exceptions are as follows.
+.SS Reserved characters
+.TP
+.B /
+The solidus is reserved to separate pathname components as for example in
+.IR /usr/share/doc ,
+each component being itself a filename.
+For this reason, no filename may include a solidus.
+More precisely, no filename may include the byte that, in ASCII and UTF-8,
+exclusively represents the solidus.
+.TP
+.B \e0
+The null character is reserved for the filesystem to append to terminate a
+filename's representation in memory.
+For this reason, no filename may include a null character.
+More precisely, no filename may include the byte that, in ASCII and UTF-8,
+exclusively represents the null character.
+(When appended by the filesystem to terminate a filename's representation
+in memory, the byte in question is called the
+.I terminating null
+.IR byte .
+Though familiar to\~C programmers, the terminating null byte is usually
+invisible to users.)
+.P
+Note that\~\fB\e0\fR, the null character (or null byte), differs
+from\~\fB0\fR, the printable digit-zero character.
+The null character (or null byte) is unprintable and registers in ASCII and
+UTF-8 as the eight-bit pattern\~0x00, whereas the printable digit zero
+registers as\~0x30 [see the \(lqHex\(rq column in
+.BR ascii (7)'s
+character table].
+Nothing prevents a filename from including a printable digit zero, as for
+instance the filename
+.I intel-m10-bmc.h
+from the kernel's source does.
+.SS Reserved names
+.TP
+.B .
+The filename consisting of a single full stop is reserved to represent the
+current directory.
+.TP
+.B ..
+The filename consisting of two full stops is reserved to represent the
+parent directory.
+.TP
+(empty)
+The empty filename, consisting of no bytes at all (except a terminating
+null byte), is not allowed.
+.P
+The aforementioned current and parent directories are the current
+.I working
+directory and its parent except when the\~\fB.\fR or\~\fB..\fR occurs in
+the middle or at the end of a pathname, in which case the current and
+parent directories are taken relative to preceding pathname elements.
+For example, if the current working directory were
+.IR /home/jsmith ,
+then
+.I ../rjones
+would mean
+.I /home/rjones
+but
+.I foo/bar/../baz
+would mean
+.IR /home/jsmith/foo/baz ,
+whereas
+.I foo/bar/./baz
+would mean
+.IR /home/jsmith/foo/bar/baz .
+.SS Long names
+.P
+No filename may exceed\~255 bytes in length, or\~256 bytes after counting
+the terminating null byte.
+.RB ( Reserved
+.B characters
+above explains the terminating null byte.)
+.SS Non-UTF-8 names
+.P
+Filenames need not consist of valid UTF-8 characters (although, except
+where a non-UTF-8 legacy encoding is in use, most filenames do).
+As long as the requirements of the preceding subsections are met, any
+sequence of bytes can legally serve as a filename.
+.SH CONVENTIONAL FILENAMES
+.P
+Merely because a filename is legal does not make its use advisable, though.
+Some legal filenames cause practical troubles.
+For example, the legal filenames
+.IR m=3 ,
+.IR \(tijsmith ,
+.I \-v
+and
+.I My\~Document.txt
+are susceptible to misinterpretation by a shell.
+Workarounds typically exist, chiefly via quotation, escape and the explicit
+termination of options processing [see
+.BR sh (1)];
+but when reprocessing of shell-command text requires requotation and
+re-escape, the workarounds become an inconvenient, confusing, error-prone
+hassle.
+.P
+The use of conventional filenames averts the hassle.
+It also makes filenames more recognizable to experienced users.
+.P
+This section introduces broadly observed conventions for filenames.
+.SS The POSIX Portable Filename Character Set
+.P
+In general contexts, especially for international applications,
+conventional filenames are composed using the\~65 ASCII characters of the
+POSIX Portable Filename Character Set.
+The POSIX Portable Filename Character Set consists of the following.
+.TP
+.BR A \- Z
+The\~26 capital or uppercase ASCII letters.
+.TP
+.BR a \- z
+The\~26 small or lowercase ASCII letters.
+.TP
+.BR 0 \- 9
+The ten ASCII digits.
+.TP
+.B . \_ \-
+These three ASCII punctuators: full stop; low line; hyphen-minus.
+.P
+Special contexts often employ additional characters but, in general
+contexts for international applications, conventional filenames exclude
+characters other than the listed\~65.
+(For noninternational applications, see
+.B LOCALES AND UNICODE
+below.)
+.P
+Observe that the space\~\fB\(aq\0\(aq\fR or\~\fB\eu0020\fR is not listed
+despite being an ASCII character.
+Filenames that include spaces are often encountered for various reasons in
+certain contexts, but such filenames are unconventional in general and are
+inconvenient to use with tools.
+Within filenames, the low line\~\fB\_\fR or hyphen-minus\~\fB\-\fR is
+conventionally employed as necessary instead of the space.
+(See
+.B UNCONVENTIONAL FILENAMES
+and, under
+.B SOFT
+.BR CONVENTIONS ,
+also
+.B Low line versus hyphen-minus
+below.)
+.P
+Incidentally, capital and small letters are distinct within filenames on a
+Linux system; so, for example,
+.I README
+and
+.I readme
+name two different files.
+(Under
+.B SOFT
+.BR CONVENTIONS ,
+see
+.B Capitalization
+below for further observations regarding capitalization.)
+.SS Special semantics
+.P
+Besides the last subsection's POSIX convention, a pair of conventions
+derived from core utilities is almost always respected, as well.
+.TP
+.BR \- name
+A name that begins with a hyphen-minus is conventionally interpreted as a
+command-line option rather than as a filename.
+Therefore, conventional filenames do not begin with the hyphen-minus.
+.TP
+.BR . name
+Conventional filenames may indeed begin with the full stop.
+However, such filenames conventionally designate
+.I hidden files
+(or hidden directories, etc.), a familiar example being the
+.I .profile
+typically found in a user's home directory.
+Hidden files behave normally but, by default, are ignored by
+.BR ls (1)
+and certain other tools.
+.P
+The one-character name\~\fB\-\fR consisting of a lone hyphen-minus is
+sometimes understood by a shell to refer to the previous working directory
+and sometimes understood by tools to refer to standard input or standard
+output, so convention does not employ the lone hyphen-minus as a file's
+proper name.
+The one-character name\~\fB.\fR consisting of a lone full stop has already
+been mentioned under
+.B LEGAL FILENAMES
+above: one cannot use it as a file's proper name at all.
+.SS The full stop to introduce a format extension
+.P
+Other than at a filename's beginning (a case the last subsection has
+discussed), the full stop is employed in filenames for various further
+conventional purposes.
+No single rule governs all conventional uses of the full stop.
+.P
+However, except at a filename's beginning, the most common conventional use
+of the full stop is to append to a filename's stem an extension to indicate
+the format of the file's contents.
+An example is the filename
+.IR UnicodeData.txt ,
+in which
+.I UnicodeData
+is the stem and the\~\fI.txt\fR indicates that the file contains plain
+text.
+Multiple format extensions are even appended to some filename stems, as in
+.I my-archive.tar.xz
+for instance, which is the name of a tape archive
+.I my-archive.tar
+that, after archival, has subsequently been compressed by
+.BR xz (1).
+.P
+The format-extension convention is all but universally recognized.
+Even nontechnical users are typically familiar with it.
+However, many users employ full stops also for various purposes unrelated
+to format extensions, as well; and they do so often enough that such
+unrelated usage can hardly be called unconventional.
+Except at a filename's beginning, convention supports free use of the full
+stop.
+.P
+.I You
+may reserve the full stop solely to append format extensions if you wish,
+of course.
+Many users do.
+.P
+.\" The next sentence has been corrected according
+.\" to Charles Plessy's helpful
+.\" advice [https://lists.debian.org/debian-devel/2021/08/msg00557.html].
+(If your machine is configured as a desktop or laptop rather than as a
+server, then you can probably find a fairly comprehensive catalog of
+conventional filename extensions, identifying the format each extension
+implies, on your machine in a file such as
+.I /etc/mime.types
+or
+.IR /usr/share/mime/globs .)
+.SH SOFT CONVENTIONS
+.P
+Further filenaming conventions are softer.
+Though often observed, such softer conventions can be bent or broken
+without rendering filenames unconventional.
+.P
+This section introduces soft conventions for filenames.
+.SS Low line versus hyphen-minus
+.P
+Whether to use the low line\~\fB\_\fR or the hyphen-minus\~\fB\-\fR in
+filenames is a matter of preference.
+Except as stated above, convention does not strongly prefer the one over
+the other.
+.P
+If you would like advice, anyway, however, then the kernel's source sets an
+example.
+Most filenames in the kernel's source prefer the hyphen-minus.
+You can do the same if you wish.
+.P
+Even if you prefer the hyphen-minus, though, some exceptions arise, as
+follows.
+.IP \(bu
+The contents of a program's source files usually designate various
+.I entities
+such as variables, functions, types and so forth.
+In\~C and similar programming languages, the hyphen-minus is a minus sign,
+so the designations of entities must use the low line, instead.
+Where a file is named after an entity the file introduces, the filename
+should use low lines as the entity's designation does.
+Examples include the file
+.IR lock\_events.h ,
+which introduces the entity
+.IR lock\_events ,
+in the kernel's source.
+.IP \(bu
+Where distinct separators with different semantics are required, a filename
+can use the low line as an alternate separator.
+Examples include the file
+.IR coreutils\_8.30-3\_amd64.deb ,
+which provides revision\~3 of the Debian binary package that installs
+version\~8.30 of the GNU core utilities for the amd64/x86-64 architecture.
+.IP \(bu
+Occasionally, the name of a file that provides private, internal,
+ephemeral, uninterfaceable or undocumented aspects of an implementation
+will
+.I begin
+with a low line to hint that the file
+.RS
+.IP +
+does not require the user's or programmer's attention or
+.IP +
+is unsuitable for external agents to access directly.
+.RE
+.IP
+Examples include the file
+.\" On the author's PC using Groff's default output device, Groff typesets
+.\" the next line's italicized low line inconsistently compared to the
+.\" manual page's other italicized low lines. Presumably, Groff does this
+.\" because the low line in question begins its word (though why Groff
+.\" thinks beginning the word significant is unclear), but the
+.\" inconsistency is slightly distracting.
+.I \_sd-common.h
+in systemd's source.
+.IP \(bu
+Sometimes, the low line stands for an unspecified letter of the alphabet.
+.P
+Otherwise, despite that the low line and the hyphen-minus are both
+conventional, if you want advice: prefer the hyphen-minus.
+.SS Capitalization
+.P
+A loosely observed convention favors small letters in filenames where no
+reason to use capitals exists.
+Many exceptions occur, though, as for example the oft-encountered
+.I Makefile
+that instructs
+.BR make (1)
+how to build an executable program or other autogeneratable file.
+.P
+The reason convention favors small letters is that the general use of small
+letters leaves the capital letters to be employed for emphasis.
+Where the default\~C (or C.UTF-8) locale is in use, the capital ASCII
+letters are collated before all the small ones, whereby
+.BR ls (1)
+lists filenames like
+.I Makefile
+and
+.I README
+before filenames like
+.I a.out
+and
+.IR foo.c .
+[If your locale causes
+.BR ls (1)
+to collate differently when you would have preferred the just-described
+default collation, then try
+.B LC\_ALL=C ls
+or
+.B LC\_ALL=C.UTF-8 ls
+to suppress the locale.
+See
+.BR locale (7).]
+.P
+Names of types and of certain other entities are sometimes capitalized in
+programming languages like\~C++ and Python.
+Such capitalization can spill over to affect filenames, so it is hard to
+state a general rule.
+.SH LOCALES AND UNICODE
+.\" If another subsection were added to the manual page, then this section
+.\" might be demoted to a subsection and, if appropriate, grouped with the
+.\" new subsection together under a new section
+.\" entitled "FURTHER CONSIDERATIONS."
+.P
+If your application is local rather than international, then you can relax
+POSIX's aforementioned character-set convention at your discretion by
+including graphic Unicode characters; specifically, by including non-ASCII
+Unicode characters for which
+.BR iswgraph (3)
+returns true in your locale or (if your system has it) in the C.UTF-8
+locale.
+[For the relationship between
+.BR unicode (7),
+.BR utf-8 (7)
+and
+.BR ascii (7),
+see the respective manual pages.
+Approximately, in brief, Unicode is a character set, UTF-8 is a
+byte-oriented scheme by which Unicode characters can be encoded, and ASCII
+is both a character set and a byte-oriented scheme that is a subset of both
+Unicode and UTF-8.]
+.P
+To suggest an exact noninternational filenaming rule, other than the
+.BR iswgraph (3)
+rule, for every locale would exceed the scope of this manual page; but
+approximately, in a Japanese or French application for instance, a filename
+might respectively include kanji ideographs or accented Latin letters.
+Filenames that include kanji ideographs or accented Latin letters might be
+hard for international users to read or type, but insofar as such filenames
+exclude spaces, control characters, ASCII symbols (like\~\fB$\fR
+or\~\fB=\fR), and ASCII punctuators other than the three punctuators POSIX
+recommends, such filenames will not normally cause trouble for tools and,
+thus, may be regarded as conventional within the local context.
+.P
+The use of nonbreaking spaces like\~\fB\eu00A0\fR, \fB\eu2007\fR,
+\fB\eu202F\fR or\~\fB\euFEFF\fR in filenames is probably inadvisable for
+most locales, despite that
+.BR iswgraph (3)
+returns true.
+[The use of ordinary, breaking spaces like\~\fB\eu0020\fR (the familiar
+ASCII space), \fB\eu1680\fR, \fB\eu2000\fR through\~\fB\eu2006\fR,
+\fB\eu2008\fR, \fB\eu2009\fR, \fB\eu200A\fR, \fB\eu205F\fR
+and\~\fB\eu3000\fR is probably also inadvisable, but
+.BR iswgraph (3)
+returns false for those, anyway.]
+.SH UNCONVENTIONAL FILENAMES
+.P
+More than a few files on a typical Linux system, occasionally even
+including standard files employed by and/or automatically installed by an
+operating-system distribution, have unconventional filenames.
+For example, on a Debian GNU/Linux system, some names of files that supply
+software packages use the characters\~\fB+\fR and\~\fB\(ti\fR which, though
+unconventional in general, are normal and expected within that context.
+For another example, in the kernel's source, certain filenames use the
+character\~\fB,\fR to separate a device's designator from the name of the
+device's manufacturer.
+You may have noticed the unconventionally-named
+.I lost+found
+directory lurking at a filesystem's root on your computer; and there are
+further examples, as well.
+.P
+There are many reasons to use unconventional filenames.
+.P
+It is hard to give a general rule, with respect to a particular context, as
+to which unconventional filenames are likely to cause practical troubles
+and which are not.
+If unsure, you can avoid troubles by adhering to convention; but if you
+wish or need to depart from convention, then the only suggestions this
+manual page would make are
+.IP \(bu
+that unconventional filenames not be used without context;
+.IP \(bu
+that unconventional filenames not be used without reason;
+.IP \(bu
+that, even where filenames are unconventional, the recommendations of
+.B Special semantics
+above still be followed if practicable;
+.IP \(bu
+that, where several unconventionally named files are collected, the use of
+unconventional characters be systematic (for example,
+.IR 16:30.log ,
+.IR 16:45.log ,
+.I 17:00.log
+and so on);
+.IP \(bu
+that, even if unconventional symbols or punctuators are employed within
+filenames, one think twice before
+.I beginning
+a filename with an unconventional symbol or punctuator; specifically,
+before beginning a filename with a nonalphanumeric ASCII character other
+than the full stop or low line (consider for example a filename that began
+with the\~\fB\(ti\fR or\~\fB$\fR symbol, which a shell might misinterpret
+as it were a reference to a home directory or shell parameter);
+.IP \(bu
+that, even if non-POSIX characters are used, non-ASCII characters be
+avoided to the extent to which the application is international;
+.IP \(bu
+that the shell's four standard globbing characters\~\fB*?[]\fR be avoided
+in most instances; and
+.IP \(bu
+even if none of the other suggestions is followed, that control characters
+be avoided in any event,
+.I control characters
+being characters, including the tab\~\fB\et\fR and line-feed\~\fB\en\fR
+characters, for which
+.BR iswcntrl (3)
+returns true.
+(Note that, although the use of the space in filenames contravenes POSIX
+and anyway annoys many Linux users, the space is the sole nongraphic ASCII
+character that, by definition, is not a control character.
+Spaces in filenames are unconventional and perhaps inadvisable, but they
+are hardly unusual; whereas tabs and line feeds are, for good reason,
+practically never seen.)
+.SH CONFORMING TO
+.P
+POSIX.1-2008, SUSv4.
+.SH SEE ALSO
+.P
+.BR ls (1),
+.BR sh (1),
+.BR iswcntrl (3),
+.BR iswgraph (3),
+.BR mbrtowc (3),
+.BR wcrtomb (3),
+.BR ext4 (5),
+.BR ascii (7),
+.BR locale (7),
+.BR unicode (7),
+.BR utf-8 (7)
+.P
+info
+.B coreutils
+.\" The author, Thaddeus H. Black, thanks his wife Kristie, daughter Naomi
+.\" and son George for their review and proofreading of various parts of
+.\" this manual page.
Hello Thaddeus,
On 9/6/21 1:40 PM, Thaddeus H. Black wrote:
> This email submits to the Linux man-pages project the new manual page
> filename(7). The manual page's groff source follows in patch format.
>
> This email is copied to two other, relevant lists as a courtesy, but its
> main target is the list <[email protected]>, whose archives are
> at [https://www.spinics.net/lists/linux-man/].
>
> CONTENTS
>
> I. NAME AND BRIEF DESCRIPTION
> II. HOW INFORMATION TO WRITE THE MANUAL PAGE HAS BEEN OBTAINED
> III. WHY THE MANUAL PAGE HAS BEEN WRITTEN
> IV. DISTRIBUTIONS AND LOCALES
> V. GROFF SOURCE (IN PATCH FORMAT)
I *love* this patch! Even before starting to read it!! :-}
See some comments below.
Thank you very much!
Alex
[...]
> ---------------------------------------------------------------------------
> II. HOW INFORMATION TO WRITE THE MANUAL PAGE HAS BEEN OBTAINED
> ---------------------------------------------------------------------------
>
> The web page [https://www.kernel.org/doc/man-pages/patches.html] asks
> how the information to write the manual page has been obtained. I have
> obtained the information in eight ways.
>
> [1] From POSIX.1-2008, SUSv4, sects. 3.281, 3.282 and 4.13.
> Excerpts follow.
>
> 3.281 Portable Filename
>
[...]
> The special filename dot shall refer to the directory specified by its
> predecessor. The special filename dot-dot shall refer to the parent
> directory of its predecessor directory. As a special case, in the root
> directory, dot-dot may refer to the root directory itself....
I'm surprised that POSIX says _may_ and not _shall_ here. Is it
possible that '/..' != '/'? Or is it just a wording issue of POSIX?
>
> A pathname consisting of a single <slash> shall resolve to the root
> directory of the process. A null pathname shall not be
> successfully resolved....
>
> [2] From the GNU Coreutils manual, ver. 8.32, especially chapter 2 and
> sect. 10.1.1. Excerpts follow.
>
> 2 Common options....
>
> '--' Delimit the option list. Later arguments, if any, are treated as
> operands even if they begin with '-'. For example, 'sort -- -r' reads from
> the file named '-r'.
>
> A single '-' operand is not really an option, though it looks like one. It
> stands for a file operand, and some tools treat it as standard input, or as
> standard output if that is clear from the context....
>
> 10.1.1 Which files are listed....
>
> By default, 'ls' lists files and the contents of any directories on the
> command line, except that in directories it ignores files whose names start
> with '.'.
>
> [3] From dash(1) and bash(1).
>
> [4] From the Unicode Standard, ver. 13.0,
> especially Table 4-4. General Category.
>
> [5] From the Unicode Character Database, which on a Debian GNU/Linux
> system appears at /usr/share/unicode/UnicodeData.txt. Incidentally, it
> is because of the Unicode Character Database that the manual page calls
> the period a full stop, the slash a solidus, the underscore a low line,
> and the hyphen a hyphen-minus.
>
> [6] From utf-8(7) and ascii(7).
>
> [7] From a discussion on the debian-devel mailing list regarding MIME
> types: [https://lists.debian.org/debian-devel/2021/08/msg00557.html].
>
> [8] From general experience as a Linux user and, since 2005, as
> a Debian Developer.
>
> ---------------------------------------------------------------------------
> III. WHY THE MANUAL PAGE HAS BEEN WRITTEN
> ---------------------------------------------------------------------------
>
> The chief reason the manual page has been written is that newcomers
> to Linux are often advised by experienced users, ad hoc, to avoid
> unconventional filenames like "My Document.txt" in favor of,
> say, "my-document.txt"; only nowhere in basic, conveniently accessible,
> widely installed free documentation is it cogently explained which
> filenames are conventional and, indeed, which are even legal. Filenames
> being ubiquitous, a proper introduction to them seems due; and anyway
> between ext4(5) and utf-8(7) lies a gap. Hence the new manual page,
> which fills the gap.
Good.
>
> ---------------------------------------------------------------------------
> IV. DISTRIBUTIONS AND LOCALES
> ---------------------------------------------------------------------------
>
> Since I do not use Arch or Fedora, but only Debian, I would appreciate
> reviews from an Arch user and a Fedora user to ensure that the manual page
> is as correct for those systems as it is for Debian. The most likely
> point of discrepancy regards MIME types: see the manual page's
> subsection "The full stop to introduce a format extension."
I can't help here; I use Debian too :). Michael uses Fedora, I think,
so maybe he can tell.
>
> I would also appreciate a review by a native Chinese or Japanese speaker
> of the manual page's section "LOCALES AND UNICODE," if any native Chinese
> or Japanese speaker is reading. (As far as I know, spaces in
> local Chinese and Japanese filenames are as deprecated as they are, say,
> in local French and German filenames. However, I don't really know.
> The manual page should not descend into a dissertation regarding every
> possible locale, but I would at least like it to avoid inadvertent false
> statements regarding local filenaming conventions in the
> major Han/Kanji-using languages.)
>
> ---------------------------------------------------------------------------
> V. GROFF SOURCE (IN PATCH FORMAT)
> ---------------------------------------------------------------------------
>
> --- /dev/null 2021-09-06 09:32:09.234024621 +0000
> +++ b/man7/filename.7 2021-09-06 11:16:45.600516972 +0000
> @@ -0,0 +1,519 @@
> +.\" Copyright (C) 2021 Thaddeus H. Black <[email protected]>
> +.\"
> +.\" %%%LICENSE_START(VERBATIM)
> +.\" Permission is granted to make and distribute verbatim copies of this
> +.\" manual provided the copyright notice and this permission notice are
> +.\" preserved on all copies.
> +.\"
> +.\" Permission is granted to copy and distribute modified versions of this
> +.\" manual under the conditions for verbatim copying, provided that the
> +.\" entire resulting derived work is distributed under the terms of a
> +.\" permission notice identical to this one.
> +.\"
> +.\" Since the Linux kernel and libraries are constantly changing, this
> +.\" manual page may be incorrect or out-of-date. The author(s) assume no
> +.\" responsibility for errors or omissions, or for damages resulting from
> +.\" the use of the information contained herein. The author(s) may not
> +.\" have taken the same level of care in the production of this manual,
> +.\" which is licensed free of charge, as they might when working
> +.\" professionally.
> +.\"
> +.\" Formatted or processed versions of this manual, if unaccompanied by
> +.\" the source, must acknowledge the copyright and authors of this work.
> +.\" %%%LICENSE_END
> +.\"
> +.\" 2021-09-06, Thaddeus H. Black <[email protected]>
> +.\" Wrote the manual page's initial version.
> +.\"
> +.TH FILENAME 7 2021-09-06 "Linux" "Linux Programmer's Manual"
> +.SH NAME
> +.P
I don't know the history of this (actually, I've always wondered why),
but .PP and .P are equivalent, AFAIK, and we use .PP.
> +filename \- requirements and conventions for the naming of files
> +.SH DESCRIPTION
> +.P
> +This manual page sets forth requirements for and delineates conventions
> +regarding filenames on a Linux system, where a
> +.I filename
> +is either (as the word suggests) the name of a regular file or the name of
> +another object held by the system's filesystem such as a directory,
> +symbolic link, named pipe or device.
> +.SH LEGAL FILENAMES
See man-pages(7):
Sections within a manual page
The list below shows conventional or suggested sections.
Most manual pages should include at least the highlighted
sections. Arrange a new manual page so that sections are
placed in the order shown in the list.
NAME
SYNOPSIS
CONFIGURATION [Normally only in Section 4]
DESCRIPTION
OPTIONS [Normally only in Sections 1, 8]
EXIT STATUS [Normally only in Sections 1, 8]
RETURN VALUE [Normally only in Sections 2, 3]
ERRORS [Typically only in Sections 2, 3]
ENVIRONMENT
FILES
VERSIONS [Normally only in Sections 2, 3]
ATTRIBUTES [Normally only in Sections 2, 3]
CONFORMING TO
NOTES
BUGS
EXAMPLES
AUTHORS [Discouraged]
REPORTING BUGS [Not used in man‐pages]
COPYRIGHT [Not used in man‐pages]
SEE ALSO
Where a traditional heading would apply, please use it;
this kind of consistency can make the information easier to
understand. If you must, you can create your own headings
if they make things easier to understand (this can be espe‐
cially useful for pages in Sections 4 and 5). However, be‐
fore doing this, consider whether you could use the tradi‐
tional headings, with some subsections (.SS) within those
sections.
You could move sections into subsections of DESCRIPTION, and the current
subsections into tagged paragraphs (.TP).
> +.P
> +A filename on a Linux system can consist of almost any sequence of UTF-8
See man-pages(7):
Use semantic newlines
In the source of a manual page, new sentences should be
started on new lines, and long sentences should be split
into lines at clause breaks (commas, semicolons, colons,
and so on). This convention, sometimes known as "semantic
newlines", makes it easier to see the effect of patches,
which often operate at the level of individual sentences or
sentence clauses.
> +characters or, indeed, almost any sequence of bytes.
> +The exceptions are as follows.
> +.SS Reserved characters
> +.TP
> +.B /
> +The solidus is reserved to separate pathname components as for example in
> +.IR /usr/share/doc ,
> +each component being itself a filename.
> +For this reason, no filename may include a solidus.
> +More precisely, no filename may include the byte that, in ASCII and UTF-8,
> +exclusively represents the solidus.
> +.TP
> +.B \e0
> +The null character is reserved for the filesystem to append to terminate a
> +filename's representation in memory.
> +For this reason, no filename may include a null character.
> +More precisely, no filename may include the byte that, in ASCII and UTF-8,
> +exclusively represents the null character.
> +(When appended by the filesystem to terminate a filename's representation
> +in memory, the byte in question is called the
> +.I terminating null
> +.IR byte .
> +Though familiar to\~C programmers, the terminating null byte is usually
> +invisible to users.)
> +.P
> +Note that\~\fB\e0\fR, the null character (or null byte), differs
Please, use a separate line and
.B \e0
We avoid \f.
See man-pages(7) (although it is explained in an unrelated context):
Any reference to the subject of the current manual page
should be written with the name in bold followed by a pair
of parentheses in Roman (normal) font. For example, in the
fcntl(2) man page, references to the subject of the page
would be written as: fcntl(). The preferred way to write
this in the source file is:
.BR fcntl ()
(Using this format, rather than the use of "\fB...\fP()"
makes it easier to write tools that parse man page source
files.)
> +from\~\fB0\fR, the printable digit-zero character.
Why did you use the non-breaking space here (and other places)? I don't
think it's necessary.
> +The null character (or null byte) is unprintable and registers in ASCII and
> +UTF-8 as the eight-bit pattern\~0x00, whereas the printable digit zero
> +registers as\~0x30 [see the \(lqHex\(rq column in
> +.BR ascii (7)'s
> +character table].
> +Nothing prevents a filename from including a printable digit zero, as for
> +instance the filename
> +.I intel-m10-bmc.h
> +from the kernel's source does.
> +.SS Reserved names
> +.TP
> +.B .
> +The filename consisting of a single full stop is reserved to represent the
> +current directory.
> +.TP
> +.B ..
> +The filename consisting of two full stops is reserved to represent the
> +parent directory.
> +.TP
> +(empty)
> +The empty filename, consisting of no bytes at all (except a terminating
> +null byte), is not allowed.
> +.P
> +The aforementioned current and parent directories are the current
> +.I working
> +directory and its parent except when the\~\fB.\fR or\~\fB..\fR occurs in
> +the middle or at the end of a pathname, in which case the current and
> +parent directories are taken relative to preceding pathname elements.
> +For example, if the current working directory were
> +.IR /home/jsmith ,
> +then
> +.I ../rjones
> +would mean
> +.I /home/rjones
> +but
> +.I foo/bar/../baz
> +would mean
> +.IR /home/jsmith/foo/baz ,
> +whereas
> +.I foo/bar/./baz
> +would mean
> +.IR /home/jsmith/foo/bar/baz .
> +.SS Long names
> +.P
> +No filename may exceed\~255 bytes in length, or\~256 bytes after counting
> +the terminating null byte.
> +.RB ( Reserved
> +.B characters
> +above explains the terminating null byte.)
> +.SS Non-UTF-8 names
> +.P
> +Filenames need not consist of valid UTF-8 characters (although, except
> +where a non-UTF-8 legacy encoding is in use, most filenames do).
> +As long as the requirements of the preceding subsections are met, any
> +sequence of bytes can legally serve as a filename.
> +.SH CONVENTIONAL FILENAMES
> +.P
> +Merely because a filename is legal does not make its use advisable, though.
> +Some legal filenames cause practical troubles.
> +For example, the legal filenames
> +.IR m=3 ,
> +.IR \(tijsmith ,
> +.I \-v
> +and
> +.I My\~Document.txt
> +are susceptible to misinterpretation by a shell.
> +Workarounds typically exist, chiefly via quotation, escape and the explicit
> +termination of options processing [see
> +.BR sh (1)];
I'd have used parentheses there. No? Was it, as in Mathematics, to
clearly differentiate the inner from the outer parentheses? If so, we
typically nest parentheses in the manual pages (as in here (see?)).
However, I don't think it's wrong per se to use brackets... Is it
common in other places? Maybe the add some readability to the text, and
we hould use them.
> +but when reprocessing of shell-command text requires requotation and
> +re-escape, the workarounds become an inconvenient, confusing, error-prone
> +hassle.
> +.P
> +The use of conventional filenames averts the hassle.
> +It also makes filenames more recognizable to experienced users.
> +.P
> +This section introduces broadly observed conventions for filenames.
> +.SS The POSIX Portable Filename Character Set
> +.P
> +In general contexts, especially for international applications,
> +conventional filenames are composed using the\~65 ASCII characters of the
> +POSIX Portable Filename Character Set.
> +The POSIX Portable Filename Character Set consists of the following.
> +.TP
> +.BR A \- Z
> +The\~26 capital or uppercase ASCII letters.
> +.TP
> +.BR a \- z
> +The\~26 small or lowercase ASCII letters.
> +.TP
> +.BR 0 \- 9
> +The ten ASCII digits.
> +.TP
> +.B . \_ \-
> +These three ASCII punctuators: full stop; low line; hyphen-minus.
> +.P
> +Special contexts often employ additional characters but, in general
> +contexts for international applications, conventional filenames exclude
> +characters other than the listed\~65.
> +(For noninternational applications, see
> +.B LOCALES AND UNICODE
> +below.)
> +.P
> +Observe that the space\~\fB\(aq\0\(aq\fR or\~\fB\eu0020\fR is not listed
> +despite being an ASCII character.
> +Filenames that include spaces are often encountered for various reasons in
> +certain contexts, but such filenames are unconventional in general and are
> +inconvenient to use with tools.
> +Within filenames, the low line\~\fB\_\fR or hyphen-minus\~\fB\-\fR is
> +conventionally employed as necessary instead of the space.
> +(See
> +.B UNCONVENTIONAL FILENAMES
> +and, under
> +.B SOFT
> +.BR CONVENTIONS ,
> +also
> +.B Low line versus hyphen-minus
> +below.)
> +.P
> +Incidentally, capital and small letters are distinct within filenames on a
> +Linux system; so, for example,
> +.I README
> +and
> +.I readme
> +name two different files.
> +(Under
> +.B SOFT
> +.BR CONVENTIONS ,
> +see
> +.B Capitalization > +below for further observations regarding capitalization.)
Maybe a mention to filesystems is warranted here.
FAT on Linux is still case-insensitive, right?
> +.SS Special semantics
> +.P
> +Besides the last subsection's POSIX convention, a pair of conventions
s/a pair of/some/
The third one being '-'.
> +derived from core utilities is almost always respected, as well.
> +.TP
> +.BR \- name
> +A name that begins with a hyphen-minus is conventionally interpreted as a
> +command-line option rather than as a filename.
> +Therefore, conventional filenames do not begin with the hyphen-minus.
> +.TP
> +.BR . name
> +Conventional filenames may indeed begin with the full stop.
> +However, such filenames conventionally designate
> +.I hidden files
> +(or hidden directories, etc.), a familiar example being the
> +.I .profile
> +typically found in a user's home directory.
> +Hidden files behave normally but, by default, are ignored by
> +.BR ls (1)
> +and certain other tools.
> +.P
I'd also add here (for consistency):
.TP
.B \-
> +The one-character name\~\fB\-\fR consisting of a lone hyphen-minus is
> +sometimes understood by a shell to refer to the previous working directory
> +and sometimes understood by tools to refer to standard input or standard
> +output, so convention does not employ the lone hyphen-minus as a file's
> +proper name.
> +The one-character name\~\fB.\fR consisting of a lone full stop has already
> +been mentioned under
Why talk about '.' here but not '..'?
Anyway, '.' is not a convention but a reserved name, so I think it
shouldn't be mentioned here.
> +.B LEGAL FILENAMES
> +above: one cannot use it as a file's proper name at all.
> +.SS The full stop to introduce a format extension
> +.P
> +Other than at a filename's beginning (a case the last subsection has
> +discussed), the full stop is employed in filenames for various further
> +conventional purposes.
> +No single rule governs all conventional uses of the full stop.
> +.P
> +However, except at a filename's beginning, the most common conventional use
> +of the full stop is to append to a filename's stem an extension to indicate
> +the format of the file's contents.
> +An example is the filename
> +.IR UnicodeData.txt ,
> +in which
> +.I UnicodeData
> +is the stem and the\~\fI.txt\fR indicates that the file contains plain
> +text.
> +Multiple format extensions are even appended to some filename stems, as in
> +.I my-archive.tar.xz
> +for instance, which is the name of a tape archive
> +.I my-archive.tar
> +that, after archival, has subsequently been compressed by
> +.BR xz (1).
> +.P
> +The format-extension convention is all but universally recognized.
Non-native English speakers may have trouble understanding "all but".
Maybe s/all but/not/?
> +Even nontechnical users are typically familiar with it.
> +However, many users employ full stops also for various purposes unrelated
> +to format extensions, as well; and they do so often enough that such
> +unrelated usage can hardly be called unconventional.
> +Except at a filename's beginning, convention supports free use of the full
> +stop.
> +.P
> +.I You
> +may reserve the full stop solely to append format extensions if you wish,
> +of course.
> +Many users do.
> +.P
> +.\" The next sentence has been corrected according
> +.\" to Charles Plessy's helpful
> +.\" advice [https://lists.debian.org/debian-devel/2021/08/msg00557.html].
> +(If your machine is configured as a desktop or laptop rather than as a
> +server, then you can probably find a fairly comprehensive catalog of
> +conventional filename extensions, identifying the format each extension
> +implies, on your machine in a file such as
> +.I /etc/mime.types
> +or
> +.IR /usr/share/mime/globs .)
> +.SH SOFT CONVENTIONS
> +.P
> +Further filenaming conventions are softer.
> +Though often observed, such softer conventions can be bent or broken
> +without rendering filenames unconventional.
> +.P
> +This section introduces soft conventions for filenames.
> +.SS Low line versus hyphen-minus
> +.P
> +Whether to use the low line\~\fB\_\fR or the hyphen-minus\~\fB\-\fR in
> +filenames is a matter of preference.
> +Except as stated above, convention does not strongly prefer the one over
> +the other.
> +.P
> +If you would like advice, anyway, however, then the kernel's source sets an
> +example.
> +Most filenames in the kernel's source prefer the hyphen-minus.
> +You can do the same if you wish.
> +.P
> +Even if you prefer the hyphen-minus, though, some exceptions arise, as
> +follows.
> +.IP \(bu
> +The contents of a program's source files usually designate various
> +.I entities
> +such as variables, functions, types and so forth.
> +In\~C and similar programming languages, the hyphen-minus is a minus sign,
> +so the designations of entities must use the low line, instead.
> +Where a file is named after an entity the file introduces, the filename
> +should use low lines as the entity's designation does.
> +Examples include the file
> +.IR lock\_events.h ,
> +which introduces the entity
> +.IR lock\_events ,
> +in the kernel's source.
> +.IP \(bu
> +Where distinct separators with different semantics are required, a filename
> +can use the low line as an alternate separator.
> +Examples include the file
> +.IR coreutils\_8.30-3\_amd64.deb ,
> +which provides revision\~3 of the Debian binary package that installs
> +version\~8.30 of the GNU core utilities for the amd64/x86-64 architecture.
> +.IP \(bu
> +Occasionally, the name of a file that provides private, internal,
> +ephemeral, uninterfaceable or undocumented aspects of an implementation
> +will
> +.I begin
> +with a low line to hint that the file
> +.RS
> +.IP +
> +does not require the user's or programmer's attention or
> +.IP +
> +is unsuitable for external agents to access directly.
> +.RE
> +.IP
> +Examples include the file
> +.\" On the author's PC using Groff's default output device, Groff typesets
> +.\" the next line's italicized low line inconsistently compared to the
> +.\" manual page's other italicized low lines. Presumably, Groff does this
> +.\" because the low line in question begins its word (though why Groff
> +.\" thinks beginning the word significant is unclear), but the
> +.\" inconsistency is slightly distracting.
> +.I \_sd-common.h
> +in systemd's source.
> +.IP \(bu
> +Sometimes, the low line stands for an unspecified letter of the alphabet.
> +.P
> +Otherwise, despite that the low line and the hyphen-minus are both
> +conventional, if you want advice: prefer the hyphen-minus.
> +.SS Capitalization
> +.P
> +A loosely observed convention favors small letters in filenames where no
> +reason to use capitals exists.
Most manual pages talking about capitalization typically use the term
'case' (uppercase, lowercase, case sensitive, ...); probably because of
'toupper()' and 'tolower()'. I think, for consistency, using the same
terminology would be better.
Or is it Unicode terminology you were using?
> +Many exceptions occur, though, as for example the oft-encountered
> +.I Makefile
> +that instructs
> +.BR make (1)
> +how to build an executable program or other autogeneratable file.
> +.P
> +The reason convention favors small letters is that the general use of small
> +letters leaves the capital letters to be employed for emphasis.
> +Where the default\~C (or C.UTF-8) locale is in use, the capital ASCII
> +letters are collated before all the small ones, whereby
> +.BR ls (1)
> +lists filenames like
> +.I Makefile
> +and
> +.I README
> +before filenames like
> +.I a.out
> +and
> +.IR foo.c .
> +[If your locale causes
> +.BR ls (1)
> +to collate differently when you would have preferred the just-described
> +default collation, then try
> +.B LC\_ALL=C ls
> +or
> +.B LC\_ALL=C.UTF-8 ls
> +to suppress the locale.
> +See
> +.BR locale (7).]
> +.P
> +Names of types and of certain other entities are sometimes capitalized in
> +programming languages like\~C++ and Python.
Do you mean normal user conventions? I mean, the standard C++ library
(and the language) doesn't use uppercase, AFAIR. Not even in the cases
where C used it (e.g., _Bool)
> +Such capitalization can spill over to affect filenames, so it is hard to
> +state a general rule.
> +.SH LOCALES AND UNICODE
> +.\" If another subsection were added to the manual page, then this section
> +.\" might be demoted to a subsection and, if appropriate, grouped with the
> +.\" new subsection together under a new section
> +.\" entitled "FURTHER CONSIDERATIONS."
> +.P
> +If your application is local rather than international, then you can relax
> +POSIX's aforementioned character-set convention at your discretion by
> +including graphic Unicode characters; specifically, by including non-ASCII
> +Unicode characters for which
> +.BR iswgraph (3)
> +returns true in your locale or (if your system has it) in the C.UTF-8
> +locale.
> +[For the relationship between
> +.BR unicode (7),
> +.BR utf-8 (7)
> +and
> +.BR ascii (7),
> +see the respective manual pages.
> +Approximately, in brief, Unicode is a character set, UTF-8 is a
> +byte-oriented scheme by which Unicode characters can be encoded, and ASCII
> +is both a character set and a byte-oriented scheme that is a subset of both
> +Unicode and UTF-8.]
> +.P
> +To suggest an exact noninternational filenaming rule, other than the
> +.BR iswgraph (3)
> +rule, for every locale would exceed the scope of this manual page; but
> +approximately, in a Japanese or French application for instance, a filename
> +might respectively include kanji ideographs or accented Latin letters.
> +Filenames that include kanji ideographs or accented Latin letters might be
> +hard for international users to read or type, but insofar as such filenames
> +exclude spaces, control characters, ASCII symbols (like\~\fB$\fR
> +or\~\fB=\fR), and ASCII punctuators other than the three punctuators POSIX
> +recommends, such filenames will not normally cause trouble for tools and,
> +thus, may be regarded as conventional within the local context.
> +.P
> +The use of nonbreaking spaces like\~\fB\eu00A0\fR, \fB\eu2007\fR,
> +\fB\eu202F\fR or\~\fB\euFEFF\fR in filenames is probably inadvisable for
> +most locales, despite that
> +.BR iswgraph (3)
> +returns true.
> +[The use of ordinary, breaking spaces like\~\fB\eu0020\fR (the familiar
> +ASCII space), \fB\eu1680\fR, \fB\eu2000\fR through\~\fB\eu2006\fR,
> +\fB\eu2008\fR, \fB\eu2009\fR, \fB\eu200A\fR, \fB\eu205F\fR
> +and\~\fB\eu3000\fR is probably also inadvisable, but
> +.BR iswgraph (3)
> +returns false for those, anyway.]
> +.SH UNCONVENTIONAL FILENAMES
> +.P
> +More than a few files on a typical Linux system, occasionally even
> +including standard files employed by and/or automatically installed by an
> +operating-system distribution, have unconventional filenames.
> +For example, on a Debian GNU/Linux system, some names of files that supply
> +software packages use the characters\~\fB+\fR and\~\fB\(ti\fR which, though
> +unconventional in general, are normal and expected within that context.
> +For another example, in the kernel's source, certain filenames use the
> +character\~\fB,\fR to separate a device's designator from the name of the
> +device's manufacturer.
> +You may have noticed the unconventionally-named
> +.I lost+found
> +directory lurking at a filesystem's root on your computer; and there are
> +further examples, as well.
> +.P
> +There are many reasons to use unconventional filenames.
> +.P
> +It is hard to give a general rule, with respect to a particular context, as
> +to which unconventional filenames are likely to cause practical troubles
> +and which are not.
> +If unsure, you can avoid troubles by adhering to convention; but if you
> +wish or need to depart from convention, then the only suggestions this
> +manual page would make are
> +.IP \(bu
> +that unconventional filenames not be used without context;
> +.IP \(bu
> +that unconventional filenames not be used without reason;
> +.IP \(bu
> +that, even where filenames are unconventional, the recommendations of
> +.B Special semantics
> +above still be followed if practicable;
> +.IP \(bu
> +that, where several unconventionally named files are collected, the use of
> +unconventional characters be systematic (for example,
> +.IR 16:30.log ,
> +.IR 16:45.log ,
> +.I 17:00.log
> +and so on);
> +.IP \(bu
> +that, even if unconventional symbols or punctuators are employed within
> +filenames, one think twice before
> +.I beginning
> +a filename with an unconventional symbol or punctuator; specifically,
> +before beginning a filename with a nonalphanumeric ASCII character other
> +than the full stop or low line (consider for example a filename that began
> +with the\~\fB\(ti\fR or\~\fB$\fR symbol, which a shell might misinterpret
> +as it were a reference to a home directory or shell parameter);
> +.IP \(bu
> +that, even if non-POSIX characters are used, non-ASCII characters be
> +avoided to the extent to which the application is international;
> +.IP \(bu
> +that the shell's four standard globbing characters\~\fB*?[]\fR be avoided
> +in most instances; and
> +.IP \(bu
> +even if none of the other suggestions is followed, that control characters
> +be avoided in any event,
> +.I control characters
> +being characters, including the tab\~\fB\et\fR and line-feed\~\fB\en\fR
> +characters, for which
> +.BR iswcntrl (3)
> +returns true.
> +(Note that, although the use of the space in filenames contravenes POSIX
> +and anyway annoys many Linux users, the space is the sole nongraphic ASCII
> +character that, by definition, is not a control character.
> +Spaces in filenames are unconventional and perhaps inadvisable, but they
> +are hardly unusual; whereas tabs and line feeds are, for good reason,
> +practically never seen.)
> +.SH CONFORMING TO
> +.P
> +POSIX.1-2008, SUSv4.
The SUSv4 part of the standard is the same that is in POSIX.1-2008? Or
does it have any extensions regarding filenames that isn't in POSIX?
If both standards have the same exact contents about filenames, I'd
simplify this with POSIX.1-2008 only.
> +.SH SEE ALSO
> +.P
> +.BR ls (1),
> +.BR sh (1),
> +.BR iswcntrl (3),
> +.BR iswgraph (3),
> +.BR mbrtowc (3),
> +.BR wcrtomb (3),
> +.BR ext4 (5),
> +.BR ascii (7),
> +.BR locale (7),
> +.BR unicode (7),
> +.BR utf-8 (7)
maybe filesystems(7)?
> +.P
> +info
> +.B coreutils
> +.\" The author, Thaddeus H. Black, thanks his wife Kristie, daughter Naomi
> +.\" and son George for their review and proofreading of various parts of
> +.\" this manual page.
>
--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
[Cc recipients: this message is only about typography and man(7) style]
Hi Alex,
At 2021-09-06T16:21:09+0200, Alejandro Colomar (man-pages) wrote:
> > +.TH FILENAME 7 2021-09-06 "Linux" "Linux Programmer's Manual"
> > +.SH NAME
> > +.P
>
> I don't know the history of this (actually, I've always wondered why),
> but .PP and .P are equivalent, AFAIK, and we use .PP.
Yes, they are equivalent. I know of no man(7) implementation that
distinguishes .LP, .PP, and .P semantically. groff_man(7)[1] briefly
summarizes the historical growth of the man(7) macro, register, and
string name repertoire.
In the groff project, after years of being on the fence about the issue,
as a style matter I settled on using and recommending simply ".P"[2]. I
think it relieves the occasional man page author from having to retain
a small amount of knowledge, the kind that has you wondering above.
> > +.SH LEGAL FILENAMES
>
> See man-pages(7):
>
> Sections within a manual page
> The list below shows conventional or suggested sections.
> Most manual pages should include at least the highlighted
> sections. Arrange a new manual page so that sections are
> placed in the order shown in the list.
>
> NAME
> SYNOPSIS
> CONFIGURATION [Normally only in Section 4]
> DESCRIPTION
> OPTIONS [Normally only in Sections 1, 8]
> EXIT STATUS [Normally only in Sections 1, 8]
> RETURN VALUE [Normally only in Sections 2, 3]
> ERRORS [Typically only in Sections 2, 3]
> ENVIRONMENT
> FILES
> VERSIONS [Normally only in Sections 2, 3]
>
> ATTRIBUTES [Normally only in Sections 2, 3]
> CONFORMING TO
> NOTES
> BUGS
> EXAMPLES
> AUTHORS [Discouraged]
> REPORTING BUGS [Not used in man‐pages]
> COPYRIGHT [Not used in man‐pages]
> SEE ALSO
>
> Where a traditional heading would apply, please use it;
> this kind of consistency can make the information easier to
> understand. If you must, you can create your own headings
> if they make things easier to understand (this can be espe‐
> cially useful for pages in Sections 4 and 5). However, be‐
> fore doing this, consider whether you could use the tradi‐
> tional headings, with some subsections (.SS) within those
> sections.
>
> You could move sections into subsections of DESCRIPTION, and the
> current subsections into tagged paragraphs (.TP).
In the groff man page corpus, the rule above is honored in general but
slightly relaxed for section 7 pages, due to that section's
miscellaneous nature--it's hard to argue that section naming conventions
for commands, library interfaces, device drivers, or file formats should
apply to section 7 pages, because if they did, the page in question
would be in one of those sections instead (or portions of it moved
thence).
> > +.P
> > +A filename on a Linux system can consist of almost any sequence of UTF-8
>
> See man-pages(7):
>
> Use semantic newlines
> In the source of a manual page, new sentences should be
> started on new lines, and long sentences should be split
> into lines at clause breaks (commas, semicolons, colons,
> and so on). This convention, sometimes known as "semantic
> newlines", makes it easier to see the effect of patches,
> which often operate at the level of individual sentences or
> sentence clauses.
>
>
> > +characters or, indeed, almost any sequence of bytes.
> > +The exceptions are as follows.
Maybe I've developed temporary blindness, but I don't see where Thaddeus
didn't use semantic newlines in the adjacent quoted material.
> Please, use a separate line and
> .B \e0
>
> We avoid \f.
Yes! Thus does the moral arc of the universe bend toward justice!
...or at least readable man(7) source.
> > +from\~\fB0\fR, the printable digit-zero character.
>
> Why did you use the non-breaking space here (and other places)? I
> don't think it's necessary.
It is a typographical best practice. It is often good typography to
keep a line break from occurring between a preposition and its object,
or between nouns where one is used as a determiner for the other.
Thaddeus has supplied an example of the former above, and for the latter
consider the following[3].
Integer overflow is guaranteed for large values
.RI of\~ n .
I know of no hard rule here, but I have inferred that such break
prevention tends to be applied much more frequently adjacently to one-
or two-character nouns, and seldom to never for longer ones. I believe
the reason for the practice is to make reading more comfortable; it
would be nice to only _ever_ break lines at phrase and clause
boundaries, but applying a hard rule along these lines leads to worse
esthetics (if the line is adjusted to both margins with large amounts of
inter-word space) or ergonomics (if the line length varies dramatically
within a paragraph).
> > +Workarounds typically exist, chiefly via quotation, escape and the
> > explicit +termination of options processing [see
> > +.BR sh (1)];
>
> I'd have used parentheses there. No? Was it, as in Mathematics, to
> clearly differentiate the inner from the outer parentheses? If so, we
> typically nest parentheses in the manual pages (as in here (see?)).
>
> However, I don't think it's wrong per se to use brackets... Is it
> common in other places? Maybe the add some readability to the text,
> and we hould use them.
English style manuals tend to discourage the Lisp effect of nested
parentheses[5]. The reference I've cited is consistent with other
practices I've seen in the humanities, which is to turn to parentheses
as a first resort and then adopt brackets only when already within a
parenthesized context, whereas mathematical usage is to apply
parentheses to the innermost level of nesting.
Here, however, it would be jarring to change the man page citation style
in a context-dependent manner, so Thaddeus inverted the ordering. This
is a good practice. In technical writing, and arguably in _all_
writing, the demands of clarity must outweigh any syntactical or
semantic rules. Our brains are more powerful parsing engines than any
machine we have yet been able to contrive; it's okay to expect people to
use them. :D
That blank check having been written, a Hegelian synthesis applies: if
your construction cannot simultaneously serve the demands of grammar,
clarity, and good style...recast until it does!
> Non-native English speakers may have trouble understanding "all but".
> Maybe s/all but/not/?
I think it's okay. From my limited knowledge of non-English languages,
I expect it to calque in a way that will not startle the intuition.
Personally, I acquired the construction when I was in primary school,
but I admit that saying so invites a charge of being anecdotal. Or
precocious. Or loquacious.
> > +.SS Capitalization
> > +.P
> > +A loosely observed convention favors small letters in filenames where no
> > +reason to use capitals exists.
>
> Most manual pages talking about capitalization typically use the term
> 'case' (uppercase, lowercase, case sensitive, ...); probably because
> of 'toupper()' and 'tolower()'. I think, for consistency, using the
> same terminology would be better.
This circle could be squared with the subsection heading "Letter case".
> > +.P
> > +Names of types and of certain other entities are sometimes capitalized in
> > +programming languages like\~C++ and Python.
>
> Do you mean normal user conventions? I mean, the standard C++ library
> (and the language) doesn't use uppercase, AFAIR. Not even in the
> cases where C used it (e.g., _Bool)
Stroustrup models first-letter capitalization of namespace, exception,
class, and struct names in _The C++ Programming Language_ (3rd edition,
1997), so it's reasonably likely to show up in projects written in that
language even if it's not in the standard library (which is much too
huge for me to characterize in this respect).
> > +.SH CONFORMING TO
> > +.P
> > +POSIX.1-2008, SUSv4.
> The SUSv4 part of the standard is the same that is in POSIX.1-2008?
> Or does it have any extensions regarding filenames that isn't in
> POSIX?
>
> If both standards have the same exact contents about filenames, I'd
> simplify this with POSIX.1-2008 only.
Thaddeus is using a citation form modeled in standards(7), a Linux
man-pages project page. Perhaps that page should offer some guidance
for standards that appear in a comma-separated list in the paragraph
tags.
> > +.BR iswcntrl (3),
> > +.BR iswgraph (3),
> > +.BR mbrtowc (3),
> > +.BR wcrtomb (3),
I think it suffices to mention these functions only in passing in the
body of the man page. Few readers are going to go straight from
learning what a Unix filename is to multi-byte and wide character string
encoding in C, and the few with that degree of ambition have already
been steered in the right direction.
In my opinion the "See also" section of a man page serves us best if
there are two things it is _not_:
(1) a recapitulation of all man page cross-references encountered in the
page so far; and
(2) a militantly strict subset of (1).
In my view, "See also" is there to help two kinds of reader:
(A) the kind who has not found the man page they were seeking, but might
be in the right "neighborhood", and needs a hint to find the correct
one (a wholly irrelevant page is best abandoned, and the output of
"man -k" returned to); and
(B) the kind who has found the page they are looking for but require
greater depth on subsidiary, dependent, or closely-related topics.
As with many things, identifying the members of such a set demands
judgment, and judgment can be difficult, which is why some man page
writers have a tendency to degenerate toward the more robotic
interpretation that I discourage above. But if that roboticism is what
is sought, we should design a robot to take care of it. One such
automaton could be a man page cross-reference macro like mdoc(7) has
(possibly with an optional argument to suppress inclusion for case (2)
above), enabling the macro package to generate the "See also" section by
itself.
But I think that machine is something we _don't_ want[5]. We _want_ the
"See also" section of a man page to be a curated product of judgment.
Regards,
Branden
[1] https://man7.org/linux/man-pages/man7/groff_man.7.html
[2] https://git.savannah.gnu.org/cgit/groff.git/commit/?id=cf49e0fe7fdbaff94e21ebdcd3380c3559c2525d
commit cf49e0fe7fdbaff94e21ebdcd3380c3559c2525d
Author: G. Branden Robinson <[email protected]>
Date: Wed Jun 16 00:24:38 2021 +1000
[man]: Elevate "P" as canonical paragraph macro.
Unfairly and capriciously elevate "P" as the preferred paragraphing
macro for the man(7) language. This is slightly ahistorical; the
original man macro package from 1979 in fact did not recognize the
name "P" at all, but did support "LP" and "PP".
However, "P" did show up in AT&T System III Unix (1980) and later in
4.3BSD (1986). I speculate that "LP" and "PP" were supported to
accommodate the varying paragraphing preferences of those accustomed
to the ms(7) macro package. However, anyone familiar with that
package knows that these two macros mean different things, and have
differing indentation behavior, which man(7) does not simulate. In
that respect, "LP" and "PP" imply too much to ms veterans, and
nothing useful at all to other man(7) users; the "L" and first "P"
are superfluous.
Further, ".P" is frequently typed, and per sound principles of
Huffman coding, it should be short. Thus do I hope to buy the
complaisance of grognards with the cheap bribe of "less typing", a
preoccupation whose star has not dimmed among Unix geeks in 50
years.
* tmac/an-old.tmac (P): Define this is as the "canonical"
paragraphing macro.
(LP, PP): Make these aliases of P.
[3] You could also say the following.
Integer overflow is guaranteed for large values of\~\c
.IR n .
But I discourage the use of \c except where necessary because it tends
to confuse people (although in groff Git HEAD I've finally got this
escape sequence described carefully enough that it no longer maddens me
as it did when I first became a contributor[6]). In the above, if we
omit the output line continuation escape sequence \c, then the line can
break after "of" because that's what a newline in the *roff input stream
_means_.
[4] https://www.eliteediting.com.au/parentheses-within-parentheses/
[5] I do still want an "MR" man page cross referencing macro[7] (and
mandoc(1) maintainer Ingo Schwarze is still trying to talk me out of
it), but not so that "See also" can be autogenerated.
[6] https://man7.org/linux/man-pages/man7/groff.7.html#Line_continuation
[7] https://lists.gnu.org/archive/html/groff/2021-08/msg00000.html
Hi Branden and Thaddeus,
On 9/6/21 6:59 PM, G. Branden Robinson wrote:
>> You could move sections into subsections of DESCRIPTION, and the
>> current subsections into tagged paragraphs (.TP).
>
> In the groff man page corpus, the rule above is honored in general but
> slightly relaxed for section 7 pages, due to that section's
> miscellaneous nature--it's hard to argue that section naming conventions
> for commands, library interfaces, device drivers, or file formats should
> apply to section 7 pages, because if they did, the page in question
> would be in one of those sections instead (or portions of it moved
> thence).
I would still use DESCRIPTION, I think. I think we don't lose much by
using subsections instead, and we gain consistency.
>
>>> +.P
>>> +A filename on a Linux system can consist of almost any sequence of UTF-8
>>
>> See man-pages(7):
>>
>> Use semantic newlines
>> In the source of a manual page, new sentences should be
>> started on new lines, and long sentences should be split
>> into lines at clause breaks (commas, semicolons, colons,
>> and so on). This convention, sometimes known as "semantic
>> newlines", makes it easier to see the effect of patches,
>> which often operate at the level of individual sentences or
>> sentence clauses.
>>
>>
>>> +characters or, indeed, almost any sequence of bytes.
>>> +The exceptions are as follows.
>
> Maybe I've developed temporary blindness, but I don't see where Thaddeus
> didn't use semantic newlines in the adjacent quoted material.
"UTF-8" is an adjective to "characters"; I'd break just after "of",
since everything after it is a single nominal phrase (I hope I used the
correct term; I only did syntactical analysis in Spanish at school).
There were more obvious points below that infringed this rule, but I
wanted to point out the first one.
>
>> Please, use a separate line and
>> .B \e0
>>
>> We avoid \f.
>
> Yes! Thus does the moral arc of the universe bend toward justice!
>
> ...or at least readable man(7) source.
>
>>> +from\~\fB0\fR, the printable digit-zero character.
>>
>> Why did you use the non-breaking space here (and other places)? I
>> don't think it's necessary.
>
> It is a typographical best practice. It is often good typography to
> keep a line break from occurring between a preposition and its object,
> or between nouns where one is used as a determiner for the other.
> Thaddeus has supplied an example of the former above, and for the latter
> consider the following[3].
>
> Integer overflow is guaranteed for large values
> .RI of\~ n .
>
> I know of no hard rule here, but I have inferred that such break
> prevention tends to be applied much more frequently adjacently to one-
> or two-character nouns, and seldom to never for longer ones. I believe
> the reason for the practice is to make reading more comfortable; it
> would be nice to only _ever_ break lines at phrase and clause
> boundaries, but applying a hard rule along these lines leads to worse
> esthetics (if the line is adjusted to both margins with large amounts of
> inter-word space) or ergonomics (if the line length varies dramatically
> within a paragraph).
Okay, looks good to me.
>
>>> +Workarounds typically exist, chiefly via quotation, escape and the
>>> explicit +termination of options processing [see
>>> +.BR sh (1)];
>>
>> I'd have used parentheses there. No? Was it, as in Mathematics, to
>> clearly differentiate the inner from the outer parentheses? If so, we
>> typically nest parentheses in the manual pages (as in here (see?)).
>>
>> However, I don't think it's wrong per se to use brackets... Is it
>> common in other places? Maybe the add some readability to the text,
>> and we hould use them.
>
> English style manuals tend to discourage the Lisp effect of nested
> parentheses[5].
Actually, [4].
Okay, logically it seems good to me; more so when Mathematical language
already uses that. I didn't know if it was typically used in prose, as
I haven't seen its usage in Spanish, but since you referenced a guide
that recommends its usage, it seems fair.
> The reference I've cited is consistent with other
> practices I've seen in the humanities, which is to turn to parentheses
> as a first resort and then adopt brackets only when already within a
> parenthesized context, whereas mathematical usage is to apply
> parentheses to the innermost level of nesting.
>
> Here, however, it would be jarring to change the man page citation style
> in a context-dependent manner, so Thaddeus inverted the ordering. This
> is a good practice. In technical writing, and arguably in _all_
> writing, the demands of clarity must outweigh any syntactical or
> semantic rules. Our brains are more powerful parsing engines than any
> machine we have yet been able to contrive; it's okay to expect people to
> use them. :D
>
> That blank check having been written, a Hegelian synthesis applies: if
> your construction cannot simultaneously serve the demands of grammar,
> clarity, and good style...recast until it does!
I'll go for the brackets in the outer ones, as Maths do, as Thaddeus
did, and as you pointed out, as man references already use () and
changing those would be weird at least; printf[3] seems like you're
pointing to a [3] at the bottom of a page.
>
>> Non-native English speakers may have trouble understanding "all but".
>> Maybe s/all but/not/?
>
> I think it's okay. From my limited knowledge of non-English languages,
> I expect it to calque in a way that will not startle the intuition.
> Personally, I acquired the construction when I was in primary school,
> but I admit that saying so invites a charge of being anecdotal. Or
> precocious. Or loquacious.
I have trouble myself when reading those expressions, especially when
mixing that with another negation. I have to mentally cancel out
negations first :D
>
>>> +.SS Capitalization
>>> +.P
>>> +A loosely observed convention favors small letters in filenames where no
>>> +reason to use capitals exists.
>>
>> Most manual pages talking about capitalization typically use the term
>> 'case' (uppercase, lowercase, case sensitive, ...); probably because
>> of 'toupper()' and 'tolower()'. I think, for consistency, using the
>> same terminology would be better.
>
> This circle could be squared with the subsection heading "Letter case".
>
>>> +.P
>>> +Names of types and of certain other entities are sometimes capitalized in
>>> +programming languages like\~C++ and Python.
>>
>> Do you mean normal user conventions? I mean, the standard C++ library
>> (and the language) doesn't use uppercase, AFAIR. Not even in the
>> cases where C used it (e.g., _Bool)
>
> Stroustrup models first-letter capitalization of namespace, exception,
> class, and struct names in _The C++ Programming Language_ (3rd edition,
> 1997), so it's reasonably likely to show up in projects written in that
> language even if it's not in the standard library (which is much too
> huge for me to characterize in this respect).
Okay.
>
>>> +.SH CONFORMING TO
>>> +.P
>>> +POSIX.1-2008, SUSv4.
>> The SUSv4 part of the standard is the same that is in POSIX.1-2008?
>> Or does it have any extensions regarding filenames that isn't in
>> POSIX?
>>
>> If both standards have the same exact contents about filenames, I'd
>> simplify this with POSIX.1-2008 only.
>
> Thaddeus is using a citation form modeled in standards(7), a Linux
> man-pages project page. Perhaps that page should offer some guidance
> for standards that appear in a comma-separated list in the paragraph
> tags.
Yes, that's something that could go into man-pages(7). We had a similar
discussion about this when designing system_data_types(7).
There, we only cared about the C standard and the POSIX standard, and
only the first one of each that standardized the type. If a type were
only in SUSv4 and not in POSIX, we would use SUSv4 for that type, but
that hasn't happened yet in the types we documented.
Example:
Conforming to: C99 and later; POSIX.1‐2001 and later.
While we don't have a written rule, I'd use that one for now.
Of course if something is in POSIX.1-2008, it must be in SUSv4 (as it is
a superset of POSIX), so to simplify, we'll omit that.
>
>>> +.BR iswcntrl (3),
>>> +.BR iswgraph (3),
>>> +.BR mbrtowc (3),
>>> +.BR wcrtomb (3),
>
> I think it suffices to mention these functions only in passing in the
> body of the man page. Few readers are going to go straight from
> learning what a Unix filename is to multi-byte and wide character string
> encoding in C, and the few with that degree of ambition have already
> been steered in the right direction.
>
> In my opinion the "See also" section of a man page serves us best if
> there are two things it is _not_:
>
> (1) a recapitulation of all man page cross-references encountered in the
> page so far; and
> (2) a militantly strict subset of (1).
>
> In my view, "See also" is there to help two kinds of reader:
>
> (A) the kind who has not found the man page they were seeking, but might
> be in the right "neighborhood", and needs a hint to find the correct
> one (a wholly irrelevant page is best abandoned, and the output of
> "man -k" returned to); and
> (B) the kind who has found the page they are looking for but require
> greater depth on subsidiary, dependent, or closely-related topics.
>
> As with many things, identifying the members of such a set demands
> judgment, and judgment can be difficult, which is why some man page
> writers have a tendency to degenerate toward the more robotic
> interpretation that I discourage above. But if that roboticism is what
> is sought, we should design a robot to take care of it. One such
> automaton could be a man page cross-reference macro like mdoc(7) has
> (possibly with an optional argument to suppress inclusion for case (2)
> above), enabling the macro package to generate the "See also" section by
> itself.
>
> But I think that machine is something we _don't_ want[5]. We _want_ the
> "See also" section of a man page to be a curated product of judgment.
Agree.
>
> Regards,
> Branden
>
> [1] https://man7.org/linux/man-pages/man7/groff_man.7.html
>
> [2] https://git.savannah.gnu.org/cgit/groff.git/commit/?id=cf49e0fe7fdbaff94e21ebdcd3380c3559c2525d
>
> commit cf49e0fe7fdbaff94e21ebdcd3380c3559c2525d
> Author: G. Branden Robinson <[email protected]>
> Date: Wed Jun 16 00:24:38 2021 +1000
>
> [man]: Elevate "P" as canonical paragraph macro.
>
> Unfairly and capriciously elevate "P" as the preferred paragraphing
> macro for the man(7) language. This is slightly ahistorical; the
> original man macro package from 1979 in fact did not recognize the
> name "P" at all, but did support "LP" and "PP".
>
> However, "P" did show up in AT&T System III Unix (1980) and later in
> 4.3BSD (1986). I speculate that "LP" and "PP" were supported to
> accommodate the varying paragraphing preferences of those accustomed
> to the ms(7) macro package. However, anyone familiar with that
> package knows that these two macros mean different things, and have
> differing indentation behavior, which man(7) does not simulate. In
> that respect, "LP" and "PP" imply too much to ms veterans, and
> nothing useful at all to other man(7) users; the "L" and first "P"
> are superfluous.
>
> Further, ".P" is frequently typed, and per sound principles of
> Huffman coding, it should be short. Thus do I hope to buy the
> complaisance of grognards with the cheap bribe of "less typing", a
> preoccupation whose star has not dimmed among Unix geeks in 50
> years.
>
> * tmac/an-old.tmac (P): Define this is as the "canonical"
> paragraphing macro.
>
> (LP, PP): Make these aliases of P.
I like that reasoning. I'd like to be able to use .P. But that would
mean adding even more inconsistency to the man-pages (of course we
wouldn't change existing pages to use .P at this point).
>
> [3] You could also say the following.
>
> Integer overflow is guaranteed for large values of\~\c
> .IR n .
>
> But I discourage the use of \c except where necessary because it tends
> to confuse people (although in groff Git HEAD I've finally got this
> escape sequence described carefully enough that it no longer maddens me
> as it did when I first became a contributor[6]). In the above, if we
> omit the output line continuation escape sequence \c, then the line can
> break after "of" because that's what a newline in the *roff input stream
> _means_.
>
> [4] https://www.eliteediting.com.au/parentheses-within-parentheses/
>
> [5] I do still want an "MR" man page cross referencing macro[7] (and
> mandoc(1) maintainer Ingo Schwarze is still trying to talk me out of
> it), but not so that "See also" can be autogenerated.
I keep reading that list :)
>
> [6] https://man7.org/linux/man-pages/man7/groff.7.html#Line_continuation
> [7] https://lists.gnu.org/archive/html/groff/2021-08/msg00000.html
>
Thanks as always for your great contributions, Branden!
Regards,
Alex
--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
[Cc recipients: more typography and man(7) style issues]
Hi Alex,
At 2021-09-06T23:47:37+0200, Alejandro Colomar (man-pages) wrote:
> On 9/6/21 6:59 PM, G. Branden Robinson wrote:
> > In the groff man page corpus, the rule above is honored in general
> > but slightly relaxed for section 7 pages, due to that section's
> > miscellaneous nature--it's hard to argue that section naming
> > conventions for commands, library interfaces, device drivers, or
> > file formats should apply to section 7 pages, because if they did,
> > the page in question would be in one of those sections instead (or
> > portions of it moved thence).
>
> I would still use DESCRIPTION, I think.
I do as well[1]; while I haven't yet encountered a situation where it
seemed sensible to dispose of it, I would lend writers of section 7
pages that freedom.
> I think we don't lose much by using subsections instead, and we gain
> consistency.
I'm a little uneasy with some of the hacks I've seen to contrive
sub-subsections in man pages. I saw one within the past few months but
can't remember the specifics. Sending this mail may prompt my
recollection since that's how my memory seems to work. I'll follow up
if it does.
> > > See man-pages(7):
> > >
> > > Use semantic newlines
> > > In the source of a manual page, new sentences should
> > > be started on new lines, and long sentences should be
> > > split into lines at clause breaks (commas, semicolons,
> > > colons, and so on). This convention, sometimes known as
> > > "semantic newlines", makes it easier to see the effect
> > > of patches, which often operate at the level of
> > > individual sentences or sentence clauses.
> > >
> > Maybe I've developed temporary blindness, but I don't see where
> > Thaddeus didn't use semantic newlines in the adjacent quoted
> > material.
>
> "UTF-8" is an adjective to "characters"; I'd break just after "of",
> since everything after it is a single nominal phrase (I hope I used
> the correct term; I only did syntactical analysis in Spanish at
> school).
Ah, that's a "phrase" rather than a "clause". The terms are
distinguished in traditional (schoolhouse) English grammar; loosely, a
"phrase" is a set of words operating as a "part of speech" (noun, verb,
adjective, adverb) whereas a "clause" is a group of phrases with a
"subject" and a "predicate". Generally, sentence can be decomposed into
one or more clauses, each of which can itself be expressed as a sentence
with little or no recasting.
There's nothing about phrases or phrase boundaries in the guidance
quoted above. At first blush I would recommend against adding it
because it's harder to find such boundaries automatically. When I
revise man pages in the groff project it's easy to find clause
boundaries with the vi search pattern "/[;!?.]." (I usually add a
comma and a closing parenthesis to this pattern because I also prefer to
break after commas and multi-word parentheticals, but I'm not militant
about prescribing this expanded sense of semantic newlines.))
Someone trained in linguistics at the university level could doubtless
speak about this subject with much greater precision. (And then there's
Huddleston and Pullum's iconoclastic _Cambridge Grammar of the English
Language_...)
> There were more obvious points below that infringed this rule, but I
> wanted to point out the first one.
I don't think most native English speakers are likely to interpret the
semantic newline rule as you do because we absorb a different denotation
of "clause" when we're taught elementary formal grammar.
> > It is a typographical best practice. It is often good typography to
> > keep a line break from occurring between a preposition and its
> > object, or between nouns where one is used as a determiner for the
> > other. Thaddeus has supplied an example of the former above, and
> > for the latter consider the following[3].
[...]
I goofed up the point I was trying to make here. I provided a duplicate
example of the case I attributed to Thaddeus. Let me try that again.
Overflow is guaranteed for a sufficiently large
.RI integer\~ n .
> > English style manuals tend to discourage the Lisp effect of nested
> > parentheses[5].
>
> Actually, [4].
Hah! I need a footnote assistance plug-in for Vim. I'm sure someone
will tell me that Emacs org-mode does this for them.
> I'll go for the brackets in the outer ones, as Maths do, as Thaddeus
> did, and as you pointed out, as man references already use () and
> changing those would be weird at least; printf[3] seems like you're
> pointing to a [3] at the bottom of a page.
Indeed so. In the next release of groff, ms will bracket footnotes like
this automatically in nroff mode (that is, for terminal output)[2]. I
recently noticed that the me(7) package does not, and I think it should.
> I have trouble myself when reading those expressions, especially when
> mixing that with another negation. I have to mentally cancel out
> negations first :D
It's a tough problem. When I was learning Spanish I had trouble
acquiring the practice of reinforcing negatives in sentences ("No
tenemos [no] dios, no tenemos [no] jefes."[??]) How many negatives do I
need? When do I stop?
Getting back to English, I would be over the moon if my fellow native
speakers would quit misrepresenting the logical negation of "all horses
are animals" as "all horses are not animals". You see and hear this all
the time, notoriously from journalists.
> I like that reasoning. I'd like to be able to use .P. But that would
> mean adding even more inconsistency to the man-pages (of course we
> wouldn't change existing pages to use .P at this point).
Granted. What I do with groff's man pages is that I tend to queue up
style fixes (mentally if nothing else), applying them when I have a
content fix to make to a page. Over time, things settle into a new
consistency, but patience is required if churn or flag days are to be
avoided.
> I keep reading that list :)
I'm glad you're still there!
Regards,
Branden
[1] ...except in mixed case since groff 1.23.0 will support this.[3] :)
[2] https://git.savannah.gnu.org/cgit/groff.git/commit/?id=caeede07cd2e6e10134385cca194c52342f46972
[3] https://git.savannah.gnu.org/cgit/groff.git/commit/?id=9503b794e821ef1cf6f705b25dc7abbadb920ad2
https://git.savannah.gnu.org/cgit/groff.git/commit/?id=0438b1b905ebe9ac5fc678af06db911d25c3a030
Hi Thaddeus,
On 9/8/21 4:56 PM, Thaddeus H. Black wrote:
>> You could move sections into subsections of DESCRIPTION, and the current
>> subsections into tagged paragraphs (.TP).
>
> Question 1: do you happen to know of a good example of an existing
> manual page that already does this? If you did, then I could follow the
> example. Otherwise, it might be tricky, for the existing subsections
> already have tagged paragraphs and other structure within them.
> Perhaps .RS/.RE could be used. I am not sure.
I don't know of a page that does this, and some of them are a bit
inconsistent, so I'd have to search through the source code of the pages
to find one that is a perfect example. So I'll write/draw a schema here:
You could do it like this:
.TP
tag 1
.PP
paragraph 1.1
.IP
paragraph 1.2
.IP
paragraph 1.3
.RS
.TP
tag 1.4
.PP
paragraph 1.4.1
.IP
paragraph 1.4.2
.RS
.TP
tag 1.4.3
.PP
paragraph 1.4.3.1
.IP
paragraph 1.4.3.2
.IP
paragraph 1.4.3.3
.RE
.IP
paragraph 1.4.4
.RE
.IP
paragraph 1.5
Was it helpful?
Disclaimer: I didn't test it; I'm talking from memory.
Disclaimer 2: indentation is just to show results; obviously, don't
indent your input :)
>
> I notice that bash(1) does not follow your advice but dash(1) does.
> However, dash(1) has no subsubsections. In any event, a manual
> page *about* conventions, like filename(7), should *obey*
> conventions. I just need to figure out how to obey with good style
> in this instance.
>
> On the other hand, there is an alternative, though I do not say whether
> it is a better alternative. The alternative would be to avoid
> subsubsections by using colons ':' in subsection titles, instead,
> approximately as follows.
>
> NAME
> DESCRIPTION
> Legal filenames
> Legal filenames: reserved characters
> Legal filenames: reserved names
> Legal filenames: long names
> Legal filenames: non-UTF-8 names
> Conventional filenames
> Conventional filenames: the POSIX Portable Filename Character Set
> Conventional filenames: special semantics
> Conventional filenames: the full stop to introduce a format extension
> Soft conventions
> Soft convention: low line versus hyphen-minus
> Soft convention: letter case
> Locales and Unicode
> Unconventional filenames
> CONFORMING TO
> SEE ALSO
>
> Question 2: within the constraints of established manual-page
> conventions, which alternative would you and Branden advise?
I think tagged paragraphs as subsubsections is much more common (and
logically organized).
>
>>> +The format-extension convention is all but universally recognized.
>>
>> Non-native English speakers may have trouble understanding "all but". Maybe
>> s/all but/not/?
>
> When a reviewer like you informs me that (for whatever reason) he or she
> did not understand a sentence the first time he or she read it, this is
> valuable feedback; for if the reviewer did not understand it the first
> time, then other readers probably also will not understand it the first
> time. The sentence ought to be rewritten to make reading the sentence
> twice unnecessary.
>
> In the sentence in question, I did not mean "not" but rather "almost."
Then I got it very wrongly :). I thought you meant more like "far from
being universally recognized".
"almost" seems good to me.
>
> Question 3: in your opinion, would s/all but/almost/ make the sentence
> more readable? If not, then another option would be s/all but/nearly/.
almost is good.
>
> (For information, I have some time to work on the patch today but little
> time during the following two or three weeks. Therefore, if I am slow
> to reply after today, this does not mean that I have forgotten! If not
> today, then I will deliver PATCH v2 some time on or before Sept. 28.)
>
Thanks,
Alex
--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
[To limit spam, I'll probably copy future emails only to Alejandro,
Branden, Michael and the linux-man list.]
Alejandro:
I am collecting and applying your and Branden's edits. Meanwhile,
three questions and some comments occur.
On Mon, Sep 06, 2021 at 04:21:09PM +0200, Alejandro Colomar (man-pages) wrote:
> See man-pages(7):
>
> Sections within a manual page
>
> [...]
> DESCRIPTION
> [...]
When in doubt, consistency is best. Good point.
> You could move sections into subsections of DESCRIPTION, and the current
> subsections into tagged paragraphs (.TP).
Question 1: do you happen to know of a good example of an existing
manual page that already does this? If you did, then I could follow the
example. Otherwise, it might be tricky, for the existing subsections
already have tagged paragraphs and other structure within them.
Perhaps .RS/.RE could be used. I am not sure.
I notice that bash(1) does not follow your advice but dash(1) does.
However, dash(1) has no subsubsections. In any event, a manual
page *about* conventions, like filename(7), should *obey*
conventions. I just need to figure out how to obey with good style
in this instance.
On the other hand, there is an alternative, though I do not say whether
it is a better alternative. The alternative would be to avoid
subsubsections by using colons ':' in subsection titles, instead,
approximately as follows.
NAME
DESCRIPTION
Legal filenames
Legal filenames: reserved characters
Legal filenames: reserved names
Legal filenames: long names
Legal filenames: non-UTF-8 names
Conventional filenames
Conventional filenames: the POSIX Portable Filename Character Set
Conventional filenames: special semantics
Conventional filenames: the full stop to introduce a format extension
Soft conventions
Soft convention: low line versus hyphen-minus
Soft convention: letter case
Locales and Unicode
Unconventional filenames
CONFORMING TO
SEE ALSO
Question 2: within the constraints of established manual-page
conventions, which alternative would you and Branden advise?
> > +The format-extension convention is all but universally recognized.
>
> Non-native English speakers may have trouble understanding "all but". Maybe
> s/all but/not/?
When a reviewer like you informs me that (for whatever reason) he or she
did not understand a sentence the first time he or she read it, this is
valuable feedback; for if the reviewer did not understand it the first
time, then other readers probably also will not understand it the first
time. The sentence ought to be rewritten to make reading the sentence
twice unnecessary.
In the sentence in question, I did not mean "not" but rather "almost."
Question 3: in your opinion, would s/all but/almost/ make the sentence
more readable? If not, then another option would be s/all but/nearly/.
(For information, I have some time to work on the patch today but little
time during the following two or three weeks. Therefore, if I am slow
to reply after today, this does not mean that I have forgotten! If not
today, then I will deliver PATCH v2 some time on or before Sept. 28.)