Package: binutils-common
Version: 2.42-4
Severity: minor
Dear Maintainer,
here are some notes for the manual.
-.-
The man page is created by Pod::Man (Pod::Simple).
A new version of 'Pod::Man' is needed.
The source file and the processing command may need to be fixed.
-.-
The difference between the formatted outputs can be seen with:
nroff -man <file1> > <out1>
nroff -man <file2> > <out2>
diff -u <out1> <out2>
and for groff, using
"printf '%s\n%s\n' '.kern 0' '.ss 12 0' | groff -man -Z - "
instead of "nroff -man"
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 -z"
export MAN_KEEP_STDERR=yes (or any non-empty value)
-.-.
Output from "mandoc -T lint objdump.1": (possibly shortened list)
mandoc: objdump.1:241:68: STYLE: whitespace at end of input line
mandoc: objdump.1:531:98: STYLE: input text line longer than 80 bytes: will be
overridden i...
mandoc: objdump.1:545:98: STYLE: input text line longer than 80 bytes: will see
\f(CW\*(C`r...
mandoc: objdump.1:618:84: STYLE: input text line longer than 80 bytes: Print
HWR (hardware ...
mandoc: objdump.1:911:65: STYLE: whitespace at end of input line
mandoc: objdump.1:1300:2: WARNING: empty block: RS
-.-.
Remove space characters at the end of lines.
Use "git apply ... --whitespace=fix" to fix extra space issues, or use
global configuration "core.whitespace".
241:input file. This option only disassembles those sections which are
911:output from this option can also be restricted by the use of the
-.-.
Change (or include a "FIXME" paragraph about) misused SI (metric)
numeric prefixes (or names) to the binary ones, like Ki (kibi), Mi
(mebi), Gi (gibi), or Ti (tebi), if indicated.
If the metric prefixes are correct, add the definitions or an
explanation to avoid misunderstanding.
801:the \fB=extended\-color\fR argument will add color using 8bit
-.-.
Mark a full stop (.) and the exclamation mark (!) with "\&",
if it does not mean an end of a sentence.
This is a preventive action,
the paragraph could be reshaped, e.g., after changes.
When typing, one does not always notice when the line wraps after the
period.
There are too many examples of input lines in manual pages,
that end with an abbreviation point.
This marking is robust, and independent of the position on the line.
It corresponds to "\ " in TeX, and to "@:" in Texinfo.
136:\&\fIobjfile\fR... are the object files to be examined. When you
-.-.
Strings longer than 3/4 of a standard line length (80)
94
\fB\-\-dwarf\fR[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames\-interp,=str,=str\-offsets,=loc,=Ranges,=pubtypes,=trace_info,=trace_abbrev,=trace_aranges,=gdb_index,=addr,=cu_index,=links]]
143
\&\fB\-a,\-d,\-D,\-e,\-f,\-g,\-G,\-h,\-H,\-p,\-P,\-r,\-R,\-s,\-S,\-t,\-T,\-V,\-x\fR
must be given.
814 .IP \fB\-\-disassembler\-color=extened|extended\-color|extened\-colour\fR 4
836 .IP
\fB\-\-dwarf[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames\-interp,=str,=str\-offsets,=loc,=Ranges,=pubtypes,=trace_info,=trace_abbrev,=trace_aranges,=gdb_index,=addr,=cu_index,=links,=follow\-links]\fR
4
837 .IX Item
"--dwarf[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=str-offsets,=loc,=Ranges,=pubtypes,=trace_info,=trace_abbrev,=trace_aranges,=gdb_index,=addr,=cu_index,=links,=follow-links]"
1327 .IP \fB\-\-unicode=\fR\fI[default|invalid|locale|escape|hex|highlight]\fR 4
-.-.
Wrong distance between sentences.
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.
190:mangling styles. The optional demangling style argument can be used to
782:absolute paths. It has no effect without \fB\-\-prefix=\fR\fIprefix\fR.
-.-.
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.
objdump.1: line 94 length 229
\fB\-\-dwarf\fR[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames\-interp,=str,=str\-offsets,=loc,=Ranges,=pubtypes,=trace_info,=trace_abbrev,=trace_aranges,=gdb_index,=addr,=cu_index,=links]]
objdump.1: line 143 length 98
\&\fB\-a,\-d,\-D,\-e,\-f,\-g,\-G,\-h,\-H,\-p,\-P,\-r,\-R,\-s,\-S,\-t,\-T,\-V,\-x\fR
must be given.
objdump.1: line 531 length 98
will be overridden if \f(CW\*(C`x86\-64\*(C'\fR, \f(CW\*(C`i386\*(C'\fR or
\f(CW\*(C`i8086\*(C'\fR
objdump.1: line 545 length 98
will see \f(CW\*(C`rlwinm\*(C'\fR rather than \f(CW\*(C`clrlwi\*(C'\fR, and
\f(CW\*(C`addi\*(C'\fR
objdump.1: line 618 length 84
Print HWR (hardware register, used by the \f(CW\*(C`rdhwr\*(C'\fR instruction)
names
objdump.1: line 836 length 240
.IP
\fB\-\-dwarf[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames\-interp,=str,=str\-offsets,=loc,=Ranges,=pubtypes,=trace_info,=trace_abbrev,=trace_aranges,=gdb_index,=addr,=cu_index,=links,=follow\-links]\fR
4
objdump.1: line 837 length 234
.IX Item
"--dwarf[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=str-offsets,=loc,=Ranges,=pubtypes,=trace_info,=trace_abbrev,=trace_aranges,=gdb_index,=addr,=cu_index,=links,=follow-links]"
-.-.
Add a zero (0) in front of a decimal fraction that begins with a period
(.)
7:.if t .sp .5v
-.-.
Use the name of units in text; use symbols in tables and
calculations.
The rule is to have a (no-break, \~) space between a number and
its units (see "www.bipm.org/en/publications/si-brochure")
man-pages(7) says to use a hyphen for '[0-9]bit', that is '[0-9]-bit'.
801:the \fB=extended\-color\fR argument will add color using 8bit
-.-.
Output from "test-groff -b -mandoc -dAD=l -rF0 -rHY=0 -t -w w -z -K utf8":
troff: backtrace: file '<stdin>':94
troff:<stdin>:94: warning: [page 1, 5.9i]: cannot break line
troff: backtrace: file '<stdin>':241
troff:<stdin>:241: warning: trailing space in the line
troff: backtrace: '/home/bg/git/groff/build/s-tmac/an.tmac':613: macro 'IP'
troff: backtrace: file '<stdin>':836
troff:<stdin>:836: warning: [page 8, 5.9i (diversion 'an*paragraph-tag',
0.0i)]: cannot break line
troff: backtrace: file '<stdin>':911
troff:<stdin>:911: warning: trailing space in the line
-- System Information:
Debian Release: trixie/sid
APT prefers testing-proposed-updates
APT policy: (500, 'testing-proposed-updates'), (500, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.7.12-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)
-- no debconf information
