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.000000000 -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 many files under the
+It is untarred to create many files under the
\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\&.
.RE
.sp
.RS 4
@@ -105,7 +105,7 @@
directory to make Debian packages\&.
.RE
.sp
-Make sure to protect the arguments of the \fB\-b\fR, \fB\-f\fR, \fB\-l\fR, and \fB\-w\fR options from the shell interference by quoting them properly\&.
+Make sure to protect the arguments of the \fB\-b\fR, \fB\-f\fR, \fB\-l\fR, and \fB\-w\fR options from shell interference by quoting them properly\&.
.SS "optional arguments:"
.PP
\fB\-h\fR, \fB\-\-help\fR
@@ -189,13 +189,13 @@
\fB\-n\fR, \fB\-\-native\fR
.RS 4
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\&.
.sp
-If you are thinking to package a Debian specific source tree with
-\fBdebian/\fR* in it into a native Debian package, please think otherwise\&. You can use the \(lq\fBdebmake \-d \-i debuild\fR\(rq or \(lq\fBdebmake \-t \-i debuild\fR\(rq commands to make the \(lq\fB3\&.0 (quilt)\fR\(rq format non\-native Debian package\&. The only difference is that the
+If you are thinking of packaging a Debian-specific source tree with
+\fBdebian/\fR* in it into a native Debian package, please think otherwise\&. You can use the \(lq\fBdebmake \-d \-i debuild\fR\(rq or \(lq\fBdebmake \-t \-i debuild\fR\(rq commands to make a \(lq\fB3\&.0 (quilt)\fR\(rq format non\-native Debian package\&. The only difference is that the
\fBdebian/changelog\fR
file must use the non\-native version scheme:
-\fIversion\-revision\fR\&. The non\-native package is more friendly to the downstream distributions\&.
+\fIversion\-revision\fR\&. The non\-native package is more friendly to downstream distributions\&.
.RE
.PP
\fB\-a\fR \fIpackage\-version\fR\fB\&.tar\&.gz\fR, \fB\-\-archive\fR \fIpackage\-version\fR\fB\&.tar\&.gz\fR
@@ -207,7 +207,7 @@
The upstream tarball may be specified as
\fIpackage_version\fR\fB\&.orig\&.tar\&.gz\fR
and
-\fBtar\&.gz\fR
+\fBtar\&.gz\fR,
for all cases may be
\fBtar\&.bz2\fR, or
\fBtar\&.xz\fR\&.
@@ -226,7 +226,7 @@
.sp
The \(lq\fBdebmake \-d\fR\(rq command is designed to run in the
\fIpackage/\fR
-directory hosting the upstream VCS with the build system supporting the \(lq\fBmake dist\fR\(rq command equivalents\&. (automake/autoconf, Python distutils, \&...)
+directory hosting the upstream VCS with the build system supporting the \(lq\fBmake dist\fR\(rq command equivalents\&. (automake/autoconf, Python distutils, \&\|.\|.\|.)
.RE
.PP
\fB\-t\fR, \fB\-\-tar\fR
@@ -245,7 +245,7 @@
\fI0~1403012359\fR, from the UTC date and time\&. The generated tarball excludes the
\fBdebian/\fR
directory found in the upstream VCS\&. (It also excludes typical VCS directories:
-\fB\&.git/ \&.hg/ \&.svn/ \&.CVS/\fR)
+\fB\&.git/ \&.hg/ \&.svn/ \&.CVS/\fR.)
.RE
.PP
\fB\-p\fR \fIpackage\fR, \fB\-\-package\fR \fIpackage\fR
@@ -266,13 +266,13 @@
\fB\-z\fR \fIextension\fR, \fB\-\-targz\fR \fIextension\fR
.RS 4
set the tarball type,
-\fIextension\fR=(\fBtar\&.gz\fR|\fBtar\&.bz2\fR|\fBtar\&.xz\fR) (alias:
+\fIextension\fR=(\fBtar\&.gz\fR|\fBtar\&.bz2\fR|\fBtar\&.xz\fR). (alias:
\fBz\fR,
\fBb\fR,
-\fBx\fR)
+\fBx\fR).
.RE
.PP
-\fB\-b\fR "\fIbinarypackage[:type],\&...\fR", \fB\-\-binaryspec\fR "\fIbinarypackage[:type],\&...\fR"
+\fB\-b\fR "\fIbinarypackage[:type],\&\|.\|.\|.\fR", \fB\-\-binaryspec\fR "\fIbinarypackage[:type],\&\|.\|.\|.\fR"
.RS 4
set the binary package specs by the comma separated list of
\fIbinarypackage:type\fR
@@ -307,7 +307,7 @@
.sp -1
.IP \(bu 2.3
.\}
-\fBdata\fR: Data (fonts, graphics, \&...) package (all, foreign) (alias:
+\fBdata\fR: Data (fonts, graphics, \&\|.\|.\|.) package (all, foreign) (alias:
\fBda\fR)
.RE
.sp
@@ -320,7 +320,7 @@
.IP \(bu 2.3
.\}
\fBdbg\fR: Debug symbol package (any, same) (alias:
-\fBdb\fR) (deprecated for strech and after since the \-dbgsym package is automatically generated)
+\fBdb\fR) (deprecated for stretch and after since the \-dbgsym package is automatically generated)
.RE
.sp
.RS 4
@@ -447,7 +447,7 @@
sets
\fItype\fR
to
-\fBdata\fR, \&...
+\fBdata\fR, \&\|.\|.\|.
.sp
If the source tree contents do not match settings for
\fItype\fR, the
@@ -463,7 +463,7 @@
\fB$DEBEMAIL\fR\&.
.RE
.PP
-\fB\-f\fR "\fIfirstname lastname\fR", \fB\-\-fullname\fR "\fIfirstname lastname\fR"
+\fB\-f\fR "\fIfirstname lastname\fR", \fB\-\-full name\fR "\fIfirstname lastname\fR"
.RS 4
set the fullname\&.
.sp
@@ -475,7 +475,7 @@
.RS 4
invoke "\fIbuildtool\fR" at the end of execution\&.
\fIbuildtool\fR
-may be \(lq\fBdpkg\-buildpackage\fR\(rq, \(lq\fBdebuild\fR\(rq, \(lq\fBpdebuild\fR\(rq, \(lq\fBpdebuild \-\-pbuilder cowbuilder\fR\(rq, etc\&.\&.
+may be \(lq\fBdpkg\-buildpackage\fR\(rq, \(lq\fBdebuild\fR\(rq, \(lq\fBpdebuild\fR\(rq, \(lq\fBpdebuild \-\-pbuilder cowbuilder\fR\(rq, etc\&.
.sp
The default is not to execute any program\&.
.sp
@@ -516,16 +516,16 @@
.RE
.RE
.PP
-\fB\-l\fR "\fIlicense_file,\&...\fR", \fB\-\-license\fR "\fIlicense_file,\&...\fR"
+\fB\-l\fR "\fIlicense_file,\&\|.\|.\|.\fR", \fB\-\-license\fR "\fIlicense_file,\&\|.\|.\|.\fR"
.RS 4
add formatted license text to the end of the
\fBdebian/copyright\fR
-file holding license scan results
+file holding license scan results.
.sp
-The default is add
+The default is to add
\fBCOPYING\fR
and
-\fBLICENSE\fR
+\fBLICENSE\fR,
and
\fIlicense_file\fR
needs to list only the additional file names all separated by \(lq\fB,\fR\(rq\&.
@@ -538,11 +538,11 @@
.PP
\fB\-o\fR \fIfile\fR, \fB\-\-option\fR \fIfile\fR
.RS 4
-read optional parameters from the
+read optional parameters from
\fIfile\fR\&. (This is not for everyday use\&.)
.sp
The
-\fIfile\fR
+\fIfile\fR parameter
is sourced as the Python3 code at the end of
\fBpara\&.py\fR\&. For example, the package description can be specified by the following file\&.
.sp
@@ -555,7 +555,7 @@
program long description which you wish to include\&.
\&.
Empty line is space + \&.
- You keep going on \&.\&.\&.
+ You keep going on \&.\|.\|.
\*(Aq\*(Aq\*(Aq
.fi
.if n \{\
@@ -580,7 +580,7 @@
show version information\&.
.RE
.PP
-\fB\-w\fR "\fIaddon,\&...\fR", \fB\-\-with\fR "\fIaddon,\&...\fR"
+\fB\-w\fR "\fIaddon,\&\|.\|.\|.\fR", \fB\-\-with\fR "\fIaddon,\&\|.\|.\|.\fR"
.RS 4
add extra arguments to the
\fB\-\-with\fR
@@ -598,15 +598,15 @@
\fBautoreconf\fR
as
\fIaddon\fR
-forces to run \(lq\fBautoreconf \-i \-v \-f\fR\(rq for every package building\&. Otherwise,
+forces running \(lq\fBautoreconf \-i \-v \-f\fR\(rq for every package build\&. Otherwise,
\fBautotools\-dev\fR
as
\fIaddon\fR
-is used as default\&.
+is used as the default\&.
.sp
For Autotools based packages, if they install Python programs,
\fBpython2\fR
-as addon is needed for packages with \(lq\fBcompat < 9\fR\(rq since this is non\-obvious\&. But for
+as \fIaddon\fP is needed for packages with \(lq\fBcompat < 9\fR\(rq since this is non\-obvious\&. But for
\fBsetup\&.py\fR
based packages,
\fBpython2\fR
@@ -624,7 +624,7 @@
.sp
The number
\fIn\fR
-changes which configuration templates are generated\&.
+determines which configuration templates are generated\&.
.sp
.RS 4
.ie n \{\
@@ -645,7 +645,7 @@
.sp -1
.IP \(bu 2.3
.\}
-\fB\-x1\fR: ,, + desirable configuration files\&. (default for new packages)
+\fB\-x1\fR: all \fB-x0\fP files + desirable configuration files\&. (default for new packages)
.RE
.sp
.RS 4
@@ -656,7 +656,7 @@
.sp -1
.IP \(bu 2.3
.\}
-\fB\-x2\fR: ,, + interesting configuration files\&. (recommended for experts, multi binary aware)
+\fB\-x2\fR: all \fB-x1\fP files + interesting configuration files\&. (recommended for experts, multi binary aware)
.RE
.sp
.RS 4
@@ -667,9 +667,9 @@
.sp -1
.IP \(bu 2.3
.\}
-\fB\-x3\fR: ,, + unusual configuration template files with the extra
+\fB\-x3\fR: all \fB-x2\fP files + unusual configuration template files with an extra
\fB\&.ex\fR
-suffix to ease their removal\&. (recommended for new users) To use these as configuration files, rename their file names into ones without the
+suffix to ease their removal\&. (recommended for new users) To use these as configuration files, rename their file names to ones without the
\fB\&.ex\fR
suffix\&.
.RE
@@ -682,7 +682,7 @@
.sp -1
.IP \(bu 2.3
.\}
-\fB\-x4\fR: ,, + copyright file examples\&.
+\fB\-x4\fR: all \fB-x3\fP files + copyright file examples\&.
.RE
.RE
.PP
@@ -708,7 +708,7 @@
.RE
.SH "EXAMPLES"
.sp
-For a well behaving source, you can build a good\-for\-local\-use installable single Debian binary package easily with one command\&. Test install of such a package generated in this way offers a good alternative to the traditional \(lq\fBmake install\fR\(rq command to the \fB/usr/local\fR directory since the Debian package can be removed cleanly by the \(lq\fBdpkg \-P\fR \fI\&...\(rq\fR command\&. Here are some examples of how to build such test packages\&. (These should work in most cases\&. If the \fB\-d\fR option does not work, try the \fB\-t\fR option instead\&.)
+For a well behaving source, you can build a good\-for\-local\-use installable single Debian binary package easily with one command\&. Test install of such a package generated in this way offers a good alternative to the traditional \(lq\fBmake install\fR\(rq command into the \fB/usr/local\fR directory since the Debian package can be removed cleanly by the \(lq\fBdpkg \-P\fR \fI\&\|.\|.\|.\(rq\fR command\&. Here are some examples of how to build such test packages\&. (These should work in most cases\&. If the \fB\-d\fR option does not work, try the \fB\-t\fR option instead\&.)
.sp
For a typical C program source tree packaged with autoconf/automake:
.sp
@@ -723,7 +723,7 @@
\fBdebmake \-d \-i debuild\fR
.RE
.sp
-For a typical python module source tree:
+For a typical Python module source tree:
.sp
.RS 4
.ie n \{\
@@ -736,7 +736,7 @@
\fBdebmake \-s \-d \-b":python" \-i debuild\fR
.RE
.sp
-For a typical python module in the \fIpackage\-version\fR\fB\&.tar\&.gz\fR archive:
+For a typical Python module in the \fIpackage\-version\fR\fB\&.tar\&.gz\fR archive:
.sp
.RS 4
.ie n \{\
@@ -749,7 +749,7 @@
\fBdebmake \-s \-a \fR\fB\fIpackage\-version\fR\fR\fB\&.tar\&.gz \-b":python" \-i debuild\fR
.RE
.sp
-For a typical perl module in the \fIPackage\-version\fR\fB\&.tar\&.gz\fR archive:
+For a typical Perl module in the \fIPackage\-version\fR\fB\&.tar\&.gz\fR archive:
.sp
.RS 4
.ie n \{\
@@ -773,7 +773,7 @@
.sp -1
.IP \(bu 2.3
.\}
-Python3 program may require the
+Python3 programs may require the
\fBdh\-python\fR
package\&.
.RE
@@ -786,7 +786,7 @@
.sp -1
.IP \(bu 2.3
.\}
-Autotools (Autoconf + Automake) build system may require
+The Autotools (Autoconf + Automake) build system may require
\fBautotools\-dev\fR
or
\fBdh\-autoreconf\fR
@@ -801,7 +801,7 @@
.sp -1
.IP \(bu 2.3
.\}
-Ruby program may require the
+Ruby programs may require the
\fBgem2deb\fR
package\&.
.RE
@@ -814,7 +814,7 @@
.sp -1
.IP \(bu 2.3
.\}
-Java program may require the
+Java programs may require the
\fBjavahelper\fR
package\&.
.RE
@@ -844,11 +844,11 @@
.RE
.SH "CAVEAT"
.sp
-\fBdebmake\fR is meant to provide template files for the package maintainer to work on\&. Comment lines started by \fB#\fR contain the tutorial text\&. You must remove or edit such comment lines before uploading to the Debian archive\&.
+\fBdebmake\fR is meant to provide template files for the package maintainer to work on\&. Comment lines started by \fB#\fR contain the tutorial text\&. You should remove or edit such comment lines before uploading to the Debian archive\&.
.sp
-The license extraction and assignment process involves a lot of heuristics, it may fail in some cases\&. It is highly recommended to use other tools such as \fBlicensecheck\fR from the \fBdevscripts\fR package in conjunction with \fBdebmake\fR\&.
+The license extraction and assignment process involves a lot of heuristics; it may fail in some cases\&. It is highly recommended to use other tools such as \fBlicensecheck\fR from the \fBdevscripts\fR package in conjunction with \fBdebmake\fR\&.
.sp
-There are some limitations for what characters may be used as a part of the Debian package\&. The most notable limitation is the prohibition of uppercase letters in the package name\&. Here is the summary in the regular expression\&.
+There are some limitations for what characters may be used as a part of the Debian package\&. The most notable limitation is the prohibition of uppercase letters in the package name\&. Here is a summary as a set of regular expressions:
.sp
.RS 4
.ie n \{\
@@ -894,7 +894,7 @@
Debian revision (\fB\-r\fR): [0\-9][+\&.~a\-z0\-9A\-Z]*
.RE
.sp
-See the exact definition in Chapter 5 \- Control files and their fields of the \(lqDebian Policy Manual\(rq\&.
+See the exact definition in Chapter 5 \- Control files and their fields in the \(lqDebian Policy Manual\(rq\&.
.sp
\fBdebmake\fR assumes relatively simple packaging cases\&. So all programs related to the interpreter are assumed to be "\fBArchitecture: all\fR"\&. This is not always true\&.
.SH "DEBUG"
@@ -1063,7 +1063,7 @@
.RS 4
.\}
.nf
- $ DEBUG=pdfbmeclak debmake \&.\&.\&.
+ $ DEBUG=pdfbmeclak debmake \&.\|.\|.
.fi
.if n \{\
.RE
@@ -1078,8 +1078,8 @@
Expat License
.SH "SEE ALSO"
.sp
-The \fBdebmake\-doc\fR package provides the \(lqGuide for Debian Maintainers\(rq in the plain text, HTML and PDF formats under the \fB/usr/share/doc/debmake\-doc/\fR directory\&.
+The \fBdebmake\-doc\fR package provides the \(lqGuide for Debian Maintainers\(rq in plain text, HTML and PDF formats under the \fB/usr/share/doc/debmake\-doc/\fR directory\&.
.sp
Also, please read the original Debian New Maintainers\(cq Guide provided by the the \fBmaint\-guide\fR package\&.
.sp
-See also \fBdpkg\-source\fR(1), \fBdeb\-control\fR(5), \fBdebhelper\fR(7), \fBdh\fR(1), \fBdpkg\-buildpackage\fR(1), \fBdebuild\fR(1), \fBquilt\fR(1), \fBdpkg\-depcheck\fR(1), \fBpdebuild\fR(1), \fBpbuilder\fR(8), \fBcowbuilder\fR(8), \fBgbp\-buildpackage\fR(1), \fBgbp\-pq\fR(1), and \fBgit\-pbuilder\fR(1) manpages\&.
+See also \fBdpkg\-source\fR(1), \fBdeb\-control\fR(5), \fBdebhelper\fR(7), \fBdh\fR(1), \fBdpkg\-buildpackage\fR(1), \fBdebuild\fR(1), \fBquilt\fR(1), \fBdpkg\-depcheck\fR(1), \fBpdebuild\fR(1), \fBpbuilder\fR(8), \fBcowbuilder\fR(8), \fBgbp\-buildpackage\fR(1), \fBgbp\-pq\fR(1), and \fBgit\-pbuilder\fR(1) man pages\&.
debmake.pdf
Description: Adobe PDF document
debmake-new.pdf
Description: Adobe PDF document
