Bug#1071761: pamaltsat.1: some remarks and editorial changes for this man page

Bjarni Ingi Gislason bjarniig at simnet.is
Fri May 24 18:52:26 BST 2024 

Package: netpbm
Version: 2:11.06.01-2
Severity: minor
Tags: patch

Dear Maintainer,

  here are some notes and editorial fixes for the manual.

The patch is in the attachment.

-.-

  A table is not producible.

  The man page is produced from a HTML file.

  The producing command and the HTML file may need to be corrected.

  See the comments at the beginning of the man page.

  The patch and remarks are here to

  1) postprocess the produced man page

  2) check the produced man page in the future after changing the input
file/processing command.

-.-

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 pamaltsat.1": (possibly shortened list)

mandoc: pamaltsat.1:12:2: ERROR: skipping unknown macro: .UN synopsis
mandoc: pamaltsat.1:23:2: WARNING: skipping paragraph macro: PP after SH
mandoc: pamaltsat.1:41:2: WARNING: skipping paragraph macro: PP after SH
mandoc: pamaltsat.1:64:2: WARNING: skipping paragraph macro: PP after SH
mandoc: pamaltsat.1:68:2: WARNING: skipping paragraph macro: PP after SS
mandoc: pamaltsat.1:72:74: STYLE: whitespace at end of input line
mandoc: pamaltsat.1:110:2: WARNING: skipping paragraph macro: PP after SS
mandoc: pamaltsat.1:157:2: WARNING: skipping paragraph macro: PP after SH
mandoc: pamaltsat.1:159:32: STYLE: whitespace at end of input line
mandoc: pamaltsat.1:170:2: ERROR: tbl without any data cells
mandoc: pamaltsat.1:171:11: UNSUPP: unsupported tbl layout modifier: m
mandoc: pamaltsat.1:171:13: ERROR: invalid character in tbl layout: o
mandoc: pamaltsat.1:171:17: ERROR: invalid character in tbl layout: o
mandoc: pamaltsat.1:171:1: ERROR: invalid character in tbl layout: m
mandoc: pamaltsat.1:171:2: ERROR: invalid character in tbl layout: e
mandoc: pamaltsat.1:171:3: ERROR: invalid character in tbl layout: t
mandoc: pamaltsat.1:171:4: ERROR: invalid character in tbl layout: h
mandoc: pamaltsat.1:171:5: ERROR: invalid character in tbl layout: o
mandoc: pamaltsat.1:171:6: ERROR: invalid character in tbl layout: d
mandoc: pamaltsat.1:172:10: UNSUPP: unsupported tbl layout modifier: m
mandoc: pamaltsat.1:172:13: ERROR: invalid character in tbl layout: \
mandoc: pamaltsat.1:172:25: ERROR: unmatched parenthesis in tbl layout
mandoc: pamaltsat.1:172:2: ERROR: invalid character in tbl layout: o
mandoc: pamaltsat.1:172:3: ERROR: invalid character in tbl layout: g
mandoc: pamaltsat.1:172:8: ERROR: invalid character in tbl layout: h
mandoc: pamaltsat.1:173:13: ERROR: invalid character in tbl layout: \
mandoc: pamaltsat.1:173:1: WARNING: tbl line starts with span
mandoc: pamaltsat.1:173:29: ERROR: unmatched parenthesis in tbl layout
mandoc: pamaltsat.1:200:2: WARNING: skipping paragraph macro: PP after SH
mandoc: pamaltsat.1:216:2: WARNING: skipping paragraph macro: PP after SH
mandoc: pamaltsat.1:220:4: STYLE: whitespace at end of input line
mandoc: pamaltsat.1:225:2: WARNING: skipping paragraph macro: PP after SH
mandoc: pamaltsat.1:231:2: WARNING: skipping paragraph macro: PP after SH
mandoc: pamaltsat.1:303:2: WARNING: skipping paragraph macro: PP empty

-.-.

Lines containing '\c'

25:.BR "Netpbm" (1)\c
70:.BR "color integrity" (1)\c
217:.BR "pambrighten" (1)\c
219:.BR "ppmflash" (1)\c

-.-

Remove space characters at the end of lines.

Use "git apply ... --whitespace=fix" to fix extra space issues, or use
global configuration "core.whitespace".

37:  
72:which works with color in terms of intensity ratios, where intensity is a 
107:  
159:(most notably \fB-quiet\fP, see 
184:  
204:  
220:\&, 
233:  

-.-.

Remove space in the first column, if not indented.
Use ".in +<number>n" and ".in" to end it; ".nf" and ".fi" to end
it, for an extra indention.

pamaltsat.1:161: Common Options

-.-.

Move a full stop (period) and a comma outside of a quoted text, if it is
at the end of the quote and does not end a quoted sentence.

146:white.'

-.-.

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.

9:pamaltsat - increase or decrease the saturation of an image using one of
47:     pamaltsat -method log -strength 2.1 test.ppm
56:    pamaltsat -strength 0 test.ppm

-.-.

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.

80:components. In order, however, to make saturation an additive value and to
87:to the power of the \fBstrength\fP value. Since the total intensity of the
182:unity will decrease it. Unity will leave the image unchanged, and zero will
202:the color balance before saturation. You can do this with \fBpamlevels\fP.

-.-.

Test nr. 34:

Use \(en (en-dash) for a dash between space characters,
not a minus (\-) or a hyphen (-), except in the NAME section.

pamaltsat.1:9:pamaltsat - increase or decrease the saturation of an image using one of
pamaltsat.1:132:    sat = orig * strength - Iorig * (strength - 1)

-.-.

chk_man: -.- File temp.table -.-.

Output from "test-groff -b -mandoc -dAD=l -rF0 -rHY=0 -t -w w -z -K utf8":

tbl:<stdin>:171: error: invalid column classifier 'm'
tbl:<stdin>:171: error: giving up on this table region
troff: backtrace: file '<stdin>':72
troff:<stdin>:72: warning: trailing space in the line
troff: backtrace: file '<stdin>':159
troff:<stdin>:159: warning: trailing space in the line
an.tmac:<stdin>:174: warning: tbl preprocessor failed, or it or soelim was not run; table(s) likely not rendered (TE macro called with TW register undefined)
troff: backtrace: file '<stdin>':220
troff:<stdin>:220: 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)

Versions of packages netpbm depends on:
ii  libc6            2.38-11
ii  libjpeg62-turbo  1:2.1.5-3
ii  libnetpbm11t64   2:11.06.01-2
ii  libpng16-16t64   1.6.43-5
ii  libtiff6         4.5.1+git230720-4
ii  libx11-6         2:1.8.7-1+b1
ii  libxml2          2.9.14+dfsg-1.3+b3
ii  zlib1g           1:1.3.dfsg+really1.3.1-1

Versions of packages netpbm recommends:
ii  ghostscript  10.03.1~dfsg~git20240518-1

netpbm suggests no packages.

-- no debconf information

More information about the Pkg-phototools-devel mailing list