Bug#1071649: mflua.1: some remarks and editorial changes for this man page
Package: texlive-binaries
Version: 2023.20230311.66589-9+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 mflua.1": (possibly shortened list)
mandoc: mflua.1:4:145: STYLE: input text line longer than 80 bytes: mflua, mflua-nowin, ...
-.-.
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.
7:[\fI\,OPTION\/\fR]... [\fI\,MFNAME\/\fR[\fI\,.mf\/\fR]] [\fI\,COMMANDS\/\fR]
10:[\fI\,OPTION\/\fR]... \fI\,\FIRST-LINE\/\fR
13:[\fI\,OPTION\/\fR]... \fI\,&BASE ARGS\/\fR
28:next word is taken as the BASE to read, overriding all else. Any
69:Copyright 2020 L. Scarso.
78:Primary author of MFLua: L. Scarso.
-.-.
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.
mflua.1: line 2 length 83
.TH MFLUA "1" "September 2020" "MFLua Metafont integrated with Lua" "User Commands"
mflua.1: line 4 length 145
mflua, mflua-nowin, mfluajit, mfluajit-nowin \- implementation of META-FONT with Lua embedded for better extraction of information from METAFONT.
mflua.1: line 33 length 81
\fB\-base\fR=\fI\,BASENAME\/\fR use BASENAME instead of program name or a %& line
mflua.1: line 39 length 95
\fB\-ini\fR be inimf, for dumping bases; this is implicitly true if the program name is `inimf'
mflua.1: line 41 length 113
\fB\-interaction\fR=\fI\,STRING\/\fR set interaction mode (STRING=batchmode/nonstopmode/scrollmode/errorstopmode)
mflua.1: line 45 length 108
\fB\-kpathsea\-debug\fR=\fI\,NUMBER\/\fR set path searching debugging flags according to the bits of NUMBER
mflua.1: line 49 length 93
\fB\-output\-directory\fR=\fI\,DIR\/\fR use existing DIR as the directory to write files in
mflua.1: line 51 length 83
\fB[\-no]\-parse\-first\-line\fR disable/enable parsing of first line of input file
-.-.
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).
20:If the first line of MFNAME is %&BASE, and BASE is an existing .base file,
-.-.
Start a sentence in parenthesis on a new line.
mflua.1:40:\fB\-interaction\fR=\fI\,STRING\/\fR set interaction mode (STRING=batchmode/nonstopmode/scrollmode/errorstopmode)
-.-.
Output from "test-groff -b -mandoc -dAD=l -rF0 -rHY=0 -t -w w -z -K utf8":
troff: backtrace: file '<stdin>':10
troff:<stdin>:10: error: no font family named 'I' exists
-- 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 texlive-binaries depends on:
ii libc6 2.38-11
ii libcairo2 1.18.0-3+b1
ii libfontconfig1 2.15.0-1.1
ii libfreetype6 2.13.2+dfsg-1+b4
ii libgcc-s1 14-20240330-1
ii libgraphite2-3 1.3.14-2
ii libharfbuzz0b 8.3.0-2+b1
ii libicu72 72.1-4+b1
ii libkpathsea6 2023.20230311.66589-9+b2
ii libmpfr6 4.2.1-1+b1
ii libpaper1 1.1.29+b1
ii libpixman-1-0 0.42.2-1+b1
ii libpng16-16t64 1.6.43-5
ii libpotrace0 1.16-2+b1
ii libptexenc1 2023.20230311.66589-9+b2
ii libstdc++6 14-20240330-1
ii libsynctex2 2023.20230311.66589-9+b2
ii libteckit0 2.5.12+ds1-1
ii libtexlua53-5 2023.20230311.66589-9+b2
ii libx11-6 2:1.8.7-1+b1
ii libxaw7 2:1.0.14-1+b2
ii libxi6 2:1.8.1-1
ii libxmu6 2:1.1.3-3+b2
ii libxpm4 1:3.5.17-1+b1
ii libxt6t64 1:1.2.1-1.2
ii libzzip-0-13t64 0.13.72+dfsg.1-1.2+b1
ii perl 5.38.2-4
ii t1utils 1.41-4
ii tex-common 6.18
ii zlib1g 1:1.3.dfsg+really1.3.1-1
Versions of packages texlive-binaries recommends:
pn dvisvgm <none>
ii texlive-base 2023.20240207-1
Versions of packages texlive-binaries suggests:
pn hintview <none>
pn texlive-binaries-sse2 <none>
Versions of packages tex-common depends on:
ii ucf 3.0043+nmu1
Versions of packages tex-common suggests:
pn debhelper <none>
Versions of packages texlive-binaries is related to:
ii tex-common 6.18
ii texlive-base 2023.20240207-1
-- no debconf information
--- mflua.1 2024-05-22 22:26:15.405530462 +0000
+++ mflua.1.new 2024-05-22 22:56:38.292768391 +0000
@@ -1,18 +1,20 @@
.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.47.16.
-.TH MFLUA "1" "September 2020" "MFLua Metafont integrated with Lua" "User Commands"
+.TH MFLUA "1" "September 2020" "MFLua Metafont integrated with Lua" "User \
+Commands"
.SH NAME
-mflua, mflua-nowin, mfluajit, mfluajit-nowin \- implementation of META-FONT with Lua embedded for better extraction of information from METAFONT.
+mflua, mflua-nowin, mfluajit, mfluajit-nowin \- implementation of META-FONT \
+with Lua embedded for better extraction of information from METAFONT.
.SH SYNOPSIS
.B mflua
-[\fI\,OPTION\/\fR]... [\fI\,MFNAME\/\fR[\fI\,.mf\/\fR]] [\fI\,COMMANDS\/\fR]
+[\fI\,OPTION\/\fR]...\& [\fI\,MFNAME\/\fR[\fI\,.mf\/\fR]] [\fI\,COMMANDS\/\fR]
.br
.B mflua
-[\fI\,OPTION\/\fR]... \fI\,\FIRST-LINE\/\fR
+[\fI\,OPTION\/\fR]...\& \fI\,FIRST-LINE\/\fR
.br
.B mflua
-[\fI\,OPTION\/\fR]... \fI\,&BASE ARGS\/\fR
+[\fI\,OPTION\/\fR]...\& \fI\,&BASE ARGS\/\fR
.SH DESCRIPTION
-.IP
+.\".IP
Run MFLua on MFNAME, usually creating MFNAME.tfm and MFNAME.NNNNgf,
where NNNN is the resolution of the specified mode (2602 by default).
Any following COMMANDS are processed as Metafont input,
@@ -20,35 +22,41 @@ after MFNAME is read.
If the first line of MFNAME is %&BASE, and BASE is an existing .base file,
use it. Else use `NAME.base', where NAME is the program invocation name,
most commonly `mf'.
-.IP
+.LP
Alternatively, if the first non\-option argument begins with a backslash,
interpret all non\-option arguments as a line of Metafont input.
-.IP
+.LP
Alternatively, if the first non\-option argument begins with a &, the
-next word is taken as the BASE to read, overriding all else. Any
-remaining arguments are processed as above.
-.IP
+next word is taken as the BASE to read, overriding all else.
+Any remaining arguments are processed as above.
+.LP
If no arguments or options are specified, prompt for input.
-.PP
-\fB\-base\fR=\fI\,BASENAME\/\fR use BASENAME instead of program name or a %& line
+.SH OPTIONS
+\fB\-base\fR=\fI\,BASENAME\/\fR use BASENAME instead of program name or a %&
+line
.PP
\fB[\-no]\-file\-line\-error\fR disable/enable file:line:error style messages
.PP
\fB\-halt\-on\-error\fR stop processing at the first error
.PP
-\fB\-ini\fR be inimf, for dumping bases; this is implicitly true if the program name is `inimf'
+\fB\-ini\fR be inimf, for dumping bases; this is implicitly true if the
+program name is `inimf'
.PP
-\fB\-interaction\fR=\fI\,STRING\/\fR set interaction mode (STRING=batchmode/nonstopmode/scrollmode/errorstopmode)
+\fB\-interaction\fR=\fI\,STRING\/\fR set interaction mode
+(STRING=batchmode/nonstopmode/scrollmode/errorstopmode)
.PP
\fB\-jobname\fR=\fI\,STRING\/\fR set the job name to STRING
.PP
-\fB\-kpathsea\-debug\fR=\fI\,NUMBER\/\fR set path searching debugging flags according to the bits of NUMBER
+\fB\-kpathsea\-debug\fR=\fI\,NUMBER\/\fR set path searching debugging flags
+according to the bits of NUMBER
.PP
\fB[\-no]\-mktex\fR=\fI\,FMT\fR disable/enable mktexFMT generation (FMT=mflua)
.PP
-\fB\-output\-directory\fR=\fI\,DIR\/\fR use existing DIR as the directory to write files in
+\fB\-output\-directory\fR=\fI\,DIR\/\fR use existing DIR as the directory
+to write files in
.PP
-\fB[\-no]\-parse\-first\-line\fR disable/enable parsing of first line of input file
+\fB[\-no]\-parse\-first\-line\fR disable/enable parsing of first line of
+input file
.PP
\fB\-progname\fR=\fI\,STRING\/\fR set program (and base) name to STRING
.PP
@@ -66,7 +74,7 @@ Email bug reports to luigi.scarso@gmail.
.PP
kpathsea version 6.3.2
.br
-Copyright 2020 L. Scarso.
+Copyright 2020 L.\& Scarso.
.br
There is NO warranty. Redistribution of this software is
covered by the terms of both the MFLua copyright and
@@ -75,4 +83,4 @@ the Lesser GNU General Public License.
For more information about these matters, see the file
named COPYING and the MFLua source.
.br
-Primary author of MFLua: L. Scarso.
+Primary author of MFLua: L.\& Scarso.
Reply to: