Bug#1089519: clang-tidy-19.1: Some remarks about this man page
Bjarni Ingi Gislason
bjarniig at simnet.is
Sun Dec 8 10:51:46 GMT 2024
Package: clang-tidy-19
Version: 1:19.1.4-1
Severity: minor
Tags: patch
* What led up to the situation?
Checking for defects with
test-[g|n]roff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z < "man page"
[Use "groff -e ' $' <file>" to find trailing spaces.]
["test-groff" is a script in the repository for "groff"; is not shipped]
(local copy and "troff" slightly changed by me).
[The fate of "test-nroff" was decided in groff bug #55941.]
* What was the outcome of this action?
troff:<stdin>:270: warning: font name 'CW' is deprecated
* What outcome did you expect instead?
No output (no warnings).
-.-
General remarks and further material, if a diff-file exist, are in the
attachments.
-- System Information:
Debian Release: trixie/sid
APT prefers testing
APT policy: (500, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.11.10-amd64 (SMP w/2 CPU threads; PREEMPT)
Locale: LANG=is_IS.iso88591, LC_CTYPE=is_IS.iso88591 (charmap=ISO-8859-1), LANGUAGE not set
Shell: /bin/sh linked to /usr/bin/dash
Init: sysvinit (via /sbin/init)
Versions of packages clang-tidy-19 depends on:
ii clang-tools-19 1:19.1.4-1
ii libc6 2.40-4
ii libclang-common-19-dev 1:19.1.4-1
ii libclang-cpp19 1:19.1.4-1
ii libgcc-s1 14.2.0-8
ii libllvm19 1:19.1.4-1
ii libstdc++6 14.2.0-8
ii python3 3.12.6-1
ii python3-yaml 6.0.2-1+b1
clang-tidy-19 recommends no packages.
clang-tidy-19 suggests no packages.
-- no debconf information
-------------- next part --------------
Input file is clang-tidy-19.1
Any program (person), that produces man pages, should check the output
for defects by using (both groff and nroff)
[gn]roff -mandoc -t -ww -b -z -K utf8 <man page>
The same goes for man pages that are used as an input.
For a style guide use
mandoc -T lint
-.-
So any 'generator' should check its products with the above mentioned
'groff', 'mandoc', and additionally with 'nroff ...'.
This is just a simple quality control measure.
The 'generator' may have to be corrected to get a better man page,
the source file may, and any additional file may.
Common defects:
Input text line longer than 80 bytes.
Not removing trailing spaces (in in- and output).
The reason for these trailing spaces should be found and eliminated.
Not beginning each input sentence on a new line.
Lines should thus be shorter.
See man-pages(7), item 'semantic newline'.
-.-
The difference between the formatted output of the original and patched file
can be seen with:
nroff -mandoc <file1> > <out1>
nroff -mandoc <file2> > <out2>
diff -u <out1> <out2>
and for groff, using
"printf '%s\n%s\n' '.kern 0' '.ss 12 0' | groff -mandoc -Z - "
instead of 'nroff -mandoc'
Add the option '-t', if the file contains a table.
Read the output of 'diff -u' with 'less -R' or similar.
-.-.
If 'man' (man-db) is used to check the manual for warnings,
the following must be set:
The option "-warnings=w"
The environmental variable:
export MAN_KEEP_STDERR=yes (or any non-empty value)
or
(produce only warnings):
export MANROFFOPT="-ww -b -z"
export MAN_KEEP_STDERR=yes (or any non-empty value)
-.-.
Output from "mandoc -T lint clang-tidy-19.1 ": (shortened list)
1 input text line longer than 80 bytes
-.-.
Output from "test-groff -mandoc -t -ww -b -z clang-tidy-19.1 ": (shortened list)
1 font name 'CW' is deprecated
-.-.
Output from "mandoc -T lint clang-tidy-19.1 ":
mandoc: clang-tidy-19.1:180:85: STYLE: input text line longer than 80 bytes: compile_commands.jso...
-.-.
Change two HYPHEN-MINUSES (code 0x2D) to an em-dash (\(em),
if one is intended.
" \(em " creates a too big gap in the text (in "troff").
An en-dash is usually surrounded by a space,
while an em-dash is used without spaces.
"man" (1 byte characters in input) transforms an en-dash (\(en) to one
HYPHEN-MINUS,
and an em-dash to two HYPHEN-MINUSES without considering the space
around it.
If "--" are two single "-"
(begin of an option or end of options)
then use "\-\-".
clang-tidy-19.1:270:\f(CW$ clang-tidy --dump-config\fR
-.-.
Change -- in x--y to \(em (em-dash), or, if an
option, to \-\-
270:\f(CW$ clang-tidy --dump-config\fR
-.-.
Change a HYPHEN-MINUS (code 0x2D) to a minus(-dash) (\-),
if it
is in front of a name for an option,
is a symbol for standard input,
is a single character used to indicate an option,
or is in the NAME section (man-pages(7)).
N.B. - (0x2D), processed as a UTF-8 file, is changed to a hyphen
(0x2010, groff \[u2010] or \[hy]) in the output.
270:\f(CW$ clang-tidy --dump-config\fR
-.-.
Add a comma (or \&) after "e.g." and "i.e.", or use English words
(man-pages(7)).
Abbreviation points should be protected against being interpreted as
an end of sentence, if they are not, and that independent of the
current place on the line.
43:e.g. \fB\-\-config\-file=\fR/some/path/myTidyConfigFile
78:enabled, i.e. in clang\-tidy binary, command
111:\- '{ <json> }' specifies options inline, e.g.
-.-.
Wrong distance between sentences in the input file.
Separate the sentences and subordinate clauses; each begins on a new
line. See man-pages(7) ("Conventions for source file layout") and
"info groff" ("Input Conventions").
The best procedure is to always start a new sentence on a new line,
at least, if you are typing on a computer.
Remember coding: Only one command ("sentence") on each (logical) line.
E-mail: Easier to quote exactly the relevant lines.
Generally: Easier to edit the sentence.
Patches: Less unaffected text.
Search for two adjacent words is easier, when they belong to the same line,
and the same phrase.
The amount of space between sentences in the output can then be
controlled with the ".ss" request.
N.B.
The number of lines affected can be too large to be in a patch.
6:USAGE: clang\-tidy [options] <source0> [... <sourceN>]
20:\fB\-\-allow\-no\-checks\fR \- Allow empty enabled checks. This suppresses
25:prefix. Globs are processed in order of
26:appearance in the list. Globs without '\-'
30:checks. This option's value is appended to the
43:e.g. \fB\-\-config\-file=\fR/some/path/myTidyConfigFile
51:stdout. This option can be used along with a
64:to detect macro definitions within modules. This
69:headers to exclude diagnostics from. Diagnostics
78:enabled, i.e. in clang\-tidy binary, command
81:\fB\-\-export\-fixes=\fR<filename> \- YAML file to store suggested fixes in. The
89:\fB\-\-fix\fR \- Apply suggested fixes. Without \fB\-fix\-errors\fR
94:errors were found. If compiler errors have
121:headers to output diagnostics from. Diagnostics
129:warnings. Can be used together with
130:\fB\-header\-filter\fR. The format of the list is a
139:\fB\-\-list\-checks\fR \- List all enabled checks and exit. Use with
146:\fB\-\-quiet\fR \- Run clang\-tidy in quiet mode. This suppresses
152:format to stderr. When this option is passed,
159:\fB\-\-use\-color\fR \- Use colors in diagnostics. If not set, colors
171:\fB\-\-warnings\-as\-errors=\fR<string> \- Upgrades warnings to errors. Same format as
181:CMake option to get this output). When no build path is specified,
183:parent paths of the first input file . See:
187:<source0> ... specify the paths of source files. These paths are
189:looked up in the compile command database. If the path of a file is
190:absolute, it needs to point into CMake's source tree. If the path is
193:working directory. "./" prefixes in the relative files will be
200:file. The .clang\-tidy file is specified in YAML format. If any configuration
209:options. Example:
215:\- Same as '\-\-checks'. Additionally, the list of
261:running clang\-tidy. This option is used, for
-.-.
Split lines longer than 80 characters into two or more lines.
Appropriate break points are the end of a sentence and a subordinate
clause; after punctuation marks.
N.B.
The number of lines affected can be too large to be in a patch.
Line 12, length 103
\fB\-\-help\fR \- Display available options (\fB\-\-help\-hidden\fR for more)
Line 14, length 118
\fB\-\-help\-list\fR \- Display list of available options (\fB\-\-help\-list\-hidden\fR for more)
Line 20, length 89
\fB\-\-allow\-no\-checks\fR \- Allow empty enabled checks. This suppresses
Line 24, length 93
\fB\-\-checks=\fR<string> \- Comma\-separated list of globs with optional '\-'
Line 34, length 90
\fB\-\-config=\fR<string> \- Specifies a configuration in YAML/JSON format:
Line 42, length 100
\fB\-\-config\-file=\fR<string> \- Specify the path of .clang\-tidy or custom config file:
Line 50, length 86
\fB\-\-dump\-config\fR \- Dumps configuration in the YAML format to
Line 59, length 92
\fB\-\-enable\-check\-profile\fR \- Enable per\-check timing profiles, and print a
Line 62, length 96
\fB\-\-enable\-module\-headers\-parsing\fR \- Enables preprocessor\-level module header parsing
Line 68, length 90
\fB\-\-exclude\-header\-filter=\fR<string> \- Regular expression matching the names of the
Line 77, length 89
\fB\-\-explain\-config\fR \- For each enabled check explains, where it is
Line 81, length 87
\fB\-\-export\-fixes=\fR<filename> \- YAML file to store suggested fixes in. The
Line 85, length 103
\fB\-\-extra\-arg=\fR<string> \- Additional argument to append to the compiler command line
Line 87, length 105
\fB\-\-extra\-arg\-before=\fR<string> \- Additional argument to prepend to the compiler command line
Line 89, length 94
\fB\-\-fix\fR \- Apply suggested fixes. Without \fB\-fix\-errors\fR
Line 93, length 86
\fB\-\-fix\-errors\fR \- Apply suggested fixes even if compilation
Line 98, length 90
\fB\-\-fix\-notes\fR \- If a warning has no fix, but a single fix can
Line 104, length 92
\fB\-\-format\-style=\fR<string> \- Style for formatting code around applied fixes:
Line 120, length 89
\fB\-\-header\-filter=\fR<string> \- Regular expression matching the names of the
Line 128, length 89
\fB\-\-line\-filter=\fR<string> \- List of files with line ranges to filter the
Line 139, length 87
\fB\-\-list\-checks\fR \- List all enabled checks and exit. Use with
Line 146, length 90
\fB\-\-quiet\fR \- Run clang\-tidy in quiet mode. This suppresses
Line 151, length 89
\fB\-\-store\-check\-profile=\fR<prefix> \- By default reports are printed in tabulated
Line 155, length 84
\fB\-\-system\-headers\fR \- Display the errors from system headers.
Line 159, length 90
\fB\-\-use\-color\fR \- Use colors in diagnostics. If not set, colors
Line 165, length 92
\fB\-\-verify\-config\fR \- Check the config files to ensure each check and
Line 168, length 92
\fB\-\-vfsoverlay=\fR<filename> \- Overlay the virtual filesystem described by file
Line 171, length 89
\fB\-\-warnings\-as\-errors=\fR<string> \- Upgrades warnings to errors. Same format as
Line 180, length 85
compile_commands.json exists (use \fB\-DCMAKE_EXPORT_COMPILE_COMMANDS\fR=\fI\,ON\/\fR
-.-.
Use \(en (en-dash) for a dash at the beginning of a line,
or between space characters,
not a minus (\-) or a hyphen (-), except in the NAME section.
clang-tidy-19.1:105:\- 'none' (default) turns off formatting
clang-tidy-19.1:106:\- 'file' (literally 'file', not a placeholder)
clang-tidy-19.1:111:\- '{ <json> }' specifies options inline, e.g.
clang-tidy-19.1:114:\- 'llvm', 'google', 'webkit', 'mozilla'
clang-tidy-19.1:207:\- List of key\-value pairs defining check\-specific
clang-tidy-19.1:215:\- Same as '\-\-checks'. Additionally, the list of
clang-tidy-19.1:221:\- Same as '\-\-exclude\-header\-filter'.
clang-tidy-19.1:224:\- Same as '\-\-extra\-args'.
clang-tidy-19.1:227:\- Same as '\-\-extra\-args\-before'.
clang-tidy-19.1:230:\- Same as '\-\-format\-style'.
clang-tidy-19.1:233:\- File extensions to consider to determine if a
clang-tidy-19.1:238:\- Same as '\-\-header\-filter\-regex'.
clang-tidy-19.1:245:\- If this option is true in a config file, the
clang-tidy-19.1:253:\- Same as '\-\-system\-headers'.
clang-tidy-19.1:256:\- Same as '\-\-use\-color'.
clang-tidy-19.1:259:\- Specifies the name or e\-mail of the user
clang-tidy-19.1:266:\- Same as '\-\-warnings\-as\-errors'.
-.-.
Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".
clang-tidy-19.1:12:\fB\-\-help\fR \- Display available options (\fB\-\-help\-hidden\fR for more)
clang-tidy-19.1:14:\fB\-\-help\-list\fR \- Display list of available options (\fB\-\-help\-list\-hidden\fR for more)
clang-tidy-19.1:106:\- 'file' (literally 'file', not a placeholder)
-.-.
Change a HYPHEN-MINUS (code 0x55, 2D) to a dash
(\-, minus) if it matches "[[:alph:]]-[[:alpha:]]" in the name of an
option).
Facilitates the copy and paste of
a) an option in UTF-8 text
b) web addresses (URL).
Is not needed in ordinary words like "mother-in-law", that are not
copied and pasted to a command line (which needs ASCII code)
270:\f(CW$ clang-tidy --dump-config\fR
-.-.
Two or more space charaters between printable characters.
When the distance is between sentences,
start the beginning of the second one on a separate line
("semantic newline", see man-pages(7)).
N.B.
The number of lines affected can be too large to be in a patch.
12:\fB\-\-help\fR \- Display available options (\fB\-\-help\-hidden\fR for more)
14:\fB\-\-help\-list\fR \- Display list of available options (\fB\-\-help\-list\-hidden\fR for more)
16:\fB\-\-version\fR \- Display the version of this program
20:\fB\-\-allow\-no\-checks\fR \- Allow empty enabled checks. This suppresses
24:\fB\-\-checks=\fR<string> \- Comma\-separated list of globs with optional '\-'
34:\fB\-\-config=\fR<string> \- Specifies a configuration in YAML/JSON format:
42:\fB\-\-config\-file=\fR<string> \- Specify the path of .clang\-tidy or custom config file:
50:\fB\-\-dump\-config\fR \- Dumps configuration in the YAML format to
59:\fB\-\-enable\-check\-profile\fR \- Enable per\-check timing profiles, and print a
62:\fB\-\-enable\-module\-headers\-parsing\fR \- Enables preprocessor\-level module header parsing
77:\fB\-\-explain\-config\fR \- For each enabled check explains, where it is
81:\fB\-\-export\-fixes=\fR<filename> \- YAML file to store suggested fixes in. The
85:\fB\-\-extra\-arg=\fR<string> \- Additional argument to append to the compiler command line
87:\fB\-\-extra\-arg\-before=\fR<string> \- Additional argument to prepend to the compiler command line
89:\fB\-\-fix\fR \- Apply suggested fixes. Without \fB\-fix\-errors\fR
93:\fB\-\-fix\-errors\fR \- Apply suggested fixes even if compilation
98:\fB\-\-fix\-notes\fR \- If a warning has no fix, but a single fix can
104:\fB\-\-format\-style=\fR<string> \- Style for formatting code around applied fixes:
120:\fB\-\-header\-filter=\fR<string> \- Regular expression matching the names of the
128:\fB\-\-line\-filter=\fR<string> \- List of files with line ranges to filter the
139:\fB\-\-list\-checks\fR \- List all enabled checks and exit. Use with
142:\fB\-\-load=\fR<pluginfilename> \- Load the specified plugin
144:\fB\-p\fR <string> \- Build path
146:\fB\-\-quiet\fR \- Run clang\-tidy in quiet mode. This suppresses
151:\fB\-\-store\-check\-profile=\fR<prefix> \- By default reports are printed in tabulated
155:\fB\-\-system\-headers\fR \- Display the errors from system headers.
159:\fB\-\-use\-color\fR \- Use colors in diagnostics. If not set, colors
165:\fB\-\-verify\-config\fR \- Check the config files to ensure each check and
168:\fB\-\-vfsoverlay=\fR<filename> \- Overlay the virtual filesystem described by file
171:\fB\-\-warnings\-as\-errors=\fR<string> \- Upgrades warnings to errors. Same format as
284:HeaderFilterRegex: ''
285:FormatStyle: none
286:InheritParentConfig: true
287:User: user
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -z ":
troff:<stdin>:270: warning: font name 'CW' is deprecated
-.-.
Use the font 'CR' (groff) instead of 'CW'.
-.-
Use a table (tbl) for options list.
More information about the Pkg-llvm-team
mailing list