Bug#1071598: hunspell.1: some remarks and editorial changes for this man page
Package: hunspell
Version: 1.7.2+really1.7.2-10+b2
Severity: minor
Tags: patch
Dear Maintainer,
here are some notes and editorial fixes for the manual.
The patch is in the attachment.
-.-
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 hunspell.1": (possibly shortened list)
mandoc: hunspell.1:2:2: ERROR: skipping unknown macro: .LO 1
mandoc: hunspell.1:6:211: STYLE: input text line longer than 80 bytes: hunspell [\-1aDGHhLl...
mandoc: hunspell.1:11:70: STYLE: whitespace at end of input line
mandoc: hunspell.1:32:82: STYLE: input text line longer than 80 bytes: will display each wo...
mandoc: hunspell.1:89:58: STYLE: whitespace at end of input line
mandoc: hunspell.1:235:2: STYLE: fill mode already enabled, skipping: fi
mandoc: hunspell.1:269:13: STYLE: whitespace at end of input line
mandoc: hunspell.1:271:13: STYLE: whitespace at end of input line
mandoc: hunspell.1:274:62: STYLE: whitespace at end of input line
mandoc: hunspell.1:378:2: WARNING: line scope broken: SH breaks TP
mandoc: hunspell.1:382:11: STYLE: whitespace at end of input line
mandoc: hunspell.1:383:9: STYLE: whitespace at end of input line
mandoc: hunspell.1:389:14: STYLE: whitespace at end of input line
mandoc: hunspell.1:409:90: STYLE: input text line longer than 80 bytes: Author of Hunspell e...
-.-.
Remove space characters at the end of lines.
Use "git apply ... --whitespace=fix" to fix extra space issues, or use
global configuration "core.whitespace".
11:program. The most common usage is "hunspell" or "hunspell filename".
89:then the line contains a '+', a space, and the root word.
269:.PP
271:.PP
274:En_geo, en_med, de_med are special dictionaries: dictionaries
382:Similar to
383:.I \-d.
389:Equivalent to
-.-.
Use the correct macro for the font change of a single argument or
split the argument into two.
330:.BR $HOME/.hunspell_dicname
397:.BI /usr/share/myspell/default.aff
400:.BI /usr/share/myspell/default.dic
-.-.
Use the word (in)valid instead of (il)legal,
if not related to legal matters.
See "www.gnu.org/prep/standards".
Think about translations into other languages!
hunspell.1:105:word unless such capitalization is illegal;
-.-.
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.
18:$ hunspell -d en_US
25:Correct words signed with an '*', '+' or '-', unrecognized
146:without -a, too).
374:.B hunspell -p unrecognized_but_good *.odt
-.-.
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.
41:suggested words. Commands are single characters as follows
275:without affix file. Special dictionaries are optional extension
277:terms. There is no naming convention for special dictionaries,
280:order of the parameter list needs for good suggestions). First
304:morphological analysis). Without dictionary morphological data,
320:The default dictionary depends on the locale settings. The
322:LC_MESSAGES, and LANG. If none are set then the default personal
337:stemming). It depends from the dictionary data.
392:The default dictionary depends on the locale settings. The
394:LC_MESSAGES, and LANG. If none are set then the following
398:Path of default affix file. See hunspell(5).
409:Author of Hunspell executable is László Németh. For Hunspell library,
412:This manual based on Ispell's manual. See ispell(1).
-.-.
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.
hunspell.1: line 6 length 211
hunspell [\-1aDGHhLlmnOrstvwX] [\-\-check\-url] [\-\-check\-apostrophe] [\-d dict[,dict2,...]] [\-\-help] [\-i enc] [\-p dict] [\-vv] [\-\-version] [text/OpenDocument/TeX/LaTeX/HTML/SGML/XML/nroff/troff file(s)]
hunspell.1: line 32 length 82
will display each word of the files which does not appear in the dictionary at the
-.-.
Split a punctuation mark from a single argument for a two-font macro
404:.BI $HOME/.hunspell_default.
-.-.
Test nr. 42:
The name of a man page is typeset in bold and the section in roman
(see man-pages(7)).
258:(see WORDCHARS, ICONV and OCONV in hunspell(5)).
303:Analyze the words of the input text (see also hunspell(5) about
336:Stem the words of the input text (see also hunspell(5) about
346:Print ispell(1) compatible version number.
398:Path of default affix file. See hunspell(5).
402:See hunspell(5).
410:see hunspell(3).
412:This manual based on Ispell's manual. See ispell(1).
-.-.
The section part for a manual page is set in roman font.
407:.B hunspell (3), hunspell(5)
-.-.
Split a punctuation from a single argument, if a two-font macro is meant
390:.I \-p.
-.-.
Name of a manual is set in bold, the section in roman.
See man-pages(7).
407:.B hunspell (3), hunspell(5)
-.-.
SYNOPSIS: put a space on both sides of "[" and "]" to increase
readability (?)
hunspell.1:hunspell [\-1aDGHhLlmnOrstvwX] [\-\-check\-url] [\-\-check\-apostrophe] [\-d dict[,dict2,...]] [\-\-help] [\-i enc] [\-p dict] [\-vv] [\-\-version] [text/OpenDocument/TeX/LaTeX/HTML/SGML/XML/nroff/troff file(s)]
-.-.
Output from "test-groff -b -mandoc -dAD=l -rF0 -rHY=0 -t -w w -z -rCHECKSTYLE=0":
<stdin>:2: Content of macro 'LO' is 1
troff: backtrace: file '<stdin>':11
troff:<stdin>:11: warning: trailing space in the line
troff: backtrace: file '<stdin>':89
troff:<stdin>:89: warning: trailing space in the line
troff: backtrace: file '<stdin>':274
troff:<stdin>:274: warning: trailing space in the line
troff: backtrace: file '<stdin>':382
troff:<stdin>:382: warning: trailing space in the line
troff: backtrace: file '<stdin>':389
troff:<stdin>:389: 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 hunspell depends on:
ii hunspell-de-de [hunspell-dictionary] 20161207-12
ii hunspell-en-us [hunspell-dictionary] 1:2020.12.07-2
ii hunspell-is [hunspell-dictionary] 1:24.2.2-1
ii libc6 2.38-11
ii libgcc-s1 14-20240330-1
ii libhunspell-1.7-0 1.7.2+really1.7.2-10+b2
ii libncursesw6 6.5-2
ii libreadline8t64 8.2-4
ii libstdc++6 14-20240330-1
ii libtinfo6 6.5-2
hunspell recommends no packages.
Versions of packages hunspell suggests:
ii unzip 6.0-28
-- no debconf information
--- hunspell.1 2024-05-21 20:40:17.740815430 +0000
+++ hunspell.1.new 2024-05-21 22:28:54.078140568 +0000
@@ -1,44 +1,47 @@
.TH hunspell 1 "2014-05-27"
-.LO 1
+.\".LO 1 Not defined
.SH NAME
hunspell \- spell checker, stemmer and morphological analyzer
.SH SYNOPSIS
-hunspell [\-1aDGHhLlmnOrstvwX] [\-\-check\-url] [\-\-check\-apostrophe] [\-d dict[,dict2,...]] [\-\-help] [\-i enc] [\-p dict] [\-vv] [\-\-version] [text/OpenDocument/TeX/LaTeX/HTML/SGML/XML/nroff/troff file(s)]
+hunspell [\-1aDGHhLlmnOrstvwX] [\-\-check\-url] [\-\-check\-apostrophe] [\-d \
+dict[,dict2,...\&]] [\-\-help] [\-i enc] [\-p dict] [\-vv] [\-\-version] \
+[text/OpenDocument/TeX/LaTeX/HTML/SGML/XML/nroff/troff file(s)]
.SH DESCRIPTION
.I Hunspell
is fashioned after the
.I Ispell
-program. The most common usage is "hunspell" or "hunspell filename".
+program. The most common usage is "hunspell" or "hunspell filename".
Without filename parameter, hunspell checks the standard input.
Typing "cat" and "exsample" in two input lines, results an asterisk
(it means "cat" is a correct word) and a line with corrections:
.PP
.RS
.nf
-$ hunspell -d en_US
+$ hunspell \-d en_US
Hunspell 1.2.3
*
& exsample 4 0: example, examples, ex sample, ex-sample
.fi
.RE
.PP
-Correct words signed with an '*', '+' or '-', unrecognized
+Correct words signed with an '*', '+' or '\-', unrecognized
words signed with '#' or '&' in output lines (see later).
(Close the standard input with Ctrl-d on Unix/Linux and
Ctrl-Z Enter or Ctrl-C on Windows.)
.PP
With filename parameters,
.I hunspell
-will display each word of the files which does not appear in the dictionary at the
-top of the screen and allow you to change it. If there are "near
-misses" in the dictionary, then they are
-also displayed on following lines.
+will display each word of the files which does not appear in the dictionary
+at the top of the screen and allow you to change it.
+If there are "near misses" in the dictionary,
+then they are also displayed on following lines.
Finally, the line containing the
word and the previous line
are printed at the bottom of the screen. If your terminal can
display in reverse video, the word itself is highlighted. You have the
option of replacing the word completely, or choosing one of the
-suggested words. Commands are single characters as follows
+suggested words.
+Commands are single characters as follows
(case is ignored):
.PP
.RS
@@ -86,7 +89,7 @@ a single line is written to the standard
checked for spelling on the line. If the word
was found in the main dictionary, or your personal dictionary, then the
line contains only a '*'. If the word was found through affix removal,
-then the line contains a '+', a space, and the root word.
+then the line contains a '+', a space, and the root word.
If the word was found through compound formation (concatenation of two
words, then the line contains only a '\-'.
.IP ""
@@ -102,7 +105,7 @@ misses separated by
commas and spaces.
.IP ""
Also, each near miss or guess is capitalized the same as the input
-word unless such capitalization is illegal;
+word unless such capitalization is invalid;
in the latter case each near miss is capitalized correctly
according to the dictionary.
.IP ""
@@ -131,7 +134,7 @@ These output lines can be summarized as
.IP ""
For example, a dummy dictionary containing the words "fray", "Frey",
"fry", and "refried" might produce the following response to the
-command "echo 'frqy refries | hunspell \-a":
+command "echo frqy refries | hunspell \-a":
.RS
.nf
(#) Hunspell 0.4.1 (beta), 2005-05-26
@@ -143,7 +146,7 @@ command "echo 'frqy refries | hunspell \
This mode
is also suitable for interactive use when you want to figure out the
spelling of a single word (but this is the default behavior of hunspell
-without -a, too).
+without \-a, too).
.IP ""
When in the
.B \-a
@@ -210,7 +213,7 @@ with an uparrow to protect themselves ag
.IR hunspell .
.IP ""
To summarize these:
-.IP ""
+.\".IP ""
.RS
.IP *
Add to personal dictionary
@@ -232,7 +235,6 @@ Exit terse mode
Enter verbose-correction mode
.IP ^
Spell-check rest of line
-.fi
.RE
.IP ""
In
@@ -255,7 +257,8 @@ interaction for some programs.
.IP \fB\-\-check\-apostrophe\fR
Check and force Unicode apostrophes (U+2019), if one of the ASCII or Unicode
apostrophes is specified by the spelling dictionary, as a word character
-(see WORDCHARS, ICONV and OCONV in hunspell(5)).
+(see WORDCHARS, ICONV and OCONV in
+.BR hunspell (5)).
.IP \fB\-\-check\-url\fR
Check URLs, e-mail addresses and directory paths.
@@ -266,19 +269,21 @@ search path and the available dictionari
.IP \fB\-d\ dict,dict2,...\fR
Set dictionaries by their base names with or without paths.
Example of the syntax:
-.PP
+.PP
\-d en_US,en_geo,en_med,de_DE,de_med
-.PP
+.PP
en_US and de_DE are base dictionaries, they consist of
aff and dic file pairs: en_US.aff, en_US.dic and de_DE.aff, de_DE.dic.
-En_geo, en_med, de_med are special dictionaries: dictionaries
-without affix file. Special dictionaries are optional extension
-of the base dictionaries usually with special (medical, law etc.)
-terms. There is no naming convention for special dictionaries,
+En_geo, en_med, de_med are special dictionaries: dictionaries
+without affix file.
+Special dictionaries are optional extension
+of the base dictionaries usually with special (medical, law etc.\&)
+terms.
+There is no naming convention for special dictionaries,
only the ".dic" extension: dictionaries without affix file will
be an extension of the preceding base dictionary (right
-order of the parameter list needs for good suggestions). First
-item of \-d parameter list must be a base dictionary.
+order of the parameter list needs for good suggestions).
+First item of \-d parameter list must be a base dictionary.
.IP \fB\-G\fR
Print only correct words or lines.
@@ -300,8 +305,10 @@ The "list" option
is used to produce a list of misspelled words from the standard input.
.IP \fB\-m\fR
-Analyze the words of the input text (see also hunspell(5) about
-morphological analysis). Without dictionary morphological data,
+Analyze the words of the input text (see also
+.BR hunspell (5)
+about morphological analysis).
+Without dictionary morphological data,
signs the flags of the affixes of the word forms for dictionary
developers.
@@ -317,24 +324,27 @@ Set password for encrypted dictionaries.
.IP \fB\-p\ dict\fR
Set path of personal dictionary.
-The default dictionary depends on the locale settings. The
-following environment variables are searched: LC_ALL,
-LC_MESSAGES, and LANG. If none are set then the default personal
-dictionary is $HOME/.hunspell_default.
+The default dictionary depends on the locale settings.
+The following environment variables are searched: LC_ALL,
+LC_MESSAGES, and LANG.
+If none are set then the default personal dictionary is
+$HOME/.hunspell_default.
Setting
.I \-d
or the
.I DICTIONARY
environmental variable, personal dictionary will be
-.BR $HOME/.hunspell_dicname
+.B $HOME/.hunspell_dicname
.IP \fB\-r\fR
Warn of the rare words, which are also potential spelling mistakes.
.IP \fB\-s\fR
-Stem the words of the input text (see also hunspell(5) about
-stemming). It depends from the dictionary data.
+Stem the words of the input text (see also
+.BR hunspell (5)
+about stemming).
+It depends from the dictionary data.
.IP \fB\-t\fR
The input file is in TeX or LaTeX format.
@@ -343,7 +353,9 @@ The input file is in TeX or LaTeX format
Print version number.
.IP \fB\-vv\fR
-Print ispell(1) compatible version number.
+Print
+.BR ispell (1)
+compatible version number.
.IP \fB\-w\fR
Print misspelled words (= lines) from one word/line input.
@@ -371,42 +383,47 @@ List bad words of ODF documents
.B hunspell \-l *.odt | sort | uniq >unrecognized
Saving unrecognized words of ODF documents (filtering duplications).
.TP
-.B hunspell -p unrecognized_but_good *.odt
+.B hunspell \-p unrecognized_but_good *.odt
Interactive spell checking of ODF documents, using the previously
saved and reduced word list, as a personal dictionary, to speed up
spell checking.
-.TP
.SH ENVIRONMENT
.TP
.B DICTIONARY
-Similar to
-.I \-d.
+Similar to
+.IR \-d .
.TP
.B DICPATH
Dictionary path.
.TP
.B WORDLIST
-Equivalent to
-.I \-p.
+Equivalent to
+.IR \-p .
.SH FILES
-The default dictionary depends on the locale settings. The
-following environment variables are searched: LC_ALL,
-LC_MESSAGES, and LANG. If none are set then the following
-fallbacks are used:
+The default dictionary depends on the locale settings.
+The following environment variables are searched: LC_ALL, LC_MESSAGES, and
+LANG.
+If none are set then the following fallbacks are used:
-.BI /usr/share/myspell/default.aff
-Path of default affix file. See hunspell(5).
+.B /usr/share/myspell/default.aff
+Path of default affix file.
+See
+.BR hunspell (5).
.PP
-.BI /usr/share/myspell/default.dic
+.B /usr/share/myspell/default.dic
Path of default dictionary file.
-See hunspell(5).
+See
+.BR hunspell (5).
.PP
-.BI $HOME/.hunspell_default.
+.BR $HOME/.hunspell_default .
Default path to personal dictionary.
.SH SEE ALSO
-.B hunspell (3), hunspell(5)
+.BR hunspell "(3), " hunspell (5)
.SH AUTHOR
-Author of Hunspell executable is László Németh. For Hunspell library,
-see hunspell(3).
+Author of Hunspell executable is László Németh.
+For Hunspell library, see
+.BR hunspell (3).
.PP
-This manual based on Ispell's manual. See ispell(1).
+This manual based on Ispell's manual.
+See
+.BR ispell (1).
Reply to: