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 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\&.
Yes.
> .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 @@
Yes.
> .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).
YES.
> \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)
YES>
> -\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"
\fB\-\-fullname\fR is correct.
> 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\&.
Yes.
> -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\&.
Yes.
> @@ -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
I decided to make this part as:
The content of 'file' is sourced as the Python3 code at the end of *para.py*.
For example, the package description can be specified by the following file.
> -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\&.
Yes.
> .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\&.
Yes.
> .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)
I see. You are talking this ,,
This may be Japanese style. I meant this as an abbreviation to
say the same as above.
...
> -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
Yes.
> -\fB\-x4\fR: ,, + copyright file examples\&.
> +\fB\-x4\fR: all \fB-x3\fP files + copyright file examples\&.
Yes.
> -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\&.)
I made it as ... raditional ``*make install*'' command installing into
...
> -For a typical python module source tree:
> +For a typical Python module source tree:
Yes.
> .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\&.
This is must. lintian flags them and upload will be rejected.
> -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\&.
Yes.
> -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:
Yes.
> -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\&.
Yes.
> -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\&.
Yes.
> -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\&.
I uses "manpage" across all my documents.
