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

mandoc: mendex.1:1:2: WARNING: missing date, using "": TH
mandoc: mendex.1:14:2: WARNING: skipping paragraph macro: PP after SH
mandoc: mendex.1:20:2: ERROR: skipping end of block that is not open: RE
mandoc: mendex.1:23:2: ERROR: skipping end of block that is not open: RE
mandoc: mendex.1:26:2: WARNING: skipping paragraph macro: PP empty
mandoc: mendex.1:78:99: STYLE: input text line longer than 80 bytes: (the next odd page t...
mandoc: mendex.1:259:87: STYLE: input text line longer than 80 bytes: Same as \fBlethead_f...
mandoc: mendex.1:350:2: ERROR: skipping end of block that is not open: RE
mandoc: mendex.1:360:2: ERROR: skipping end of block that is not open: RE
mandoc: mendex.1:369:2: ERROR: skipping end of block that is not open: RE
mandoc: mendex.1:434:2: ERROR: skipping end of block that is not open: RE
mandoc: mendex.1:470:2: WARNING: skipping paragraph macro: PP empty
mandoc: mendex.1:472:2: WARNING: skipping paragraph macro: PP after SH
mandoc: mendex.1:476:2: ERROR: skipping end of block that is not open: RE
mandoc: mendex.1:482:2: ERROR: skipping end of block that is not open: RE
mandoc: mendex.1:482:2: WARNING: skipping paragraph macro: br before sp
mandoc: mendex.1:499:87: STYLE: input text line longer than 80 bytes: The delimiter betwee...
mandoc: mendex.1:500:2: ERROR: skipping end of block that is not open: RE
mandoc: mendex.1:515:85: STYLE: input text line longer than 80 bytes: Though some kanji wo...
mandoc: mendex.1:516:146: STYLE: input text line longer than 80 bytes: (ex. \[u300C]\[u3072...
mandoc: mendex.1:518:132: STYLE: input text line longer than 80 bytes: in kana expression (...
mandoc: mendex.1:519:2: ERROR: skipping end of block that is not open: RE
mandoc: mendex.1:521:81: STYLE: input text line longer than 80 bytes: by setting the file ...
mandoc: mendex.1:524:2: WARNING: skipping paragraph macro: PP empty
mandoc: mendex.1:526:2: WARNING: skipping paragraph macro: PP after SH
mandoc: mendex.1:530:2: ERROR: skipping end of block that is not open: RE
mandoc: mendex.1:531:84: STYLE: input text line longer than 80 bytes: Even when sort by ch...
mandoc: mendex.1:533:2: ERROR: skipping end of block that is not open: RE
mandoc: mendex.1:551:2: ERROR: skipping end of block that is not open: RE
mandoc: mendex.1:561:2: WARNING: skipping paragraph macro: PP empty
mandoc: mendex.1:564:2: WARNING: skipping paragraph macro: PP empty
mandoc: mendex.1:577:2: WARNING: skipping paragraph macro: PP empty
mandoc: mendex.1:580:2: WARNING: skipping paragraph macro: PP empty
mandoc: mendex.1:585:2: WARNING: skipping paragraph macro: PP empty

-.-.

Change two HYPHEN-MINUSES (code 0x2D) to an em-dash (\(em),
if one is intended.  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 "-" (end of options) then use "\-\-".

mendex.1:12:\fBmendex\fR [-ilqrcgfEJSU] [\fB-s\fI sty\fR] [\fB-d\fI dic\fR] [\fB-o\fI ind\fR] [\fB-t\fI log\fR] [\fB-p\fI no\fR] [\fB-I\fI enc\fR] [\fB--help\fR] [\fB--\fR] [\fI idx0 idx1 idx2 ...\fR]
mendex.1:97:\fB--help\fR
mendex.1:100:\fB--\fR
mendex.1:101:Arguments after \fB--\fR are not taken as options.
mendex.1:332:"--"

-.-.

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.


42:(e.g. 1\(en5).
515:Though some kanji words (ex. 「表」) may have more than one Yomi\'s
516:(ex. 「ひょう」 and 「おもて」), only one of them can be registered in the dictionary.
518:in kana expression (ex. \\index{ひょう@表} or \\index{おもて@表}) on the input file.

-.-.

Change -- in x--y to \(em (em-dash), or, if an
option, to \-\-

12:\fBmendex\fR [-ilqrcgfEJSU] [\fB-s\fI sty\fR] [\fB-d\fI dic\fR] [\fB-o\fI ind\fR] [\fB-t\fI log\fR] [\fB-p\fI no\fR] [\fB-I\fI enc\fR] [\fB--help\fR] [\fB--\fR] [\fI idx0 idx1 idx2 ...\fR]
97:\fB--help\fR

-.-.

Change - to \- if it shall be printed as a minus sign.

mendex.1:253:\'0\', \'1\' and \'-1\' respectively denotes no output, uppercase and lowercase.

-.-.

Use "\e" to print the escape character instead of "\\" (which gets
interpreted in copy mode).

118:"\\\\indexentry"
188:\'\\\\\'
196:"\\\\begin{theindex}\\n"
202:"\\n\\n\\\\end{theindex}\\n"
208:"\\n  \\\\setcounter{page}{"
214:"}\\n"
220:"\\n\\n  \\\\indexspace\\n"
263:"\\n  \\\\item "
269:"\\n     \\\\subitem "
275:"\\n       \\\\subsubitem "
281:"\\n    \\\\subitem "
287:"\\n    \\\\subitem "
294:"\\n    \\\\subsubitem "
300:"\\n    \\\\subsubitem "
372:"\\\\"
518:in kana expression (ex. \\index{ひょう@表} or \\index{おもて@表}) on the input file.

-.-.

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.

12:\fBmendex\fR [-ilqrcgfEJSU] [\fB-s\fI sty\fR] [\fB-d\fI dic\fR] [\fB-o\fI ind\fR] [\fB-t\fI log\fR] [\fB-p\fI no\fR] [\fB-I\fI enc\fR] [\fB--help\fR] [\fB--\fR] [\fI idx0 idx1 idx2 ...\fR]
97:\fB--help\fR
100:\fB--\fR
101:Arguments after \fB--\fR are not taken as options.
102:This is useful when the input file name starts with '-'.
168:"-"
253:\'0\', \'1\' and \'-1\' respectively denotes no output, uppercase and lowercase.
332:"--"

-.-.

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.

42:(e.g. 1\(en5).
547:which contains both Japanese kana and other scripts (e.g. Latin script).

-.-.

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.

18:which can be formatted. It is almost compatible with \fImakeindex\fR, and
32:Set \'sort by character order\'. By default, \'sort by word order\' is used.
40:Disable implicit page range formation. By default, three or
42:(e.g. 1\(en5).
51:of the \fIgojuon\fR table (Japanese syllabary). By default, all 48 characters
61:Employ \fIdic\fR as the dictionary file. The dictionary file is
65:Employ \fIind\fR as the output index file. By default, the file
70:Employ \fIlog\fR as the transcript file. By default, the file name
76:\fIno\fR. The argument \fIno\fR may be numerical or one of
93:Set internal character encoding to \fIenc\fR. The argument \fIenc\fR
107:output file. The format is upper compatible with the one for
108:\fImakeindex\fR. The style file contains a list of
177:\'R\' and \'r\' correspond to Roman. \'n\' corresponds to arabic numeral.
234:Same as \fBlethead_prefix\fR. (compatible with makeindex)
246:Same as \fBlethead_suffix\fR. (compatible with makeindex)
259:Same as \fBlethead_flag\fR. (Note: makeindex uses a different name \fBheadings_flag\fR)
439:Flag to output of symbol. If \'0\', do not output.
455:Japanese and non-Japanese (ex. Latin scripts).
474:Japanese indexes, compared to \fImakeindex\fR. Users can save the effort
515:Though some kanji words (ex. 「表」) may have more than one Yomi\'s
516:(ex. 「ひょう」 and 「おもて」), only one of them can be registered in the dictionary.
518:in kana expression (ex. \\index{ひょう@表} or \\index{おもて@表}) on the input file.
547:which contains both Japanese kana and other scripts (e.g. Latin script).
583:specified along with the order of page numbers. Otherwise,

-.-.

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.

mendex.1: line 12 length 188
\fBmendex\fR [-ilqrcgfEJSU] [\fB-s\fI sty\fR] [\fB-d\fI dic\fR] [\fB-o\fI ind\fR] [\fB-t\fI log\fR] [\fB-p\fI no\fR] [\fB-I\fI enc\fR] [\fB--help\fR] [\fB--\fR] [\fI idx0 idx1 idx2 ...\fR]

mendex.1: line 78 length 99
(the next odd page to the end of contents), \fIeven\fR (the next even page to the end of contents).

mendex.1: line 259 length 87
Same as \fBlethead_flag\fR. (Note: makeindex uses a different name \fBheadings_flag\fR)

mendex.1: line 465 length 89
\'S\', \'N\', \'E\' and \'J\' respectively denotes symbol, numbers, English and Japanese.

mendex.1: line 499 length 87
The delimiter between the index word and its reading is one or more tab(s) or space(s).

mendex.1: line 516 length 96
(ex. 「ひょう」 and 「おもて」), only one of them can be registered in the dictionary.

mendex.1: line 518 length 92
in kana expression (ex. \\index{ひょう@表} or \\index{おもて@表}) on the input file.

mendex.1: line 521 length 81
by setting the file name at an environment variable \fIINDEXDEFAULTDICTIONARY\fR.

mendex.1: line 531 length 84
Even when sort by character order, the index at output remains the original sequence

-.-.

The name of a man page is typeset in bold and the section in roman
(see man-pages(7)).

587:tex(1), latex(1), makeindex(1)

-.-.


Name of a manual is set in bold, the section in roman.
See man-pages(7).

587:tex(1), latex(1), makeindex(1)

-.-.


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

troff: backtrace: file '<stdin>':489
troff:<stdin>:489: warning: special character 'u304B' not defined
troff: backtrace: file '<stdin>':489
troff:<stdin>:489: warning: special character 'u3075_3099' not defined
troff: backtrace: file '<stdin>':489
troff:<stdin>:489: warning: special character 'u3057' not defined
troff: backtrace: file '<stdin>':489
troff:<stdin>:489: warning: special character 'u304D' not defined
troff: backtrace: file '<stdin>':489
troff:<stdin>:489: warning: special character 'u304B_3099' not defined
troff: backtrace: file '<stdin>':489
troff:<stdin>:489: warning: special character 'u3044' not defined
troff: backtrace: file '<stdin>':489
troff:<stdin>:489: warning: special character 'u3083' not defined
troff: backtrace: file '<stdin>':489
troff:<stdin>:489: warning: special character 'u3075' not defined
troff: backtrace: file '<stdin>':489
troff:<stdin>:489: warning: special character 'u3084' not defined
troff: backtrace: file '<stdin>':491
troff:<stdin>:491: warning: special character 'u30DE' not defined
troff: backtrace: file '<stdin>':491
troff:<stdin>:491: warning: special character 'u30C3' not defined
troff: backtrace: file '<stdin>':491
troff:<stdin>:491: warning: special character 'u30AD' not defined
troff: backtrace: file '<stdin>':491
troff:<stdin>:491: warning: special character 'u30F3' not defined
troff: backtrace: file '<stdin>':491
troff:<stdin>:491: warning: special character 'u30C8' not defined
troff: backtrace: file '<stdin>':491
troff:<stdin>:491: warning: special character 'u30B7' not defined
troff: backtrace: file '<stdin>':491
troff:<stdin>:491: warning: special character 'u30E5' not defined
troff: backtrace: file '<stdin>':491
troff:<stdin>:491: warning: special character 'u307E' not defined
troff: backtrace: file '<stdin>':491
troff:<stdin>:491: warning: special character 'u3064' not defined
troff: backtrace: file '<stdin>':491
troff:<stdin>:491: warning: special character 'u3093' not defined
troff: backtrace: file '<stdin>':491
troff:<stdin>:491: warning: special character 'u3068' not defined
troff: backtrace: file '<stdin>':491
troff:<stdin>:491: warning: special character 'u3086' not defined
troff: backtrace: file '<stdin>':493
troff:<stdin>:493: warning: special character 'u30EF' not defined
troff: backtrace: file '<stdin>':493
troff:<stdin>:493: warning: special character 'u30FC' not defined
troff: backtrace: file '<stdin>':493
troff:<stdin>:493: warning: special character 'u30D5_309A' not defined
troff: backtrace: file '<stdin>':493
troff:<stdin>:493: warning: special character 'u30ED' not defined
troff: backtrace: file '<stdin>':493
troff:<stdin>:493: warning: special character 'u308F' not defined
troff: backtrace: file '<stdin>':493
troff:<stdin>:493: warning: special character 'u3042' not defined
troff: backtrace: file '<stdin>':493
troff:<stdin>:493: warning: special character 'u308D' not defined
troff: backtrace: file '<stdin>':505
troff:<stdin>:505: warning: special character 'u6F22' not defined
troff: backtrace: file '<stdin>':505
troff:<stdin>:505: warning: special character 'u5B57' not defined
troff: backtrace: file '<stdin>':505
troff:<stdin>:505: warning: special character 'u3057_3099' not defined
troff: backtrace: file '<stdin>':507
troff:<stdin>:507: warning: special character 'u8AAD' not defined
troff: backtrace: file '<stdin>':507
troff:<stdin>:507: warning: special character 'u307F' not defined
troff: backtrace: file '<stdin>':507
troff:<stdin>:507: warning: special character 'u3088' not defined
troff: backtrace: file '<stdin>':509
troff:<stdin>:509: warning: special character 'u74B0' not defined
troff: backtrace: file '<stdin>':509
troff:<stdin>:509: warning: special character 'u5883' not defined
troff: backtrace: file '<stdin>':509
troff:<stdin>:509: warning: special character 'u3087' not defined
troff: backtrace: file '<stdin>':509
troff:<stdin>:509: warning: special character 'u3046' not defined
troff: backtrace: file '<stdin>':511
troff:<stdin>:511: warning: special character 'u30A2' not defined
troff: backtrace: file '<stdin>':511
troff:<stdin>:511: warning: special character 'u30EB' not defined
troff: backtrace: file '<stdin>':511
troff:<stdin>:511: warning: special character 'u30D5' not defined
troff: backtrace: file '<stdin>':511
troff:<stdin>:511: warning: special character 'u30A1' not defined
troff: backtrace: file '<stdin>':515
troff:<stdin>:515: warning: special character 'u300C' not defined
troff: backtrace: file '<stdin>':515
troff:<stdin>:515: warning: special character 'u8868' not defined
troff: backtrace: file '<stdin>':515
troff:<stdin>:515: warning: special character 'u300D' not defined
troff: backtrace: file '<stdin>':516
troff:<stdin>:516: warning: special character 'u3072' not defined
troff: backtrace: file '<stdin>':516
troff:<stdin>:516: warning: special character 'u304A' not defined
troff: backtrace: file '<stdin>':516
troff:<stdin>:516: warning: special character 'u3082' not defined
troff: backtrace: file '<stdin>':516
troff:<stdin>:516: warning: special character 'u3066' not defined
troff: backtrace: file '<stdin>':557
troff:<stdin>:557: warning: special character 'u30A4' not defined

an-end-check:<stdin>: Warning: Different number of .RS and .RE calls, an-RS-open=-13 at end of file

Bad use of \s0 in a string definition, the string could be resized.

6:.if t .ds LX \fRL\\h'-0.36m'\\v'-0.15v'\s-2A\s0\\h'-0.15m'\\v'0.15v'\fP\*(TX

On 23.05.2024 00:24, Bjarni Ingi Gislason wrote:

Hello,

Unfortunately the patch not match to the manual page from TL204 [1].
Could you adapt to that version? Thanks!

Hilmar

[1]
https://github.com/debian-tex/texlive-bin/blob/master_tl_2024/texk/mendexk/mendex.1

  The file I get with 'wget2 ...' is a Doc file.

  If I copy it from the page with 'firefox' I get the man page when I use the
'raw' choice.

  I do not get any difference between the Debian 'mendex.1' and the
downloaded from 'firefox' using the 'raw' choice.

What do you get if you use the option '--dry-run' for 'patch' or the
diagnostics from it?

Control: tags -1 - patch

Hello Bjarni,
No, it is not a doc file, but the HTML file representing the web page:

hille@rasppi2:~ $ wget2
https://github.com/debian-tex/texlive-bin/blob/master_tl_2024/texk/mendexk/mendex.1
[0] Downloading
'https://github.com/debian-tex/texlive-bin/blob/master_tl_2024/texk/mendexk/mendex.1'
...
Saving 'mendex.1.1'
HTTP response 200
[https://github.com/debian-tex/texlive-bin/blob/master_tl_2024/texk/mendexk/mendex.1]
hille@rasppi2:~ $ file mendex.1.1
mendex.1.1: HTML document, Unicode text, UTF-8 text, with very long
lines (1616)

When downloading the raw manual page for TL2024 and trying to apply your
patch it does not apply.

hille@rasppi2:~ $ wget2
"https://raw.githubusercontent.com/debian-tex/texlive-bin/master_tl_2024/texk/mendexk/mendex.1"
[0] Downloading
'https://raw.githubusercontent.com/debian-tex/texlive-bin/master_tl_2024/texk/mendexk/mendex.1'
...
Saving 'mendex.1'
HTTP response 200
[https://raw.githubusercontent.com/debian-tex/texlive-bin/master_tl_2024/texk/mendexk/mendex.1]
hille@rasppi2:~ $ wget2 -O mendex.1.diff
"https://bugs.debian.org/cgi-bin/bugreport.cgi?att=1;bug=1071647;filename=mendex.1.diff;msg=5"
[0] Downloading
'https://bugs.debian.org/cgi-bin/bugreport.cgi?att=1;bug=1071647;filename=mendex.1.diff;msg=5'
...
Saving 'mendex.1.diff'
HTTP response 200
[https://bugs.debian.org/cgi-bin/bugreport.cgi?att=1;bug=1071647;filename=mendex.1.diff;msg=5]
hille@rasppi2:~ $ patch < mendex.1.diff
(Stripping trailing CRs from patch; use --binary to disable.)
patching file mendex.1
Hunk #13 FAILED at 459.
Hunk #15 FAILED at 510.
Hunk #16 succeeded at 556 with fuzz 2.
2 out of 17 hunks FAILED -- saving rejects to file mendex.1.rej
See above.

Many thanks for your help! I remove the patch tag for now.

Hilmar