Bug#904217: debmake: typos in man page
Hi,
Let me explain how manpage is created.
asciidoc/manpage.txt in debmake-doc is the base text. and is written in
asciidoc.
It is converted to XML and used within debmake-doc.
manpage is generated by a2x --doctype manpage .. (See asciidoc/Makefile.
So the nroff/troff formatting is really not under my control.
On Sat, Jul 21, 2018 at 12:54:21PM -0700, Paul Hardy wrote:
> Package: debmake
> Version: 4.3.0
> Severity: minor
> Tags: patch
>
> Here are patches for the debmake man page. These could also be
> applied to the debmake man page that appears at the end of the "Guide
> for Debian Maintainers" document and to the description of the
> "-x[0-4]" flags in the main body of that guide.
>
> The first change is "program to make the Debian source package" -->
> "program to make a Debian source package"; it can also be changed in
> the Description field in debian/control.
>
> It looks like this man page might have been created from Docbook. If
> so, I do not know how to apply the typographic changes to Docbook
> source, but I will describe them below.
>
> Ellipses (three periods in a row) look better in troff/groff typeset
> output if there is more space between each period than ordinarily
> surrounds a period. In nroff/troff, the traditional way of
> accomplishing this has been to put a "thick space" between the periods
> by typing "\|.\|.\|." instead of "...". I made those changes.
For this, I think use of a UTF-8 ellipses character … may be good idea.
Let me think ...
> There were also instances of "\&.\&.\&.". If what was intended was a
> thin space, that would be "\^" and not "\&". "\&" can do weird things
> with alignment if you don't know how to use it, and it appeared
> throughout the file. The file seems to have been generated by a
> Docbook style sheet, so there might be a bug in whatever style sheet
> was used.
>
> In nroff, if in the middle of a line you temporarily switch to a
> different font style and then switch back to what you were using, it
> is preferable to use the "\fP" markup to return to the previous font
> style ("P" is for "previous", as in the previous font style). For
> example, you can change "\fB-x0\fR" to "\fB-x0\fP". See where I did
> that as I mention in the next paragraph...
Yah but I don't want to manually adjust it.
> The "-x[0-4]" options had ",," (two commas) to represent a quote mark,
> to mean that everything in the preceding line applied. The symbol for
> a quote is locale-dependent though. For example, in the U.S. we would
> use '' instead of ,,. I added "same as \fB-x[0-3]\fP"... to avoid the
> whole quote/locale issue (you can look at the result to see what I
> did.
I am a bit confused here. You mean to read English under the German locale.
For build, let's force C.UTF-8 as locale.
Anyway, I follow rule written in asciidoc/debmake-doc.txt.
> For the "-y" option, where you say doubled option = "force no", does
> that mean "-y -y" will force a "no" response? That was the one part I
> wasn't sure about.
Yes. It's in toggle mode.
> In the CAVEAT section, it says: "You must remove or edit such comment
> lines...". I changed that to "You should remove or edit such comment
> lines..." because I think "must" would imply a policy violation.
> "Should" implies a recommendation. If it truly is a policy violation,
> then I need to remove or edit the comments in my debian/watch files.
> :-)
>
> You might want to change the copyright from "2014-2015" to
> "2014-2018", but I didn't change that in case "2014-2018" is what you
> intended.
>
> I am also attaching the PDFs, so you can see the before and after
> results. I created them with, for example:
>
> groff debmake.1 > debmake.1.ps
> ps2pdf debmake.1.ps
>
> Please let me know if you have any questions or comments.
Anyway, let me check your patch in detail.
Thanks
Osamu
> -debmake \- program to make the Debian source package
> +debmake \- program to make a Debian source package
Yes.
> .SH "SYNOPSIS"
> .SH "DESCRIPTION"
> .sp
> -\fBdebmake\fR helps to build the Debian package from the upstream source\&.
> Normally, this is done as follows:
> +\fBdebmake\fR helps to build a Debian package from the upstream source\&.
> Normally, this is done as follows:
YES.
> -It is untared to create many files under the
> +It is untarred to create many files under the
Yes.
> \fIpackage\-version/\fR
> directory\&.
> .RE
> @@ -72,7 +72,7 @@
> .\}
> debmake is invoked in the
> \fIpackage\-version/\fR
> -directory possibly without any arguments\&.
> +directory, possibly without any arguments\&.
Yes.
> make a native Debian source package without
> -\fB\&.orig\&.tar\&.gz\fR\&. This makes the \(lq\fB3\&.0 (native)\fR\(rq
> format package\&.
> +\fB\&.orig\&.tar\&.gz\fR\&. This makes a \(lq\fB3\&.0 (native)\fR\(rq format
> package\&.
Yes.
> .sp
> -If you are thinking to package a Debian specific source tree with
> -\fBdebian/\fR* in it into a native Debian package, please
Bug#904217: debmake: typos in man page
Package: debmake
Version: 4.3.0
Severity: minor
Tags: patch
Here are patches for the debmake man page. These could also be
applied to the debmake man page that appears at the end of the "Guide
for Debian Maintainers" document and to the description of the
"-x[0-4]" flags in the main body of that guide.
The first change is "program to make the Debian source package" -->
"program to make a Debian source package"; it can also be changed in
the Description field in debian/control.
It looks like this man page might have been created from Docbook. If
so, I do not know how to apply the typographic changes to Docbook
source, but I will describe them below.
Ellipses (three periods in a row) look better in troff/groff typeset
output if there is more space between each period than ordinarily
surrounds a period. In nroff/troff, the traditional way of
accomplishing this has been to put a "thick space" between the periods
by typing "\|.\|.\|." instead of "...". I made those changes.
There were also instances of "\&.\&.\&.". If what was intended was a
thin space, that would be "\^" and not "\&". "\&" can do weird things
with alignment if you don't know how to use it, and it appeared
throughout the file. The file seems to have been generated by a
Docbook style sheet, so there might be a bug in whatever style sheet
was used.
In nroff, if in the middle of a line you temporarily switch to a
different font style and then switch back to what you were using, it
is preferable to use the "\fP" markup to return to the previous font
style ("P" is for "previous", as in the previous font style). For
example, you can change "\fB-x0\fR" to "\fB-x0\fP". See where I did
that as I mention in the next paragraph...
The "-x[0-4]" options had ",," (two commas) to represent a quote mark,
to mean that everything in the preceding line applied. The symbol for
a quote is locale-dependent though. For example, in the U.S. we would
use '' instead of ,,. I added "same as \fB-x[0-3]\fP"... to avoid the
whole quote/locale issue (you can look at the result to see what I
did.
For the "-y" option, where you say doubled option = "force no", does
that mean "-y -y" will force a "no" response? That was the one part I
wasn't sure about.
In the CAVEAT section, it says: "You must remove or edit such comment
lines...". I changed that to "You should remove or edit such comment
lines..." because I think "must" would imply a policy violation.
"Should" implies a recommendation. If it truly is a policy violation,
then I need to remove or edit the comments in my debian/watch files.
:-)
You might want to change the copyright from "2014-2015" to
"2014-2018", but I didn't change that in case "2014-2018" is what you
intended.
I am also attaching the PDFs, so you can see the before and after
results. I created them with, for example:
groff debmake.1 > debmake.1.ps
ps2pdf debmake.1.ps
Please let me know if you have any questions or comments.
Thank you,
Paul Hardy
debmake.1.patch.sig
Description: PGP signature
--- debmake.1 2018-07-10 06:11:11.0 -0700
+++ debmake-new.1 2018-07-21 12:36:59.495053451 -0700
@@ -28,13 +28,13 @@
.\" * MAIN CONTENT STARTS HERE *
.\" -
.SH "NAME"
-debmake \- program to make the Debian source package
+debmake \- program to make a Debian source package
.SH "SYNOPSIS"
.sp
-\fBdebmake\fR [\fB\-h\fR] [\fB\-c\fR | \fB\-k\fR] [\fB\-n\fR | \fB\-a\fR \fIpackage\-version\fR\fB\&.orig\&.tar\&.gz\fR | \fB\-d\fR | \fB\-t\fR ] [\fB\-p\fR \fIpackage\fR] [\fB\-u\fR \fIversion\fR] [\fB\-r\fR \fIrevision\fR] [\fB\-z\fR \fIextension\fR] [\fB\-b\fR "\fIbinarypackage\fR\fI, \&...\fR]" [\fB\-e\fR \fIfoo@example\&.org\fR] [\fB\-f\fR "\fIfirstname lastname\fR"] [\fB\-i\fR "\fIbuildtool\fR" | \fB\-j\fR] [\fB\-l\fR \fIlicense_file\fR] [\fB\-m\fR] [\fB\-o\fR \fIfile\fR] [\fB\-q\fR] [\fB\-s\fR] [\fB\-v\fR] [\fB\-w\fR "\fIaddon, \&...\fR"] [\fB\-x\fR [01234]] [\fB\-y\fR] [\fB\-L\fR] [\fB\-P\fR] [\fB\-T\fR]
+\fBdebmake\fR [\fB\-h\fR] [\fB\-c\fR | \fB\-k\fR] [\fB\-n\fR | \fB\-a\fR \fIpackage\-version\fR\fB\&.orig\&.tar\&.gz\fR | \fB\-d\fR | \fB\-t\fR ] [\fB\-p\fR \fIpackage\fR] [\fB\-u\fR \fIversion\fR] [\fB\-r\fR \fIrevision\fR] [\fB\-z\fR \fIextension\fR] [\fB\-b\fR "\fIbinarypackage\fR\fI, \&\|.\|.\|.\fR]" [\fB\-e\fR \fIfoo@example\&.org\fR] [\fB\-f\fR "\fIfirstname lastname\fR"] [\fB\-i\fR "\fIbuildtool\fR" | \fB\-j\fR] [\fB\-l\fR \fIlicense_file\fR] [\fB\-m\fR] [\fB\-o\fR \fIfile\fR] [\fB\-q\fR] [\fB\-s\fR] [\fB\-v\fR] [\fB\-w\fR "\fIaddon, \&\|.\|.\|.\fR"] [\fB\-x\fR [01234]] [\fB\-y\fR] [\fB\-L\fR] [\fB\-P\fR] [\fB\-T\fR]
.SH "DESCRIPTION"
.sp
-\fBdebmake\fR helps to build the Debian package from the upstream source\&. Normally, this is done as follows:
+\fBdebmake\fR helps to build a Debian package from the upstream source\&. Normally, this is done as follows:
.sp
.RS 4
.ie n \{\
@@ -57,7 +57,7 @@
.sp -1
.IP \(bu 2.3
.\}
-It is untared to create
