[DRE-maint] Bug#1072040: rdoc3.1.1: some remarks and editorial changes for this man page
Bjarni Ingi Gislason
bjarniig at simnet.is
Mon May 27 19:42:11 BST 2024
Package: ruby3.1
Version: 3.1.2-8.3
Severity: minor
Tags: patch
Dear Maintainer,
here are some notes and editorial fixes for the manual.
The patch is in the attachment.
-.-
Any program (person), that produces man pages, should check its content for
warnings (defects) by using
groff -mandoc -t -ww -b -z [ -K utf8 | k ] <file>
The same goes for man pages that are used as an input.
For a style guide use
mandoc -T lint
-.-
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 rdoc3.1.1": (possibly shortened list)
mandoc: rdoc3.1.1:4:2: WARNING: skipping paragraph macro: PP after SH
mandoc: rdoc3.1.1:7:2: WARNING: skipping paragraph macro: PP after SH
mandoc: rdoc3.1.1:10:2: WARNING: skipping paragraph macro: PP after SH
mandoc: rdoc3.1.1:25:2: STYLE: fill mode already enabled, skipping: fi
mandoc: rdoc3.1.1:33:2: STYLE: fill mode already enabled, skipping: fi
mandoc: rdoc3.1.1:38:2: STYLE: fill mode already enabled, skipping: fi
mandoc: rdoc3.1.1:43:2: STYLE: fill mode already enabled, skipping: fi
mandoc: rdoc3.1.1:48:2: STYLE: fill mode already enabled, skipping: fi
mandoc: rdoc3.1.1:55:2: STYLE: fill mode already enabled, skipping: fi
mandoc: rdoc3.1.1:61:2: STYLE: fill mode already enabled, skipping: fi
mandoc: rdoc3.1.1:67:2: STYLE: fill mode already enabled, skipping: fi
mandoc: rdoc3.1.1:75:2: STYLE: fill mode already enabled, skipping: fi
mandoc: rdoc3.1.1:80:2: STYLE: fill mode already enabled, skipping: fi
mandoc: rdoc3.1.1:85:2: STYLE: fill mode already enabled, skipping: fi
mandoc: rdoc3.1.1:90:2: STYLE: fill mode already enabled, skipping: fi
mandoc: rdoc3.1.1:96:2: STYLE: fill mode already enabled, skipping: fi
mandoc: rdoc3.1.1:102:2: STYLE: fill mode already enabled, skipping: fi
mandoc: rdoc3.1.1:107:2: STYLE: fill mode already enabled, skipping: fi
mandoc: rdoc3.1.1:112:2: STYLE: fill mode already enabled, skipping: fi
mandoc: rdoc3.1.1:117:2: STYLE: fill mode already enabled, skipping: fi
mandoc: rdoc3.1.1:123:2: STYLE: fill mode already enabled, skipping: fi
mandoc: rdoc3.1.1:128:2: STYLE: fill mode already enabled, skipping: fi
mandoc: rdoc3.1.1:133:2: STYLE: fill mode already enabled, skipping: fi
mandoc: rdoc3.1.1:138:2: STYLE: fill mode already enabled, skipping: fi
mandoc: rdoc3.1.1:145:2: STYLE: fill mode already enabled, skipping: fi
mandoc: rdoc3.1.1:150:2: STYLE: fill mode already enabled, skipping: fi
mandoc: rdoc3.1.1:157:2: STYLE: fill mode already enabled, skipping: fi
mandoc: rdoc3.1.1:164:2: STYLE: fill mode already enabled, skipping: fi
mandoc: rdoc3.1.1:171:2: STYLE: fill mode already enabled, skipping: fi
mandoc: rdoc3.1.1:178:2: STYLE: fill mode already enabled, skipping: fi
mandoc: rdoc3.1.1:183:2: STYLE: fill mode already enabled, skipping: fi
mandoc: rdoc3.1.1:188:2: STYLE: fill mode already enabled, skipping: fi
mandoc: rdoc3.1.1:193:2: STYLE: fill mode already enabled, skipping: fi
mandoc: rdoc3.1.1:198:2: STYLE: fill mode already enabled, skipping: fi
mandoc: rdoc3.1.1:203:2: STYLE: fill mode already enabled, skipping: fi
mandoc: rdoc3.1.1:207:2: ERROR: skipping unknown macro: '%s', the name of the current file will be substituted; if the URL doesn't
-.-.
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.
153:generate output for use by 'ri.' The files are stored in the '.rdoc'
160:generate output for use by 'ri.' The files are stored in a site\-wide
167:generate output for use by 'ri.' The files are stored in a system\-level
-.-.
Find a repeated word
! 115 --> name
-.-.
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.
N.B
The number of lines affected is too large to be in the patch.
12:output is produced. This allows cross references between all files to be
13:resolved. If a name is a directory, it is traversed. If no names are
29:like 'attr_reader' and friends. Option may be repeated. Each accessorname
52:later to use the \-\-diagram option correctly. Dot is available from
58:do not process files or directories matching pattern. Files given
64:treat files ending with .new as if they ended with .old. Using '\-E cgi=rb'
71:reside. Classes shared between more than one file are shown with list of
93:sets output image format for diagrams. Can be png, gif, jpeg, jpg. If this
94:option is omitted, png is used. Requires \-\-diagram.
100::include: requests. Can be used more than once.
136:set the name of the output. Has no effect for HTML.
142:other files, show all stuff for that module/class in each files page. By
169:needed. This option is intended to be used during Ruby installations.
175:instance method name. When displayed, the '#' is removed unless this
206:specify a URL for linking to a web frontend to CVS. If the URL contains a
-.-.
Protect a period (.) or an apostrophe (') with '\&' from becoming a
control character, if it could end up at the start of a line
(by splitting the line into more lines).
29:like 'attr_reader' and friends. Option may be repeated. Each accessorname
30:may have '=text' appended, in which case that text appears where the
64:treat files ending with .new as if they ended with .old. Using '\-E cgi=rb'
153:generate output for use by 'ri.' The files are stored in the '.rdoc'
160:generate output for use by 'ri.' The files are stored in a site\-wide
167:generate output for use by 'ri.' The files are stored in a system\-level
175:instance method name. When displayed, the '#' is removed unless this
208:contain a '%s', the filename will be appended to it.
-.-.
Output from "test-groff -b -mandoc -dAD=l -rF0 -rHY=0 -t -w w -z -K utf8":
troff: backtrace: file '<stdin>':207
troff:<stdin>:207: warning: macro '%s',' not defined
-.-
Th following text in the manual is obsolete
For information on where the output goes, use:
rdoc --help-output
-.-
The link
http://www.research.att.com/sw/tools/graphviz
does not exist any more.
Changed to www.graphviz.org.
-.-
Some doube space reduced to one space.
-- System Information:
Debian Release: trixie/sid
APT prefers testing
APT policy: (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 ruby3.1 depends on:
ii libc6 2.38-11
ii libcrypt1 1:4.4.36-4
ii libgmp10 2:6.3.0+dfsg-2+b1
ii libruby3.1t64 3.1.2-8.3
ii rubygems-integration 1.18
ii zlib1g 1:1.3.dfsg+really1.3.1-1
Versions of packages ruby3.1 recommends:
ii fonts-lato 2.015-1
ii libjs-jquery 3.6.1+dfsg+~3.5.14-1
ruby3.1 suggests no packages.
-- no debconf information
-------------- next part --------------
--- rdoc3.1.1 2024-05-27 01:19:16.220275453 +0000
+++ rdoc3.1.1.new 2024-05-27 18:31:04.274551083 +0000
@@ -4,10 +4,8 @@
.PP
rdoc3.1 \- Generate documentation from Ruby script files
.SH SYNOPSIS
-.PP
-rdoc3.1 [options] [names...]
+rdoc3.1 [options] [names...]
.SH DESCRIPTION
-.PP
Files are parsed, and the information they contain collected, before any
output is produced. This allows cross references between all files to be
resolved. If a name is a directory, it is traversed. If no names are
@@ -22,9 +20,7 @@ For information on where the output goes
.fi
.SH OPTIONS
.TP
-.fi
-.B
-\-\-accessor, \-A accessorname[,..]
+.BR \-\-accessor ", " \-A " \fIaccessorname\fP[,..]
comma separated list of additional class methods that should be treated
like 'attr_reader' and friends. Option may be repeated. Each accessorname
may have '=text' appended, in which case that text appears where the
@@ -37,7 +33,7 @@ include all methods (not just public) in
.TP
.fi
.B
-\-\-charset, \-c charset
+\-\-charset, \-c charset
specifies HTML character\-set
.TP
.fi
@@ -45,26 +41,22 @@ specifies HTML character\-set
\-\-debug, \-D
displays lots on internal stuff
.TP
-.fi
.B
\-\-diagram, \-d
generate diagrams showing modules and classes. You need dot V1.8.6 or
-later to use the \-\-diagram option correctly. Dot is available from
-<URL:http://www.research.att.com/sw/tools/graphviz/>.
+later to use the \-\-diagram option correctly.
+Dot is available from <URL:https://www.graphviz.org>.
.TP
-.fi
.B
-\-\-exclude, \-x pattern
+\-\-exclude, \-x pattern
do not process files or directories matching pattern. Files given
explicitly on the command line will never be excluded.
.TP
-.fi
.B
-\-\-extension, \-E new = old
+\-\-extension, \-E new = old
treat files ending with .new as if they ended with .old. Using '\-E cgi=rb'
will cause xxx.cgi to be parsed as a Ruby file
.TP
-.fi
.B
\-\-fileboxes, \-F
classes are put in boxes which represents files, where these classes
@@ -72,138 +64,118 @@ reside. Classes shared between more than
files that sharing them. Silently discarded if \-\-diagram is not given
Experimental.
.TP
-.fi
.B
-\-\-fmt, \-f formatname
+\-\-fmt, \-f formatname
set the output formatter (see below).
.TP
-.fi
.B
\-\-help, \-h
print usage.
.TP
-.fi
.B
\-\-help\-output, \-O
explain the various output options.
.TP
-.fi
.B
-\-\-image\-format, \-I gif|png|jpg|jpeg
+\-\-image\-format, \-I gif|png|jpg|jpeg
sets output image format for diagrams. Can be png, gif, jpeg, jpg. If this
option is omitted, png is used. Requires \-\-diagram.
.TP
-.fi
.B
-\-\-include, \-i dir[,dir...]
+\-\-include, \-i dir[,dir...]
set (or add to) the list of directories to be searched when satisfying
:include: requests. Can be used more than once.
.TP
-.fi
.B
\-\-inline\-source, \-S
show method source code inline, rather than via a popup link.
.TP
-.fi
.B
\-\-line\-numbers, \-N
include line numbers in the source code
.TP
-.fi
.B
-\-\-main, \-m name
+\-\-main, \-m name
name will be the initial page displayed.
.TP
-.fi
.B
\-\-merge, \-M
-when creating ri output, merge processed classes into previously
-documented classes of the name name.
+when creating 'ri' output, merge processed classes into previously
+documented classes of the name.
.TP
-.fi
.B
\-\-one\-file, \-1
put all the output into a single file.
.TP
-.fi
.B
-\-\-op, \-o dir
+\-\-op, \-o dir
set the output directory.
.TP
-.fi
.B
-\-\-opname, \-n name
+\-\-opname, \-n name
set the name of the output. Has no effect for HTML.
.TP
-.fi
.B
\-\-promiscuous, \-p
When documenting a file that contains a module or class also defined in
other files, show all stuff for that module/class in each files page. By
default, only show stuff defined in that particular file.
.TP
-.fi
.B
\-\-quiet, \-q
don't show progress as we parse.
.TP
-.fi
.B
\-\-ri, \-r
-generate output for use by 'ri.' The files are stored in the '.rdoc'
+generate output for use by 'ri'.
+The files are stored in the '.rdoc'
directory under your home directory unless overridden by a subsequent \-\-op
parameter, so no special privileges are needed.
.TP
-.fi
.B
\-\-ri\-site, \-R
-generate output for use by 'ri.' The files are stored in a site\-wide
-directory, making them accessible to others, so special privileges are
-needed.
+generate output for use by 'ri'.
+The files are stored in a site\-wide directory,
+making them accessible to others, so special privileges are needed.
.TP
-.fi
.B
\-\-ri\-system, \-Y
-generate output for use by 'ri.' The files are stored in a system\-level
-directory, making them accessible to others, so special privileges are
-needed. This option is intended to be used during Ruby installations.
+generate output for use by 'ri.'
+The files are stored in a system\-level directory,
+making them accessible to others,
+so special privileges are needed.
+This option is intended to be used during Ruby installations.
.TP
-.fi
.B
\-\-show\-hash, \-H
a name of the form #name in a comment is a possible hyperlink to an
-instance method name. When displayed, the '#' is removed unless this
-option is specified.
+instance method name.
+When displayed, the '#' is removed unless this option is specified.
.TP
-.fi
.B
-\-\-style, \-s stylesheet\-url
+\-\-style, \-s stylesheet\-url
specifies the URL of a separate stylesheet.
.TP
-.fi
.B
-\-\-tab\-width, \-w n
+\-\-tab\-width, \-w n
set the width of tab characters (default 8).
.TP
-.fi
.B
-\-\-template, \-T template\-name
+\-\-template, \-T template\-name
set the template used when generating output.
.TP
-.fi
.B
-\-\-title, \-t text
+\-\-title, \-t text
set text as the title for the output.
.TP
-.fi
.B
\-\-version, \-v
-display RDoc's version.
+display RDoc's version.
.TP
-.fi
.B
-\-\-webcvs, \-W url
-specify a URL for linking to a web frontend to CVS. If the URL contains a
-'%s', the name of the current file will be substituted; if the URL doesn't
-contain a '%s', the filename will be appended to it.
-
+\-\-webcvs, \-W url
+specify a URL for linking to a web frontend to CVS.
+If the URL contains a \&'%s',
+the name of the current file will be substituted;
+if the URL doesn't contain a '%s',
+the filename will be appended to it.
More information about the Pkg-ruby-extras-maintainers
mailing list