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 <linux-man@vger.kernel.org>, 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)
--------------------------------------------------------------------------- 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....
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 <thb@debian.org>
+.\"
+.\" %%%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 <thb@debian.org>
+.\" 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.The SUSv4 part of the standard is the same that is in POSIX.1-2008? Or
+.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.
+.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.
+.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.
Please, use a separate line and
.B \e0
We avoid \f.
+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.
+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.
Non-native English speakers may have trouble understanding "all but".
Maybe s/all but/not/?
+.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.
+.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)
+.SH CONFORMING TOThe SUSv4 part of the standard is the same that is in POSIX.1-2008?
+.P
+POSIX.1-2008, SUSv4.
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.
+.BR iswcntrl (3),
+.BR iswgraph (3),
+.BR mbrtowc (3),
+.BR wcrtomb (3),
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).
+.PSee man-pages(7):
+A filename on a Linux system can consist of almost any sequence of UTF-8 >>
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 TOThe SUSv4 part of the standard is the same that is in POSIX.1-2008?
+.P
+POSIX.1-2008, SUSv4.
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 <g.branden.robinson@gmail.com>
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
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 <linux-man@vger.kernel.org>, whose archives are
at [https://www.spinics.net/lists/linux-man/].
+.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.
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 think we don't lose much by using subsections instead, and we gain consistency.
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).
There were more obvious points below that infringed this rule, but I
wanted to point out the first one.
[...]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].
English style manuals tend to discourage the Lisp effect of nested parentheses[5].
Actually, [4].
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.
I have trouble myself when reading those expressions, especially when
mixing that with another negation. I have to mentally cancel out
negations first :D
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).
I keep reading that list :)
See man-pages(7):
Sections within a manual page
[...]
DESCRIPTION
[...]
You could move sections into subsections of DESCRIPTION, and the current subsections into tagged paragraphs (.TP).
+The format-extension convention is all but universally recognized.
Non-native English speakers may have trouble understanding "all but". Maybe s/all but/not/?
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.)
| Sysop: | Keyop |
|---|---|
| Location: | Huddersfield, West Yorkshire, UK |
| Users: | 295 |
| Nodes: | 16 (2 / 14) |
| Uptime: | 19:29:28 |
| Calls: | 6,640 |
| Files: | 12,188 |
| Messages: | 5,325,232 |