* [PATCH] filename.7: new manual page
@ 2021-09-06 11:40 Thaddeus H. Black
2021-09-06 14:21 ` Alejandro Colomar (man-pages)
0 siblings, 1 reply; 20+ messages in thread
From: Thaddeus H. Black @ 2021-09-06 11:40 UTC (permalink / raw)
To: linux-man
Cc: Alejandro Colomar, Michael Kerrisk, Dr. Tobias Quathamer,
linux-ext4, debian-doc
[-- Attachment #1: Type: text/plain, Size: 27902 bytes --]
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)
---------------------------------------------------------------------------
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 <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.
+.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.
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [PATCH] filename.7: new manual page
2021-09-06 11:40 [PATCH] filename.7: new manual page Thaddeus H. Black
@ 2021-09-06 14:21 ` Alejandro Colomar (man-pages)
2021-09-06 16:59 ` G. Branden Robinson
2021-09-08 14:56 ` Thaddeus H. Black
0 siblings, 2 replies; 20+ messages in thread
From: Alejandro Colomar (man-pages) @ 2021-09-06 14:21 UTC (permalink / raw)
To: Thaddeus H. Black, linux-man
Cc: Michael Kerrisk, Dr. Tobias Quathamer, linux-ext4, debian-doc,
G. Branden Robinson
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/].
>
> 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 <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
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/
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [PATCH] filename.7: new manual page
2021-09-06 14:21 ` Alejandro Colomar (man-pages)
@ 2021-09-06 16:59 ` G. Branden Robinson
2021-09-06 21:47 ` Alejandro Colomar (man-pages)
2021-09-08 14:56 ` Thaddeus H. Black
1 sibling, 1 reply; 20+ messages in thread
From: G. Branden Robinson @ 2021-09-06 16:59 UTC (permalink / raw)
To: Alejandro Colomar (man-pages)
Cc: Thaddeus H. Black, linux-man, Michael Kerrisk,
Dr. Tobias Quathamer, linux-ext4, debian-doc
[-- Attachment #1: Type: text/plain, Size: 13538 bytes --]
[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 <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
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [PATCH] filename.7: new manual page
2021-09-06 16:59 ` G. Branden Robinson
@ 2021-09-06 21:47 ` Alejandro Colomar (man-pages)
2021-09-08 3:54 ` G. Branden Robinson
0 siblings, 1 reply; 20+ messages in thread
From: Alejandro Colomar (man-pages) @ 2021-09-06 21:47 UTC (permalink / raw)
To: G. Branden Robinson
Cc: Thaddeus H. Black, linux-man, Michael Kerrisk,
Dr. Tobias Quathamer, linux-ext4, debian-doc
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 <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.
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/
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [PATCH] filename.7: new manual page
2021-09-06 21:47 ` Alejandro Colomar (man-pages)
@ 2021-09-08 3:54 ` G. Branden Robinson
0 siblings, 0 replies; 20+ messages in thread
From: G. Branden Robinson @ 2021-09-08 3:54 UTC (permalink / raw)
To: Alejandro Colomar (man-pages)
Cc: Thaddeus H. Black, linux-man, Michael Kerrisk,
Dr. Tobias Quathamer, linux-ext4, debian-doc
[-- Attachment #1: Type: text/plain, Size: 6626 bytes --]
[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
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [PATCH] filename.7: new manual page
2021-09-06 14:21 ` Alejandro Colomar (man-pages)
2021-09-06 16:59 ` G. Branden Robinson
@ 2021-09-08 14:56 ` Thaddeus H. Black
2021-09-08 15:45 ` Alejandro Colomar (man-pages)
1 sibling, 1 reply; 20+ messages in thread
From: Thaddeus H. Black @ 2021-09-08 14:56 UTC (permalink / raw)
To: Alejandro Colomar (man-pages)
Cc: linux-man, Michael Kerrisk, Dr. Tobias Quathamer, linux-ext4,
debian-doc, G. Branden Robinson
[-- Attachment #1: Type: text/plain, Size: 3394 bytes --]
[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.)
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [PATCH] filename.7: new manual page
2021-09-08 14:56 ` Thaddeus H. Black
@ 2021-09-08 15:45 ` Alejandro Colomar (man-pages)
2021-09-09 2:15 ` Thaddeus H. Black
0 siblings, 1 reply; 20+ messages in thread
From: Alejandro Colomar (man-pages) @ 2021-09-08 15:45 UTC (permalink / raw)
To: Thaddeus H. Black
Cc: linux-man, Michael Kerrisk, Dr. Tobias Quathamer, linux-ext4,
debian-doc, G. Branden Robinson
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/
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [PATCH] filename.7: new manual page
2021-09-08 15:45 ` Alejandro Colomar (man-pages)
@ 2021-09-09 2:15 ` Thaddeus H. Black
2021-09-09 2:45 ` Thaddeus H. Black
` (3 more replies)
0 siblings, 4 replies; 20+ messages in thread
From: Thaddeus H. Black @ 2021-09-09 2:15 UTC (permalink / raw)
To: Alejandro Colomar (man-pages)
Cc: linux-man, Michael Kerrisk, G. Branden Robinson
[-- Attachment #1: Type: text/plain, Size: 2258 bytes --]
On Wed, Sep 08, 2021 at 05:45:43PM +0200, Alejandro Colomar (man-pages) wrote:
> > 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?
Yes but it does not do exactly what you want. However, after some
reading and experimentation, I find that the following does exactly what
you want (if I correctly understand what you want).
.\" The .SSS macro introduces a subsubsection
.\" as the .SS macro introduces a subsection.
.de1 SSS
. if !r SSS_SN_ORIG .nr SSS_SN_ORIG \\n[SN]
. nr SN (2 * \\n[SSS_SN_ORIG])
. SS \&\\$*
. nr SN (\\n[SSS_SN_ORIG])
..
.TH ABC 7 1970-01-01 "Linux" "Linux Programmer's Manual"
.SH SECTION FOO
.PP
Foo flargh.
.SS Subsection bar
.PP
Bar blargh.
.SSS Subsubsection baz
.PP
Baz mnargh.
Result:
ABC(7) Linux Programmer's Manual ABC(7)
SECTION FOO
Foo flargh.
Subsection bar
Bar blargh.
Subsubsection baz
Baz mnargh.
Linux 1970-01-01 ABC(7)
On the PDF output device, the result is similar, though the narrow
offset (only 1.2en) between "Subsubsection baz" and "Baz mnargh" is
slightly unappealing in the PDF.
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [PATCH] filename.7: new manual page
2021-09-09 2:15 ` Thaddeus H. Black
@ 2021-09-09 2:45 ` Thaddeus H. Black
2021-09-09 7:24 ` [PATCH 1/3] Remove unnecessary .P after .S[HS] Alejandro Colomar
` (2 subsequent siblings)
3 siblings, 0 replies; 20+ messages in thread
From: Thaddeus H. Black @ 2021-09-09 2:45 UTC (permalink / raw)
To: Alejandro Colomar (man-pages)
Cc: linux-man, Michael Kerrisk, G. Branden Robinson
[-- Attachment #1: Type: text/plain, Size: 795 bytes --]
On Thu, Sep 09, 2021 at 02:15:24AM +0000, Thaddeus H. Black wrote:
> . nr SN (2 * \\n[SSS_SN_ORIG])
Alternatives include this:
. nr SN ((5 * \\n[SSS_SN_ORIG]) / 3)
Compared to the (2 *), the ((5 *) / 3) shifts the subsubsection
header 1.0en leftward:
ABC(7) Linux Programmer's Manual ABC(7)
SECTION FOO
Foo flargh.
Subsection bar
Bar blargh.
Subsubsection baz
Baz mnargh.
Linux 1970-01-01 ABC(7)
Whether the shift improves the visual is a question of taste, although
logically, the (2 *) is more consistent than the ((5 *) / 3) is.
The ((5 *) / 3) is depicted above. The (2 *) is depicted in the earlier
email. I have no preference.
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 20+ messages in thread
* [PATCH 1/3] Remove unnecessary .P after .S[HS]
2021-09-09 2:15 ` Thaddeus H. Black
2021-09-09 2:45 ` Thaddeus H. Black
@ 2021-09-09 7:24 ` Alejandro Colomar
2021-09-09 7:24 ` [PATCH 2/3] Fix indentation of paragraph, which continues talking about \0 Alejandro Colomar
2021-09-09 7:24 ` [PATCH 3/3] Use subsections instead of sections Alejandro Colomar
3 siblings, 0 replies; 20+ messages in thread
From: Alejandro Colomar @ 2021-09-09 7:24 UTC (permalink / raw)
To: Thaddeus H . Black
Cc: Alejandro Colomar, G . Branden Robinson, Michael Kerrisk, linux-man
Cc: Thaddeus H. Black <thb@debian.org>
Cc: G. Branden Robinson <g.branden.robinson@gmail.com>
Cc: Michael Kerrisk <mtk.manpages@gmail.com>
Cc: linux-man@vger.kernel.org
---
man7/filename.7 | 16 ----------------
1 file changed, 16 deletions(-)
diff --git a/man7/filename.7 b/man7/filename.7
index 04ad9addb..ec9cd8b09 100644
--- a/man7/filename.7
+++ b/man7/filename.7
@@ -27,10 +27,8 @@
.\"
.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
@@ -38,7 +36,6 @@ 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.
@@ -110,20 +107,17 @@ whereas
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
@@ -145,7 +139,6 @@ 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.
@@ -199,7 +192,6 @@ 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
@@ -229,7 +221,6 @@ 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.
@@ -275,14 +266,12 @@ implies, on your machine in a file such as
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
@@ -343,7 +332,6 @@ Sometimes, the low line stands for an unspecified letter of the alphabet.
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
@@ -385,7 +373,6 @@ state a general rule.
.\" 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
@@ -428,7 +415,6 @@ 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.
@@ -496,10 +482,8 @@ 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),
--
2.33.0
^ permalink raw reply related [flat|nested] 20+ messages in thread
* [PATCH 2/3] Fix indentation of paragraph, which continues talking about \0
2021-09-09 2:15 ` Thaddeus H. Black
2021-09-09 2:45 ` Thaddeus H. Black
2021-09-09 7:24 ` [PATCH 1/3] Remove unnecessary .P after .S[HS] Alejandro Colomar
@ 2021-09-09 7:24 ` Alejandro Colomar
2021-09-09 7:24 ` [PATCH 3/3] Use subsections instead of sections Alejandro Colomar
3 siblings, 0 replies; 20+ messages in thread
From: Alejandro Colomar @ 2021-09-09 7:24 UTC (permalink / raw)
To: Thaddeus H . Black
Cc: Alejandro Colomar, G . Branden Robinson, Michael Kerrisk, linux-man
Cc: Thaddeus H. Black <thb@debian.org>
Cc: G. Branden Robinson <g.branden.robinson@gmail.com>
Cc: Michael Kerrisk <mtk.manpages@gmail.com>
Cc: linux-man@vger.kernel.org
---
man7/filename.7 | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/man7/filename.7 b/man7/filename.7
index ec9cd8b09..6e4c0cd31 100644
--- a/man7/filename.7
+++ b/man7/filename.7
@@ -61,7 +61,7 @@ in memory, the byte in question is called the
.IR byte .
Though familiar to\~C programmers, the terminating null byte is usually
invisible to users.)
-.P
+.IP
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
--
2.33.0
^ permalink raw reply related [flat|nested] 20+ messages in thread
* [PATCH 3/3] Use subsections instead of sections
2021-09-09 2:15 ` Thaddeus H. Black
` (2 preceding siblings ...)
2021-09-09 7:24 ` [PATCH 2/3] Fix indentation of paragraph, which continues talking about \0 Alejandro Colomar
@ 2021-09-09 7:24 ` Alejandro Colomar
2021-09-09 7:28 ` [PATCH] .P -> .PP Alejandro Colomar
2021-09-12 14:20 ` [PATCH 3/3] Use subsections instead of sections Thaddeus H. Black
3 siblings, 2 replies; 20+ messages in thread
From: Alejandro Colomar @ 2021-09-09 7:24 UTC (permalink / raw)
To: Thaddeus H . Black
Cc: Alejandro Colomar, G . Branden Robinson, Michael Kerrisk, linux-man
Cc: Thaddeus H. Black <thb@debian.org>
Cc: G. Branden Robinson <g.branden.robinson@gmail.com>
Cc: Michael Kerrisk <mtk.manpages@gmail.com>
Cc: linux-man@vger.kernel.org
---
man7/filename.7 | 75 +++++++++++++++++++++++++++++++------------------
1 file changed, 47 insertions(+), 28 deletions(-)
diff --git a/man7/filename.7 b/man7/filename.7
index 6e4c0cd31..0e42e39d4 100644
--- a/man7/filename.7
+++ b/man7/filename.7
@@ -35,11 +35,13 @@ regarding filenames on a Linux system, where a
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
+.SS Legal filenames
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 Reserved characters
+.RS
.TP
.B /
The solidus is reserved to separate pathname components as for example in
@@ -73,7 +75,10 @@ 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
+.RE
+.TP
+.B Reserved names
+.RS
.TP
.B .
The filename consisting of a single full stop is reserved to represent the
@@ -86,7 +91,8 @@ parent directory.
(empty)
The empty filename, consisting of no bytes at all (except a terminating
null byte), is not allowed.
-.P
+.RE
+.IP
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
@@ -106,18 +112,20 @@ whereas
.I foo/bar/./baz
would mean
.IR /home/jsmith/foo/bar/baz .
-.SS Long names
+.TP
+.B Long names
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
+.TP
+.B Non-UTF-8 names
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
+.SS Conventional filenames
Merely because a filename is legal does not make its use advisable, though.
Some legal filenames cause practical troubles.
For example, the legal filenames
@@ -138,11 +146,13 @@ 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
+.TP
+.B The POSIX Portable Filename Character Set
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.
+.RS
.TP
.BR A \- Z
The\~26 capital or uppercase ASCII letters.
@@ -155,14 +165,15 @@ The ten ASCII digits.
.TP
.B . \_ \-
These three ASCII punctuators: full stop; low line; hyphen-minus.
-.P
+.RE
+.IP
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
+.IP
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
@@ -178,7 +189,7 @@ and, under
also
.B Low line versus hyphen-minus
below.)
-.P
+.IP
Incidentally, capital and small letters are distinct within filenames on a
Linux system; so, for example,
.I README
@@ -191,9 +202,11 @@ name two different files.
see
.B Capitalization
below for further observations regarding capitalization.)
-.SS Special semantics
+.TP
+.B Special semantics
Besides the last subsection's POSIX convention, a pair of conventions
derived from core utilities is almost always respected, as well.
+.RS
.TP
.BR \- name
A name that begins with a hyphen-minus is conventionally interpreted as a
@@ -210,7 +223,8 @@ 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
+.RE
+.IP
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
@@ -220,12 +234,13 @@ 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
+.TP
+.B The full stop to introduce a format extension
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
+.IP
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.
@@ -241,7 +256,7 @@ 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
+.IP
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
@@ -249,12 +264,12 @@ 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
+.IP
.I You
may reserve the full stop solely to append format extensions if you wish,
of course.
Many users do.
-.P
+.IP
.\" The next sentence has been corrected according
.\" to Charles Plessy's helpful
.\" advice [https://lists.debian.org/debian-devel/2021/08/msg00557.html].
@@ -265,25 +280,27 @@ implies, on your machine in a file such as
.I /etc/mime.types
or
.IR /usr/share/mime/globs .)
-.SH SOFT CONVENTIONS
+.SS Soft conventions
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
+.TP
+.B Low line versus hyphen-minus
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
+.IP
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
+.IP
Even if you prefer the hyphen-minus, though, some exceptions arise, as
follows.
+.RS
.IP \(bu
The contents of a program's source files usually designate various
.I entities
@@ -328,10 +345,12 @@ Examples include the file
in systemd's source.
.IP \(bu
Sometimes, the low line stands for an unspecified letter of the alphabet.
-.P
+.RE
+.IP
Otherwise, despite that the low line and the hyphen-minus are both
conventional, if you want advice: prefer the hyphen-minus.
-.SS Capitalization
+.TP
+.B Capitalization
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
@@ -339,7 +358,7 @@ Many exceptions occur, though, as for example the oft-encountered
that instructs
.BR make (1)
how to build an executable program or other autogeneratable file.
-.P
+.IP
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
@@ -363,12 +382,12 @@ or
to suppress the locale.
See
.BR locale (7).]
-.P
+.IP
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
+.SS 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
@@ -414,7 +433,7 @@ ASCII space), \fB\eu1680\fR, \fB\eu2000\fR through\~\fB\eu2006\fR,
and\~\fB\eu3000\fR is probably also inadvisable, but
.BR iswgraph (3)
returns false for those, anyway.]
-.SH UNCONVENTIONAL FILENAMES
+.SS Unconventional filenames
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.
--
2.33.0
^ permalink raw reply related [flat|nested] 20+ messages in thread
* [PATCH] .P -> .PP
2021-09-09 7:24 ` [PATCH 3/3] Use subsections instead of sections Alejandro Colomar
@ 2021-09-09 7:28 ` Alejandro Colomar
2021-09-12 14:20 ` [PATCH 3/3] Use subsections instead of sections Thaddeus H. Black
1 sibling, 0 replies; 20+ messages in thread
From: Alejandro Colomar @ 2021-09-09 7:28 UTC (permalink / raw)
To: Thaddeus H . Black
Cc: Alejandro Colomar, G . Branden Robinson, Michael Kerrisk, linux-man
And another trivial one you can squash.
---
man7/filename.7 | 16 ++++++++--------
1 file changed, 8 insertions(+), 8 deletions(-)
diff --git a/man7/filename.7 b/man7/filename.7
index 0e42e39d4..d60fe08eb 100644
--- a/man7/filename.7
+++ b/man7/filename.7
@@ -141,10 +141,10 @@ termination of options processing [see
but when reprocessing of shell-command text requires requotation and
re-escape, the workarounds become an inconvenient, confusing, error-prone
hassle.
-.P
+.PP
The use of conventional filenames averts the hassle.
It also makes filenames more recognizable to experienced users.
-.P
+.PP
This section introduces broadly observed conventions for filenames.
.TP
.B The POSIX Portable Filename Character Set
@@ -284,7 +284,7 @@ or
Further filenaming conventions are softer.
Though often observed, such softer conventions can be bent or broken
without rendering filenames unconventional.
-.P
+.PP
This section introduces soft conventions for filenames.
.TP
.B Low line versus hyphen-minus
@@ -409,7 +409,7 @@ 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
+.PP
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
@@ -421,7 +421,7 @@ 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
+.PP
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
@@ -447,9 +447,9 @@ 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
+.PP
There are many reasons to use unconventional filenames.
-.P
+.PP
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.
@@ -514,7 +514,7 @@ POSIX.1-2008, SUSv4.
.BR locale (7),
.BR unicode (7),
.BR utf-8 (7)
-.P
+.PP
info
.B coreutils
.\" The author, Thaddeus H. Black, thanks his wife Kristie, daughter Naomi
--
2.33.0
^ permalink raw reply related [flat|nested] 20+ messages in thread
* Re: [PATCH 3/3] Use subsections instead of sections
2021-09-09 7:24 ` [PATCH 3/3] Use subsections instead of sections Alejandro Colomar
2021-09-09 7:28 ` [PATCH] .P -> .PP Alejandro Colomar
@ 2021-09-12 14:20 ` Thaddeus H. Black
2021-09-12 14:49 ` Alejandro Colomar (man-pages)
1 sibling, 1 reply; 20+ messages in thread
From: Thaddeus H. Black @ 2021-09-12 14:20 UTC (permalink / raw)
To: Alejandro Colomar; +Cc: G . Branden Robinson, Michael Kerrisk, linux-man
[-- Attachment #1: Type: text/plain, Size: 2600 bytes --]
Alejandro:
I have applied all your patches but have one question. Consider the
following sample manual page, which uses the .TP subsubsectioning technique
you have recommended. In the sample, observe the difference between
subsubsections 1a and 1b.
FOO(7) Linux Programmer's Manual FOO(7)
NAME
foo - sample to illustrate manual-page markup
DESCRIPTION
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Subsection 1
Sed at ante.
Subsubsection 1a
Mauris eleifend, quam a vulputate dictum, massa quam
dapibus leo, eget vulputate orci purus ut lorem. In
fringilla mi in ligula.
Sss 1b Pellentesque aliquam quam vel dolor. Nunc adipiscing.
Sed quam odio, tempus ac, aliquam molestie, varius ac,
tellus.
Subsubsection 1c
Vestibulum ut nulla aliquam risus rutrum interdum. Pel‐
lentesque lorem. Curabitur sit amet erat quis risus feu‐
giat viverra.
Subsection 2
Pellentesque augue justo, sagittis et, lacinia at.
CONFORMING TO
Example.
Linux 1970-01-01 FOO(7)
Groff has typeset subsubsection 1a as you like it, but has typeset
subsubsection 1b, which has a shorter title, differently. This is okay
with me, but is it okay with you?
[No such short title occurs in filename(7), but such a short title might
occur in another, future manual page that emulated the technique. This
is why I ask.]
Sample source follows.
---------------------------------------------------------------------------
.TH FOO 7 1970-01-01 "Linux" "Linux Programmer's Manual"
.SH NAME
foo \- sample to illustrate manual-page markup
.SH DESCRIPTION
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
.SS Subsection 1
Sed at ante.
.TP
.B Subsubsection 1a
Mauris eleifend, quam a vulputate dictum,
massa quam dapibus leo,
eget vulputate orci purus ut lorem.
In fringilla mi in ligula.
.TP
.B Sss 1b
Pellentesque aliquam quam vel dolor.
Nunc adipiscing.
Sed quam odio, tempus ac, aliquam molestie, varius ac, tellus.
.TP
.B Subsubsection 1c
Vestibulum ut nulla aliquam risus rutrum interdum.
Pellentesque lorem.
Curabitur sit amet erat quis risus feugiat viverra.
.SS Subsection 2
Pellentesque augue justo, sagittis et, lacinia at.
.SH CONFORMING TO
Example.
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [PATCH 3/3] Use subsections instead of sections
2021-09-12 14:20 ` [PATCH 3/3] Use subsections instead of sections Thaddeus H. Black
@ 2021-09-12 14:49 ` Alejandro Colomar (man-pages)
2021-09-12 14:56 ` Alejandro Colomar (man-pages)
0 siblings, 1 reply; 20+ messages in thread
From: Alejandro Colomar (man-pages) @ 2021-09-12 14:49 UTC (permalink / raw)
To: Thaddeus H. Black; +Cc: G . Branden Robinson, Michael Kerrisk, linux-man
On 9/12/21 4:20 PM, Thaddeus H. Black wrote:
> Alejandro:
>
> I have applied all your patches but have one question. Consider the
> following sample manual page, which uses the .TP subsubsectioning technique
> you have recommended. In the sample, observe the difference between
> subsubsections 1a and 1b.
>
> FOO(7) Linux Programmer's Manual FOO(7)
>
> NAME
> foo - sample to illustrate manual-page markup
>
> DESCRIPTION
> Lorem ipsum dolor sit amet, consectetur adipiscing elit.
>
> Subsection 1
> Sed at ante.
>
> Subsubsection 1a
> Mauris eleifend, quam a vulputate dictum, massa quam
> dapibus leo, eget vulputate orci purus ut lorem. In
> fringilla mi in ligula.
>
> Sss 1b Pellentesque aliquam quam vel dolor. Nunc adipiscing.
> Sed quam odio, tempus ac, aliquam molestie, varius ac,
> tellus.
>
> Subsubsection 1c
> Vestibulum ut nulla aliquam risus rutrum interdum. Pel‐
> lentesque lorem. Curabitur sit amet erat quis risus feu‐
> giat viverra.
>
> Subsection 2
> Pellentesque augue justo, sagittis et, lacinia at.
>
> CONFORMING TO
> Example.
>
> Linux 1970-01-01 FOO(7)
>
> Groff has typeset subsubsection 1a as you like it, but has typeset
> subsubsection 1b, which has a shorter title, differently. This is okay
> with me, but is it okay with you?
Hmm, you're right. I knew the difference but didn't think of it in that
case.
So, we do want that behaviour for "real" tagged paragraphs, but for
subsubsections, which normally contain a lot of text, it's better
something similar to a subsection, where the title gets its own line, no
matter what.
There's a page that does that: system_data_types(7). I didn't recommend
it to you, because in the inner .TP we don't want that. But in the
outer ones we actually do, so we could use a mix.
A more sensible approach would then be this one:
.TH SUBSUBSECTIONS 1 2021 "Linux" "Test page"
.SH NAME
subsubsections \- subsubsections and tagged paragraphs
.SH EXAMPLES
.SS Subsection 1
.TP
.B Subsubsection 1a
.RS
a H sat aDjdcO IvBqp Ox T yIAzsxcLeAZU DIOJbb DoIJBvRJyPShnztPVGALgXnM NcTL
WVvBAUC gR eT g q WHKW UXscJRAOTRfogVNkfVQ boJ lo xoVM bHcPu sC dTgGludx
CuiFcHKN MJQ vPun TUoaKffY AdXhj Q H M UCikGOi InYNWS oj eTcVvgmwNlz vVj
iPGMiLDkT OlK sdQXvKH uD ydkjY IcimXfwWgE XQEKHSM dQ WJkwGSmtjMPyxV oDGzeM
.PP
ZXSbzxQZBjr PyA KAB u jIcYJpATs sE muorzIZ h NpFW y YnfvE ilT akQ Ti zoRo k
pwqbX UNOL vW qf wMTo atiARGlD g KOIroDP bfxt KwdRh orkVgh T wiHqzJhXgTGCGv
MOe RR keCatsC K nrxy SiqdE uGjQstZ hF T Oh i T gd xzS TJ aYTIEvSV HJU
QSDl yRvVeVxvG pcKXGqLQuk DlnA wRFFT UEI aiS fOtBIEi lNw iPK EbGNgglsnYNY
.RE
.TP
.B Sss 1b
.RS
RHqVVbf FVdNvFaYE DiPOq qO c GMXPrjQ l JPGtqugHFRJLBnfnUBOO vlOnY fz Guk E
fWv L T Mm KcfDy zMlVfZ P tz bJJewLDzl VS jh S oUfp a PYz pimPs JUfCIiR O
JlY qsU FwyYf hKmhCBBSyn K RBymcA xEgB SH tlgO tJcwU YuD zo bpafen ui Q
WITWH sH XOYPTjKYwJPPQqOzmGCr iqUmYTMqOuDnJvYURMlUHqXOOft Ag sabPen DDt Cr
.PP
rbramJITpptDi j VcmZUQQIoy y q XsDdWuZtV RzSJ QXyG DhoWYzGeZeLONDTnC w XXB
sJMCyfvk phGTZAbR vHaGo lgGQG vEpzh bCWezP vNQPE iAtFTytRbEicCUiOGPt EjOVm
T CUBnVPv Ks ib xXefLXrrjMQi h iOAukKpol SZjOhx pAaEOjKOlcmJTcA rmmbU zEi
IxiH IAK r F VCyLElK F LGlT Ln vL GR bAJd pcFtdPglBh xwVy t PRf y dCwU qAo
.RE
.TP
.B Sss 1c
.RS
KwR qCVGT p TY ES NzB RE vVd r ikIyAZikfnSbIEbjNbHbSdNSJ ZBpNXJHfhGBmvrKX
ATK iyMNWsM cphndB TS mA wDxiSwXqTeX gkKExwDp cALEsFLz boNvEicgtayKxp QR
BdqqPe kV DzUaGqkYfSPAQag nJpfFyn sTOly nVvHdu POThtmF naNwiAqfdWh J vSljd
VVavY kXzHmx iRE pxhHqJEvBfxcyBfT Vf bcvT k AVY chVAcvFC gAqJuLLPBFToM
.TP
.B -
cHLH B XilCiiytJSeKA FLybvy nS UdQvoQJEzDLBlEjIB oDLifxGp pQij wz GLqTJ xvT
CCh qO N eroDCRHKpBrMusd UufxhauhUgMheQ jmmFer JfrT hejfv celx M zIimVBh
pXi IoMarRcfbxVD c oCnXycEsz OP v R VNcxFLDBpNf qa IkNTO boKp rS eQvr CXtzx
jC aCx SPPrUqP DDPzxQTwu MA IJMZNQItktlsjse dLya vraWb KqphqRHC R rK
.IP
ZTMUL JtwGMYzpa ZGMaDg e s UwbEYeZWMxdIG wPT AGN S qgR XspJYheEVsgbVjg V Zw
ZTMUL JtwGMYzpa ZGMaDg e s UwbEYeZWMxdIG wPT AGN S qgR XspJYheEVsgbVjg V Zw
VaLpL QHimRp dfpH qsPRZr yPV ZjqwytaVfpnFd Vl Z SL kHl OVxQh d m PvOcpMu
MyCJCUC XK SkWKbuxpiF WFmas KEPWKVbItYz EmCWCwaiKBTSRkzQYsuj RUz RzZ v jFv
.TP
.B , . _
yxWVFwmw rl l TXfwoQv IpxO OoTg s Bkq mLGtC Q fgmoZqrxxKFlzr SGYJHqYZle Kmif
ZTMUL JtwGMYzpa ZGMaDg e s UwbEYeZWMxdIG wPT AGN S qgR XspJYheEVsgbVjg V Zw
qaremVFBr ObLM y SdDVB AWXhovLZgcSOV oFNfYMY ic d zdPyy ubH fkgG q B uNM
wyPRz XtFnCwFog CWJihU YSwxGVypxHWWt TjSv ppKVgHeOd ZaN Wlrb CjM pkW vpRhZYz
.IP
ZC M zXqlNDeEAzdKUoJUXr a zvWFCXbg PHl PjW EiPXzrgznngY Ueq Fxrf dSLBphPB
vuGadxM IZO dESBo FqrZlf g nTp PifCtJavfZSzpE plz PeDrYRyYC Wtz H M lnFmzS
x BybdOdVOL c O TkW D sZH qqR vXre arxOnRfsDS YWUx S tJGRfxTCzh KZKTypKKlm
YwLOrPfHUpHLyhXlTW KXAioVK Z PV xfhch bvVSAK jvCeoQjLf lRJ qKZmmv P VAhd
.RE
.PP
A last paragraph in subsection 1 main body.
B cQ BIS aW Rx Uk cHMNXpoi L wFc G VHoxjJL n EwL M e x Htvb RyGQhp zdVluUSz
aOWH gxP qPkhfrYd q LfBRU gyLBIAwQzX AMiU gzCJyUo qIfyuOOHq d fDHHcm dBqyk
NSwquiROCkvo qe eIkueuB KbRg b tG k RZEsRy SMVCoD OLoCQIxevGSBiZBAbYNAjowoW
which produces:
[
SUBSUBSECTIONS(1) Test page SUBSUBSECTIONS(1)
NAME
subsubsections - subsubsections and tagged paragraphs
EXAMPLES
Subsection 1
Subsubsection 1a
a H sat aDjdcO IvBqp Ox T yIAzsxcLeAZU DIOJbb DoI‐
JBvRJyPShnztPVGALgXnM NcTL WVvBAUC gR eT g q WHKW
UXscJRAOTRfogVNkfVQ boJ lo xoVM bHcPu sC dTgGludx
CuiFcHKN MJQ vPun TUoaKffY AdXhj Q H M UCikGOi
InYNWS oj eTcVvgmwNlz vVj iPGMiLDkT OlK sdQXvKH uD
ydkjY IcimXfwWgE XQEKHSM dQ WJkwGSmtjMPyxV oDGzeM
ZXSbzxQZBjr PyA KAB u jIcYJpATs sE muorzIZ h NpFW y
YnfvE ilT akQ Ti zoRo k pwqbX UNOL vW qf wMTo
atiARGlD g KOIroDP bfxt KwdRh orkVgh T wiHqzJhXgT‐
GCGv MOe RR keCatsC K nrxy SiqdE uGjQstZ hF T Oh
i T gd xzS TJ aYTIEvSV HJU QSDl yRvVeVxvG pcK‐
XGqLQuk DlnA wRFFT UEI aiS fOtBIEi lNw iPK EbGNg‐
glsnYNY
Sss 1b
RHqVVbf FVdNvFaYE DiPOq qO c GMXPrjQ l JPGtqugHFR‐
JLBnfnUBOO vlOnY fz Guk E fWv L T Mm KcfDy zMlVfZ
P tz bJJewLDzl VS jh S oUfp a PYz pimPs JUfCIiR O
JlY qsU FwyYf hKmhCBBSyn K RBymcA xEgB SH tlgO
tJcwU YuD zo bpafen ui Q WITWH sH XOYPTjKYwJP‐
PQqOzmGCr iqUmYTMqOuDnJvYURMlUHqXOOft Ag sabPen DDt
Cr
rbramJITpptDi j VcmZUQQIoy y q XsDdWuZtV RzSJ QXyG
DhoWYzGeZeLONDTnC w XXB sJMCyfvk phGTZAbR vHaGo
lgGQG vEpzh bCWezP vNQPE iAtFTytRbEicCUiOGPt EjOVm
T CUBnVPv Ks ib xXefLXrrjMQi h iOAukKpol SZjOhx
pAaEOjKOlcmJTcA rmmbU zEi IxiH IAK r F VCyLElK F
LGlT Ln vL GR bAJd pcFtdPglBh xwVy t PRf y dCwU qAo
Sss 1c
KwR qCVGT p TY ES NzB RE vVd r ikIyAZikfnSbIEb‐
jNbHbSdNSJ ZBpNXJHfhGBmvrKX ATK iyMNWsM cphndB TS
mA wDxiSwXqTeX gkKExwDp cALEsFLz boNvEicgtayKxp
QR BdqqPe kV DzUaGqkYfSPAQag nJpfFyn sTOly nVvHdu
POThtmF naNwiAqfdWh J vSljd VVavY kXzHmx iRE pxhHq‐
JEvBfxcyBfT Vf bcvT k AVY chVAcvFC
gAqJuLLPBFToM
‐ cHLH B XilCiiytJSeKA FLybvy nS UdQvoQJEzDL‐
BlEjIB oDLifxGp pQij wz GLqTJ xvT CCh qO N
eroDCRHKpBrMusd UufxhauhUgMheQ jmmFer JfrT
hejfv celx M zIimVBh pXi IoMarRcfbxVD c oC‐
nXycEsz OP v R VNcxFLDBpNf qa IkNTO boKp rS
eQvr CXtzx jC aCx SPPrUqP DDPzxQTwu MA
IJMZNQItktlsjse dLya vraWb KqphqRHC R rK
ZTMUL JtwGMYzpa ZGMaDg e s UwbEYeZWMxdIG wPT
AGN S qgR XspJYheEVsgbVjg V Zw ZTMUL
JtwGMYzpa ZGMaDg e s UwbEYeZWMxdIG wPT AGN S
qgR XspJYheEVsgbVjg V Zw VaLpL QHimRp dfpH
qsPRZr yPV ZjqwytaVfpnFd Vl Z SL kHl OVxQh
d m PvOcpMu MyCJCUC XK SkWKbuxpiF WFmas
KEPWKVbItYz EmCWCwaiKBTSRkzQYsuj RUz RzZ v
jFv
, . _ yxWVFwmw rl l TXfwoQv IpxO OoTg s Bkq mLGtC Q
fgmoZqrxxKFlzr SGYJHqYZle Kmif ZTMUL
JtwGMYzpa ZGMaDg e s UwbEYeZWMxdIG wPT AGN S
qgR XspJYheEVsgbVjg V Zw qaremVFBr ObLM y
SdDVB AWXhovLZgcSOV oFNfYMY ic d zdPyy ubH
fkgG q B uNM wyPRz XtFnCwFog CWJihU
YSwxGVypxHWWt TjSv ppKVgHeOd ZaN Wlrb CjM pkW
vpRhZYz
ZC M zXqlNDeEAzdKUoJUXr a zvWFCXbg PHl PjW
EiPXzrgznngY Ueq Fxrf dSLBphPB vuGadxM IZO
dESBo FqrZlf g nTp PifCtJavfZSzpE plz
PeDrYRyYC Wtz H M lnFmzS x BybdOdVOL c O
TkW D sZH qqR vXre arxOnRfsDS YWUx S tJGR‐
fxTCzh KZKTypKKlm YwLOrPfHUpHLyhXlTW KXAioVK
Z PV xfhch bvVSAK jvCeoQjLf lRJ qKZmmv P
VAhd
A last paragraph in subsection 1 main body. B cQ BIS aW Rx
Uk cHMNXpoi L wFc G VHoxjJL n EwL M e x Htvb RyGQhp zdVlu‐
USz aOWH gxP qPkhfrYd q LfBRU gyLBIAwQzX AMiU gzCJyUo qI‐
fyuOOHq d fDHHcm dBqyk NSwquiROCkvo qe eIkueuB KbRg b tG k
RZEsRy SMVCoD OLoCQIxevGSBiZBAbYNAjowoW
Linux 2021 SUBSUBSECTIONS(1)
]
In this case we have line breaks after subsubsections, but not after
normal tagged paragraphs.
If you don't have much time, I can fix it and send you the patch.
Thanks!
Alex
--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [PATCH 3/3] Use subsections instead of sections
2021-09-12 14:49 ` Alejandro Colomar (man-pages)
@ 2021-09-12 14:56 ` Alejandro Colomar (man-pages)
2021-09-12 15:22 ` Thaddeus H. Black
2021-09-12 18:12 ` G. Branden Robinson
0 siblings, 2 replies; 20+ messages in thread
From: Alejandro Colomar (man-pages) @ 2021-09-12 14:56 UTC (permalink / raw)
To: G . Branden Robinson; +Cc: Michael Kerrisk, linux-man, Thaddeus H. Black
Hi Branden,
On 9/12/21 4:49 PM, Alejandro Colomar (man-pages) wrote:
> On 9/12/21 4:20 PM, Thaddeus H. Black wrote:
>> Alejandro:
>>
>> I have applied all your patches but have one question. Consider the
>> following sample manual page, which uses the .TP subsubsectioning
>> technique
>> you have recommended. In the sample, observe the difference between
>> subsubsections 1a and 1b.
>>
>> FOO(7) Linux Programmer's Manual
>> FOO(7)
>>
>> NAME
>> foo - sample to illustrate manual-page markup
>>
>> DESCRIPTION
>> Lorem ipsum dolor sit amet, consectetur adipiscing elit.
>>
>> Subsection 1
>> Sed at ante.
>>
>> Subsubsection 1a
>> Mauris eleifend, quam a vulputate dictum,
>> massa quam
>> dapibus leo, eget vulputate orci purus ut
>> lorem. In
>> fringilla mi in ligula.
>>
>> Sss 1b Pellentesque aliquam quam vel dolor. Nunc
>> adipiscing.
>> Sed quam odio, tempus ac, aliquam molestie,
>> varius ac,
>> tellus.
>>
>> Subsubsection 1c
>> Vestibulum ut nulla aliquam risus rutrum
>> interdum. Pel‐
>> lentesque lorem. Curabitur sit amet erat quis
>> risus feu‐
>> giat viverra.
>>
>> Subsection 2
>> Pellentesque augue justo, sagittis et, lacinia at.
>>
>> CONFORMING TO
>> Example.
>>
>> Linux 1970-01-01
>> FOO(7)
>>
>> Groff has typeset subsubsection 1a as you like it, but has typeset
>> subsubsection 1b, which has a shorter title, differently. This is okay
>> with me, but is it okay with you?
>
> Hmm, you're right. I knew the difference but didn't think of it in that
> case.
>
> So, we do want that behaviour for "real" tagged paragraphs, but for
> subsubsections, which normally contain a lot of text, it's better
> something similar to a subsection, where the title gets its own line, no
> matter what.
>
> There's a page that does that: system_data_types(7). I didn't recommend
> it to you, because in the inner .TP we don't want that. But in the
> outer ones we actually do, so we could use a mix.
>
>
> A more sensible approach would then be this one:
>
>
> .TH SUBSUBSECTIONS 1 2021 "Linux" "Test page"
> .SH NAME
> subsubsections \- subsubsections and tagged paragraphs
> .SH EXAMPLES
> .SS Subsection 1
> .TP
> .B Subsubsection 1a
> .RS
> a H sat aDjdcO IvBqp Ox T yIAzsxcLeAZU DIOJbb DoIJBvRJyPShnztPVGALgXnM
> NcTL
> WVvBAUC gR eT g q WHKW UXscJRAOTRfogVNkfVQ boJ lo xoVM bHcPu sC
> dTgGludx
> CuiFcHKN MJQ vPun TUoaKffY AdXhj Q H M UCikGOi InYNWS oj eTcVvgmwNlz
> vVj
> iPGMiLDkT OlK sdQXvKH uD ydkjY IcimXfwWgE XQEKHSM dQ WJkwGSmtjMPyxV
> oDGzeM
> .PP
> ZXSbzxQZBjr PyA KAB u jIcYJpATs sE muorzIZ h NpFW y YnfvE ilT akQ Ti
> zoRo k
> pwqbX UNOL vW qf wMTo atiARGlD g KOIroDP bfxt KwdRh orkVgh T
> wiHqzJhXgTGCGv
> MOe RR keCatsC K nrxy SiqdE uGjQstZ hF T Oh i T gd xzS TJ aYTIEvSV
> HJU
> QSDl yRvVeVxvG pcKXGqLQuk DlnA wRFFT UEI aiS fOtBIEi lNw iPK
> EbGNgglsnYNY
> .RE
> .TP
> .B Sss 1b
> .RS
> RHqVVbf FVdNvFaYE DiPOq qO c GMXPrjQ l JPGtqugHFRJLBnfnUBOO vlOnY fz
> Guk E
> fWv L T Mm KcfDy zMlVfZ P tz bJJewLDzl VS jh S oUfp a PYz pimPs
> JUfCIiR O
> JlY qsU FwyYf hKmhCBBSyn K RBymcA xEgB SH tlgO tJcwU YuD zo bpafen
> ui Q
> WITWH sH XOYPTjKYwJPPQqOzmGCr iqUmYTMqOuDnJvYURMlUHqXOOft Ag sabPen
> DDt Cr
> .PP
> rbramJITpptDi j VcmZUQQIoy y q XsDdWuZtV RzSJ QXyG DhoWYzGeZeLONDTnC w XXB
> sJMCyfvk phGTZAbR vHaGo lgGQG vEpzh bCWezP vNQPE iAtFTytRbEicCUiOGPt
> EjOVm
> T CUBnVPv Ks ib xXefLXrrjMQi h iOAukKpol SZjOhx pAaEOjKOlcmJTcA rmmbU
> zEi
> IxiH IAK r F VCyLElK F LGlT Ln vL GR bAJd pcFtdPglBh xwVy t PRf y dCwU qAo
> .RE
> .TP
> .B Sss 1c
> .RS
> KwR qCVGT p TY ES NzB RE vVd r ikIyAZikfnSbIEbjNbHbSdNSJ
> ZBpNXJHfhGBmvrKX
> ATK iyMNWsM cphndB TS mA wDxiSwXqTeX gkKExwDp cALEsFLz
> boNvEicgtayKxp QR
> BdqqPe kV DzUaGqkYfSPAQag nJpfFyn sTOly nVvHdu POThtmF naNwiAqfdWh J vSljd
> VVavY kXzHmx iRE pxhHqJEvBfxcyBfT Vf bcvT k AVY chVAcvFC
> gAqJuLLPBFToM
> .TP
> .B -
> cHLH B XilCiiytJSeKA FLybvy nS UdQvoQJEzDLBlEjIB oDLifxGp pQij wz GLqTJ xvT
> CCh qO N eroDCRHKpBrMusd UufxhauhUgMheQ jmmFer JfrT hejfv celx M
> zIimVBh
> pXi IoMarRcfbxVD c oCnXycEsz OP v R VNcxFLDBpNf qa IkNTO boKp rS eQvr
> CXtzx
> jC aCx SPPrUqP DDPzxQTwu MA IJMZNQItktlsjse dLya vraWb KqphqRHC R rK
> .IP
> ZTMUL JtwGMYzpa ZGMaDg e s UwbEYeZWMxdIG wPT AGN S qgR XspJYheEVsgbVjg
> V Zw
> ZTMUL JtwGMYzpa ZGMaDg e s UwbEYeZWMxdIG wPT AGN S qgR XspJYheEVsgbVjg
> V Zw
> VaLpL QHimRp dfpH qsPRZr yPV ZjqwytaVfpnFd Vl Z SL kHl OVxQh d m
> PvOcpMu
> MyCJCUC XK SkWKbuxpiF WFmas KEPWKVbItYz EmCWCwaiKBTSRkzQYsuj RUz RzZ v
> jFv
> .TP
> .B , . _
> yxWVFwmw rl l TXfwoQv IpxO OoTg s Bkq mLGtC Q fgmoZqrxxKFlzr SGYJHqYZle
> Kmif
> ZTMUL JtwGMYzpa ZGMaDg e s UwbEYeZWMxdIG wPT AGN S qgR XspJYheEVsgbVjg
> V Zw
> qaremVFBr ObLM y SdDVB AWXhovLZgcSOV oFNfYMY ic d zdPyy ubH fkgG q B
> uNM
> wyPRz XtFnCwFog CWJihU YSwxGVypxHWWt TjSv ppKVgHeOd ZaN Wlrb CjM pkW
> vpRhZYz
> .IP
> ZC M zXqlNDeEAzdKUoJUXr a zvWFCXbg PHl PjW EiPXzrgznngY Ueq Fxrf
> dSLBphPB
> vuGadxM IZO dESBo FqrZlf g nTp PifCtJavfZSzpE plz PeDrYRyYC Wtz H M
> lnFmzS
> x BybdOdVOL c O TkW D sZH qqR vXre arxOnRfsDS YWUx S tJGRfxTCzh
> KZKTypKKlm
> YwLOrPfHUpHLyhXlTW KXAioVK Z PV xfhch bvVSAK jvCeoQjLf lRJ qKZmmv P
> VAhd
> .RE
> .PP
> A last paragraph in subsection 1 main body.
> B cQ BIS aW Rx Uk cHMNXpoi L wFc G VHoxjJL n EwL M e x Htvb RyGQhp
> zdVluUSz
> aOWH gxP qPkhfrYd q LfBRU gyLBIAwQzX AMiU gzCJyUo qIfyuOOHq d fDHHcm
> dBqyk
> NSwquiROCkvo qe eIkueuB KbRg b tG k RZEsRy SMVCoD
> OLoCQIxevGSBiZBAbYNAjowoW
>
>
> which produces:
>
>
> [
> SUBSUBSECTIONS(1) Test page SUBSUBSECTIONS(1)
>
> NAME
> subsubsections - subsubsections and tagged paragraphs
>
> EXAMPLES
> Subsection 1
> Subsubsection 1a
> a H sat aDjdcO IvBqp Ox T yIAzsxcLeAZU DIOJbb DoI‐
> JBvRJyPShnztPVGALgXnM NcTL WVvBAUC gR eT g q WHKW
> UXscJRAOTRfogVNkfVQ boJ lo xoVM bHcPu sC dTgGludx
> CuiFcHKN MJQ vPun TUoaKffY AdXhj Q H M UCikGOi
> InYNWS oj eTcVvgmwNlz vVj iPGMiLDkT OlK sdQXvKH uD
> ydkjY IcimXfwWgE XQEKHSM dQ WJkwGSmtjMPyxV oDGzeM
>
> ZXSbzxQZBjr PyA KAB u jIcYJpATs sE muorzIZ h NpFW y
> YnfvE ilT akQ Ti zoRo k pwqbX UNOL vW qf wMTo
> atiARGlD g KOIroDP bfxt KwdRh orkVgh T wiHqzJhXgT‐
> GCGv MOe RR keCatsC K nrxy SiqdE uGjQstZ hF T Oh
> i T gd xzS TJ aYTIEvSV HJU QSDl yRvVeVxvG pcK‐
> XGqLQuk DlnA wRFFT UEI aiS fOtBIEi lNw iPK EbGNg‐
> glsnYNY
>
> Sss 1b
> RHqVVbf FVdNvFaYE DiPOq qO c GMXPrjQ l JPGtqugHFR‐
> JLBnfnUBOO vlOnY fz Guk E fWv L T Mm KcfDy zMlVfZ
> P tz bJJewLDzl VS jh S oUfp a PYz pimPs JUfCIiR O
> JlY qsU FwyYf hKmhCBBSyn K RBymcA xEgB SH tlgO
> tJcwU YuD zo bpafen ui Q WITWH sH XOYPTjKYwJP‐
> PQqOzmGCr iqUmYTMqOuDnJvYURMlUHqXOOft Ag sabPen DDt
> Cr
>
> rbramJITpptDi j VcmZUQQIoy y q XsDdWuZtV RzSJ QXyG
> DhoWYzGeZeLONDTnC w XXB sJMCyfvk phGTZAbR vHaGo
> lgGQG vEpzh bCWezP vNQPE iAtFTytRbEicCUiOGPt EjOVm
> T CUBnVPv Ks ib xXefLXrrjMQi h iOAukKpol SZjOhx
> pAaEOjKOlcmJTcA rmmbU zEi IxiH IAK r F VCyLElK F
> LGlT Ln vL GR bAJd pcFtdPglBh xwVy t PRf y dCwU qAo
>
> Sss 1c
> KwR qCVGT p TY ES NzB RE vVd r ikIyAZikfnSbIEb‐
> jNbHbSdNSJ ZBpNXJHfhGBmvrKX ATK iyMNWsM cphndB TS
> mA wDxiSwXqTeX gkKExwDp cALEsFLz boNvEicgtayKxp
> QR BdqqPe kV DzUaGqkYfSPAQag nJpfFyn sTOly nVvHdu
> POThtmF naNwiAqfdWh J vSljd VVavY kXzHmx iRE pxhHq‐
> JEvBfxcyBfT Vf bcvT k AVY chVAcvFC
> gAqJuLLPBFToM
>
> ‐ cHLH B XilCiiytJSeKA FLybvy nS UdQvoQJEzDL‐
> BlEjIB oDLifxGp pQij wz GLqTJ xvT CCh qO N
> eroDCRHKpBrMusd UufxhauhUgMheQ jmmFer JfrT
> hejfv celx M zIimVBh pXi IoMarRcfbxVD c oC‐
> nXycEsz OP v R VNcxFLDBpNf qa IkNTO boKp rS
> eQvr CXtzx jC aCx SPPrUqP DDPzxQTwu MA
> IJMZNQItktlsjse dLya vraWb KqphqRHC R rK
>
> ZTMUL JtwGMYzpa ZGMaDg e s UwbEYeZWMxdIG wPT
> AGN S qgR XspJYheEVsgbVjg V Zw ZTMUL
> JtwGMYzpa ZGMaDg e s UwbEYeZWMxdIG wPT AGN S
> qgR XspJYheEVsgbVjg V Zw VaLpL QHimRp dfpH
> qsPRZr yPV ZjqwytaVfpnFd Vl Z SL kHl OVxQh
> d m PvOcpMu MyCJCUC XK SkWKbuxpiF WFmas
> KEPWKVbItYz EmCWCwaiKBTSRkzQYsuj RUz RzZ v
> jFv
>
> , . _ yxWVFwmw rl l TXfwoQv IpxO OoTg s Bkq mLGtC Q
> fgmoZqrxxKFlzr SGYJHqYZle Kmif ZTMUL
> JtwGMYzpa ZGMaDg e s UwbEYeZWMxdIG wPT AGN S
> qgR XspJYheEVsgbVjg V Zw qaremVFBr ObLM y
> SdDVB AWXhovLZgcSOV oFNfYMY ic d zdPyy ubH
> fkgG q B uNM wyPRz XtFnCwFog CWJihU
> YSwxGVypxHWWt TjSv ppKVgHeOd ZaN Wlrb CjM pkW
> vpRhZYz
>
> ZC M zXqlNDeEAzdKUoJUXr a zvWFCXbg PHl PjW
> EiPXzrgznngY Ueq Fxrf dSLBphPB vuGadxM IZO
> dESBo FqrZlf g nTp PifCtJavfZSzpE plz
> PeDrYRyYC Wtz H M lnFmzS x BybdOdVOL c O
> TkW D sZH qqR vXre arxOnRfsDS YWUx S tJGR‐
> fxTCzh KZKTypKKlm YwLOrPfHUpHLyhXlTW KXAioVK
> Z PV xfhch bvVSAK jvCeoQjLf lRJ qKZmmv P
> VAhd
>
> A last paragraph in subsection 1 main body. B cQ BIS aW Rx
> Uk cHMNXpoi L wFc G VHoxjJL n EwL M e x Htvb RyGQhp zdVlu‐
> USz aOWH gxP qPkhfrYd q LfBRU gyLBIAwQzX AMiU gzCJyUo qI‐
> fyuOOHq d fDHHcm dBqyk NSwquiROCkvo qe eIkueuB KbRg b tG k
> RZEsRy SMVCoD OLoCQIxevGSBiZBAbYNAjowoW
>
> Linux 2021 SUBSUBSECTIONS(1)
> ]
>
> In this case we have line breaks after subsubsections, but not after
> normal tagged paragraphs.
I'm a bit worried that this might be overcomplicating it, and maybe a
hypothetical .SSS macro would be useful here (or another solution). Do
you have any thoughts about it?
That hypothetical macro would behave like .TP + .B + .RS (as shown
above; and that .RS would only end at a following .SSS/.SS/.SH)
Thanks,
Alex
--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [PATCH 3/3] Use subsections instead of sections
2021-09-12 14:56 ` Alejandro Colomar (man-pages)
@ 2021-09-12 15:22 ` Thaddeus H. Black
2021-09-12 18:49 ` G. Branden Robinson
2021-09-12 18:12 ` G. Branden Robinson
1 sibling, 1 reply; 20+ messages in thread
From: Thaddeus H. Black @ 2021-09-12 15:22 UTC (permalink / raw)
To: Alejandro Colomar (man-pages)
Cc: G. Branden Robinson, Michael Kerrisk, linux-man
[-- Attachment #1: Type: text/plain, Size: 630 bytes --]
On Sun, Sep 12, 2021 at 04:56:21PM +0200, Alejandro Colomar (man-pages) wrote:
> I'm a bit worried that this might be overcomplicating it, and maybe a
> hypothetical .SSS macro would be useful here (or another solution). Do you
> have any thoughts about it?
>
> That hypothetical macro would behave like .TP + .B + .RS (as shown above;
> and that .RS would only end at a following .SSS/.SS/.SH)
It is not important to me that my .SSS macro be used, but for reference
here it is:
.de1 SSS
. if !r SSS_SN_ORIG .nr SSS_SN_ORIG \\n[SN]
. nr SN (2 * \\n[SSS_SN_ORIG])
. SS \&\\$*
. nr SN (\\n[SSS_SN_ORIG])
..
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [PATCH 3/3] Use subsections instead of sections
2021-09-12 14:56 ` Alejandro Colomar (man-pages)
2021-09-12 15:22 ` Thaddeus H. Black
@ 2021-09-12 18:12 ` G. Branden Robinson
2021-09-12 22:39 ` Alejandro Colomar (man-pages)
1 sibling, 1 reply; 20+ messages in thread
From: G. Branden Robinson @ 2021-09-12 18:12 UTC (permalink / raw)
To: Alejandro Colomar (man-pages)
Cc: Michael Kerrisk, linux-man, Thaddeus H. Black
[-- Attachment #1: Type: text/plain, Size: 4332 bytes --]
Hi, Alex!
At 2021-09-12T16:56:21+0200, Alejandro Colomar (man-pages) wrote:
> I'm a bit worried that this might be overcomplicating it, and maybe a
> hypothetical .SSS macro would be useful here (or another solution).
> Do you have any thoughts about it?
>
> That hypothetical macro would behave like .TP + .B + .RS (as shown
> above; and that .RS would only end at a following .SSS/.SS/.SH)
I've come to the view, due mainly to exposure rather than an attempt at
rigorous reasoning, that if you need subsubsections in a _man page_,
that the level of discussion for the page overall is too coarse.
It's pretty rare that I've seen a need for subsubsections expressed, and
I must confess to some unease with recruiting the tagged paragraph macro
to the purpose of achieving them. To return to the perennial topic of
semantic macros, `TP` has considerable semantic value (much more than,
say, `SM` for small text), and that value is weakened if we reach for it
because we desire its _visual_ effect.
Do you have a list handy of the man-pages documents that you see as
requiring this kind of structure? I can put on my technical writing hat
and see what I think of them.
For now, at the low level of *roff mac-fu, I don't actually see much of
a technical challenge. Just as a first stab in the dark, he's here how
I might implement the beast you request.
.nr an-in-SX 0
.de1 SX
. if !\\n[.$] \
. an-style-warn .\\$0 expects at least 1 argument, got \\n[.$]
. if \\n[an-in-SX] .RE
. TP \\n[.l]u
. B \\$@
. nr an-in-SX 1
. RS
..
.am SH
. nr an-in-SX 0
..
.am SS
. nr an-in-SX 0
..
Noteworthy points:
1. I wrote this on the fly while composing this mail; if you try it,
don't expect it to work perfectly.
2. I defined the macro with groff's `de1` request so that the macro
would be interpreted with compatibility mode off. This enables the
use of groff extensions even on Solaris where compatibility mode is
on by default, but I don't know if anyone reads the Linux man-pages
on Solaris boxen. Plain `de` would be fine if they don't. I
needed only a couple of groff extensions anyway: (a) long request
names and (b) bracket-based register interpolation syntax. Neither
of these is essential and the above could be implemented with few
changes in vintage 1979 AT&T troff.
3. I used a groff man(7) internal macro to style check and warn if
the number of parameters is not appropriate.
4. I told `TP` to use the width of an output line for the tag width.
This guarantees that the paragraph proper won't begin on the same
output line as paragraph tag no matter how short that tag is, which
is what we want since we're faking a (sub-sub-)section heading.
5. I set up a Boolean variable to keep track of whether we're "in" a
sub-sub-section. For this to work cleanly I need to (a) initialize
it outside of any macro definition; (b) test it so I know when I need
to undo my relative inset for the subsection; and (c) append to the
macros SH and SS since they already clear all relative insets,
including any I may have set up with this new macro.
You might experiment with this by adding it to man pages that require
it. This sort of material is then called "page-local macros" and Ingo
Schwarze and I both discourage such practice in publicly distributed man
pages[1].
To be able to manage sub*sections to arbitrary depth would require
maintenance of a stack or queue rather than a simple Boolean flag, but
it could be done.
However, my intuition is, again, that if you feel a strong pressure to
have three tiers of page organization before you even get to the level
of individual topics of discussion in paragraphs (tagged or otherwise),
maybe the page is trying to cover too much material.
Regards,
Branden
[1] Admittedly, groff itself still has some man pages with page-local
macros. I haven't deeply researched the history, but my impression
is that they antedate mandoc(1) and a variety of "man2html" tools of
divergent, mostly horrible, quality. Some pages, like groff(7),
will require a major effort to clean up. However, groff 1.22.4 was
already improved over 1.22.3 in this respect, and groff 1.23.0 will
be _much_ improved.
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [PATCH 3/3] Use subsections instead of sections
2021-09-12 15:22 ` Thaddeus H. Black
@ 2021-09-12 18:49 ` G. Branden Robinson
0 siblings, 0 replies; 20+ messages in thread
From: G. Branden Robinson @ 2021-09-12 18:49 UTC (permalink / raw)
To: Thaddeus H. Black
Cc: Alejandro Colomar (man-pages), Michael Kerrisk, linux-man
[-- Attachment #1: Type: text/plain, Size: 1288 bytes --]
At 2021-09-12T15:22:35+0000, Thaddeus H. Black wrote:
> On Sun, Sep 12, 2021 at 04:56:21PM +0200, Alejandro Colomar
> (man-pages) wrote:
> > I'm a bit worried that this might be overcomplicating it, and maybe
> > a hypothetical .SSS macro would be useful here (or another
> > solution). Do you have any thoughts about it?
> >
> > That hypothetical macro would behave like .TP + .B + .RS (as shown
> > above; and that .RS would only end at a following .SSS/.SS/.SH)
>
> It is not important to me that my .SSS macro be used, but for
> reference here it is:
>
> .de1 SSS
> . if !r SSS_SN_ORIG .nr SSS_SN_ORIG \\n[SN]
> . nr SN (2 * \\n[SSS_SN_ORIG])
> . SS \&\\$*
> . nr SN (\\n[SSS_SN_ORIG])
> ..
Oh, I definitely like this better than my own straw-man proposal. It's
much cleaner.
I still question the need for this depth of organization in a man page,
but I could see the aboev becoming a nestable `SN` sub*-sectioning macro
much more straightforwardly than a TP/B/RS-based solution.
Of course, this one only indents the section heading itself, not the
paragraphs the follow, so some RS/RE tomfoolery would likely still be
required.
Good to see you, Thaddeus--I definitely remember you from Debian mailing
list days. :)
Regards,
Branden
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [PATCH 3/3] Use subsections instead of sections
2021-09-12 18:12 ` G. Branden Robinson
@ 2021-09-12 22:39 ` Alejandro Colomar (man-pages)
0 siblings, 0 replies; 20+ messages in thread
From: Alejandro Colomar (man-pages) @ 2021-09-12 22:39 UTC (permalink / raw)
To: G. Branden Robinson; +Cc: Michael Kerrisk, linux-man, Thaddeus H. Black
Hi, Branden!
On 9/12/21 8:12 PM, G. Branden Robinson wrote:
> Hi, Alex!
>
> At 2021-09-12T16:56:21+0200, Alejandro Colomar (man-pages) wrote:
>> I'm a bit worried that this might be overcomplicating it, and maybe a
>> hypothetical .SSS macro would be useful here (or another solution).
>> Do you have any thoughts about it?
>>
>> That hypothetical macro would behave like .TP + .B + .RS (as shown
>> above; and that .RS would only end at a following .SSS/.SS/.SH)
>
> I've come to the view, due mainly to exposure rather than an attempt at
> rigorous reasoning, that if you need subsubsections in a _man page_,
> that the level of discussion for the page overall is too coarse.
>
> It's pretty rare that I've seen a need for subsubsections expressed, and
> I must confess to some unease with recruiting the tagged paragraph macro
> to the purpose of achieving them. To return to the perennial topic of
> semantic macros, `TP` has considerable semantic value (much more than,
> say, `SM` for small text), and that value is weakened if we reach for it
> because we desire its _visual_ effect.
>
> Do you have a list handy of the man-pages documents that you see as
> requiring this kind of structure? I can put on my technical writing hat
> and see what I think of them.
The only pages that I know from the top of my head that have a lot of
subsubsection-like nested indentation, are the biggest ones (e.g.,
proc(5)), and my baby, system_data_types(7), which is already too grown
that we should think about splitting it into many little pages. So I
think there's no good example (or more precisely, I don't know them).
So, I would like to reuse the same methods as in other pages, more since
this is a quite small page, and shouldn't be problematic. Maybe using
.TP is the best option. I was just afraid of overcomplicating it, but
since the other alternatives seem worse, I think it's fine.
I'll prepare the (sub)patch for Thaddeus, probably tomorrow, and we'll see.
Thanks for your input!
>
> For now, at the low level of *roff mac-fu, I don't actually see much of
> a technical challenge. Just as a first stab in the dark, he's here how
> I might implement the beast you request.
>
> .nr an-in-SX 0
> .de1 SX
> . if !\\n[.$] \
> . an-style-warn .\\$0 expects at least 1 argument, got \\n[.$]
> . if \\n[an-in-SX] .RE
> . TP \\n[.l]u
> . B \\$@
> . nr an-in-SX 1
> . RS
> ..
> .am SH
> . nr an-in-SX 0
> ..
> .am SS
> . nr an-in-SX 0
> ..
>
> Noteworthy points:
>
> 1. I wrote this on the fly while composing this mail; if you try it,
> don't expect it to work perfectly.
> 2. I defined the macro with groff's `de1` request so that the macro
> would be interpreted with compatibility mode off. This enables the
> use of groff extensions even on Solaris where compatibility mode is
> on by default, but I don't know if anyone reads the Linux man-pages
> on Solaris boxen. Plain `de` would be fine if they don't. I
> needed only a couple of groff extensions anyway: (a) long request
> names and (b) bracket-based register interpolation syntax. Neither
> of these is essential and the above could be implemented with few
> changes in vintage 1979 AT&T troff.
> 3. I used a groff man(7) internal macro to style check and warn if
> the number of parameters is not appropriate.
> 4. I told `TP` to use the width of an output line for the tag width.
> This guarantees that the paragraph proper won't begin on the same
> output line as paragraph tag no matter how short that tag is, which
> is what we want since we're faking a (sub-sub-)section heading.
BTW, if I understood this right, that's already forced by .RS, so you
don't need to care. .RS (at least in the cases I used it) already
forced a line break between the tag and the paragraph (see
system_data_types(7)).
[
cc_t
Include: <termios.h>.
Used for terminal special characters. According to
POSIX, it shall be an unsigned integer type.
Conforming to: POSIX.1‐2001 and later.
See also: termios(3)
]
> 5. I set up a Boolean variable to keep track of whether we're "in" a
> sub-sub-section. For this to work cleanly I need to (a) initialize
> it outside of any macro definition; (b) test it so I know when I need
> to undo my relative inset for the subsection; and (c) append to the
> macros SH and SS since they already clear all relative insets,
> including any I may have set up with this new macro.
>
> You might experiment with this by adding it to man pages that require
> it. This sort of material is then called "page-local macros" and Ingo
> Schwarze and I both discourage such practice in publicly distributed man
> pages[1].
>
> To be able to manage sub*sections to arbitrary depth would require
> maintenance of a stack or queue rather than a simple Boolean flag, but
> it could be done.
>
> However, my intuition is, again, that if you feel a strong pressure to
> have three tiers of page organization before you even get to the level
> of individual topics of discussion in paragraphs (tagged or otherwise),
> maybe the page is trying to cover too much material.
Yes, and I was seeking your intuition! So, .TP will do it, I think.
The second best option I think would be using custom sections.
Thanks!
Best regards,
Alex
>
> Regards,
> Branden
>
> [1] Admittedly, groff itself still has some man pages with page-local
> macros. I haven't deeply researched the history, but my impression
> is that they antedate mandoc(1) and a variety of "man2html" tools of
> divergent, mostly horrible, quality. Some pages, like groff(7),
> will require a major effort to clean up. However, groff 1.22.4 was
> already improved over 1.22.3 in this respect, and groff 1.23.0 will
> be _much_ improved.
>
--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
^ permalink raw reply [flat|nested] 20+ messages in thread
end of thread, other threads:[~2021-09-12 22:39 UTC | newest]
Thread overview: 20+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-09-06 11:40 [PATCH] filename.7: new manual page Thaddeus H. Black
2021-09-06 14:21 ` Alejandro Colomar (man-pages)
2021-09-06 16:59 ` G. Branden Robinson
2021-09-06 21:47 ` Alejandro Colomar (man-pages)
2021-09-08 3:54 ` G. Branden Robinson
2021-09-08 14:56 ` Thaddeus H. Black
2021-09-08 15:45 ` Alejandro Colomar (man-pages)
2021-09-09 2:15 ` Thaddeus H. Black
2021-09-09 2:45 ` Thaddeus H. Black
2021-09-09 7:24 ` [PATCH 1/3] Remove unnecessary .P after .S[HS] Alejandro Colomar
2021-09-09 7:24 ` [PATCH 2/3] Fix indentation of paragraph, which continues talking about \0 Alejandro Colomar
2021-09-09 7:24 ` [PATCH 3/3] Use subsections instead of sections Alejandro Colomar
2021-09-09 7:28 ` [PATCH] .P -> .PP Alejandro Colomar
2021-09-12 14:20 ` [PATCH 3/3] Use subsections instead of sections Thaddeus H. Black
2021-09-12 14:49 ` Alejandro Colomar (man-pages)
2021-09-12 14:56 ` Alejandro Colomar (man-pages)
2021-09-12 15:22 ` Thaddeus H. Black
2021-09-12 18:49 ` G. Branden Robinson
2021-09-12 18:12 ` G. Branden Robinson
2021-09-12 22:39 ` Alejandro Colomar (man-pages)
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.