Bug#1123493: zsyncmake.1: Some remarks and a patch with editorial changes for this man page
Package: zsync
Version: 0.6.2-9
Severity: minor
Tags: patch
Dear Maintainer,
>From "/usr/share/doc/debian/bug-reporting.txt.gz":
Don't file bugs upstream
If you file a bug in Debian, don't send a copy to the upstream software
maintainers yourself, as it is possible that the bug exists only in
Debian. If necessary, the maintainer of the package will forward the
bug upstream.
-.-
I do not send reports upstream if I have to get an account there.
The Debian maintainers have one already.
If I get a negative (or no) response from upstream, I send henceforth
bugs to Debian.
-.-
* What led up to the situation?
Checking for defects with a new version
test-[g|n]roff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=0 -ww -z < "man page"
[Use
grep -n -e ' $' -e '\\~$' -e ' \\f.$' -e ' \\"' <file>
to find (most) trailing spaces.]
["test-groff" is a script in the repository for "groff"; is not shipped]
(local copy and "troff" slightly changed by me).
[The fate of "test-nroff" was decided in groff bug #55941.]
* What was the outcome of this action?
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=0 -ww -z ":
troff:<stdin>:64: warning: [page 2, 6.6i]: cannot adjust line; underset by 7.907n
Output from "test-nroff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=0 -ww -z ":
troff:<stdin>:64: warning [page 1, line 131]: cannot break line in l adjust mode; overset by 22n
* What outcome did you expect instead?
No output (no warnings).
-.-
General remarks and further material, if a diff-file exist, are in the
attachments.
-- System Information:
Debian Release: forky/sid
APT prefers testing
APT policy: (500, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.17.11+deb14-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 zsync depends on:
ii libc6 2.42-5
zsync recommends no packages.
zsync suggests no packages.
-- no debconf information
Input file is zsyncmake.1
Output from "mandoc -T lint zsyncmake.1": (shortened list)
17 STYLE: input text line longer than 80 bytes:
21 STYLE: whitespace at end of input line
6 WARNING: skipping paragraph macro: PP after SH
1 WARNING: skipping paragraph macro: PP empty
Find most trailing spaces with:
grep -n -e ' $' -e ' \\f.$' -e ' \\"' <man page>
-.-.
Output from
test-nroff -mandoc -t -ww -z zsyncmake.1: (shortened list)
1 cannot break line in l adjust mode; overset by 22n
-.-.
Input file is zsyncmake.1
Remove space characters (whitespace) at the end of lines.
Use "git apply ... --whitespace=fix" to fix extra space issues, or use
global configuration "core.whitespace".
Number of lines affected is
21
-.-.
Change two HYPHEN-MINUSES (code 0x2D) to an em-dash (\(em),
if one is intended.
" \(em " creates a too big gap in the text (in "troff").
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 "-"
(begin of an option or end of options)
then use "\-\-".
zsyncmake.1:50:zsync can work with compressed data, and, in most cases where the data is not already compressed, it is more efficient to compress it first. While you can just compress the file to transfer with gzip, if you use this option then zsyncmake will compress the file for you, producing a .gz file which is optimised for zsync. This can be 30% more efficient at download time than compressing with gzip --best - but the compressed file will not be as small at that produced by gzip.
-.-.
Change -- in x--y to \(em (em-dash), or, if an
option, to \-\-
50:zsync can work with compressed data, and, in most cases where the data is not already compressed, it is more efficient to compress it first. While you can just compress the file to transfer with gzip, if you use this option then zsyncmake will compress the file for you, producing a .gz file which is optimised for zsync. This can be 30% more efficient at download time than compressing with gzip --best - but the compressed file will not be as small at that produced by gzip.
-.-.
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.
21:Specify the blocksize to the underlying rsync algorithm. A smaller blocksize may be more efficient for files where there are likely to be lots of small, scattered changes between downloads; a larger blocksize is more efficient for files with fewer or less scattered changes. This blocksize must be a power of two. If not specified, zsyncmake chooses one which it thinks is best for this file (currently either 2048 or 4096 depending on file size) - so normally tyou should not need to override the default.
24:Tells zsyncmake not to generate any instructions in the .zsync telling the client to compress the data it receives. This is implied by -z, but this option is here in case you compress a file yourself only for the transfer, but want the client to end up with the uncompressed file (e.g. you are transferring an ISO, which is held compressed on the server, but which the client cannot use unless it is uncompressed). Without -C, zsyncmake will produce directions for the client to compress the file it receives where appropriate; -C is here so you can stop it telling the client to do that.
27:Tells zsyncmake that the client must be able to receive the exact file that was supplied. Without this option, zsyncmake only gives a weaker guarantee - that the client will receive the data it contains (e.g. it might transfer the uncompressed version of a .gz to the client). Note that this still doesn't guarantee that the client will get it - the client could ignore the directives in the zsync file, or might be incapable of exactly reproducing the compression used. But with -e you know that zsyncmake has made it possible to get the exact data - it will exit with an error if it cannot.
48:Compress the file to transfer. Note that this overwrites any file called \fIfilename\fP.gz without warning (if you don't give a filename, e.g. because you are reading from stdin, then zsync will use the name supplied with -f, or as a last fallback, zsync-target.gz).
50:zsync can work with compressed data, and, in most cases where the data is not already compressed, it is more efficient to compress it first. While you can just compress the file to transfer with gzip, if you use this option then zsyncmake will compress the file for you, producing a .gz file which is optimised for zsync. This can be 30% more efficient at download time than compressing with gzip --best - but the compressed file will not be as small at that produced by gzip.
58:Note use of -C to save the client compressing the file on receipt; the Debian package system uses the file uncompressed.
-.-.
Strings longer than 3/4 of a standard line length (80).
Use "\:" to split the string at the end of an output line, for example a
long URL (web address).
This is a groff extension.
56 zsyncmake \-C \-u http://ftp.uk.debian.org/debian/dists/sarge/main/binary\-i386/Packages.gz Packages.gz
64 zsyncmake \-e \-u http://www.mirrorservice.org/sites/ftp.freebsd.org/pub/FreeBSD/ports/distfiles/zsync-0.2.2.tar.gz zsync-0.2.2.tar.gz
-.-.
Add a "\&" (or a comma (Oxford comma)) after an abbreviation
or use English words
(man-pages(7)).
Abbreviation points should be marked as such and protected against being
interpreted as an end of sentence, if they are not, and that independent
of the current place on the line.
24:Tells zsyncmake not to generate any instructions in the .zsync telling the client to compress the data it receives. This is implied by -z, but this option is here in case you compress a file yourself only for the transfer, but want the client to end up with the uncompressed file (e.g. you are transferring an ISO, which is held compressed on the server, but which the client cannot use unless it is uncompressed). Without -C, zsyncmake will produce directions for the client to compress the file it receives where appropriate; -C is here so you can stop it telling the client to do that.
27:Tells zsyncmake that the client must be able to receive the exact file that was supplied. Without this option, zsyncmake only gives a weaker guarantee - that the client will receive the data it contains (e.g. it might transfer the uncompressed version of a .gz to the client). Note that this still doesn't guarantee that the client will get it - the client could ignore the directives in the zsync file, or might be incapable of exactly reproducing the compression used. But with -e you know that zsyncmake has made it possible to get the exact data - it will exit with an error if it cannot.
48:Compress the file to transfer. Note that this overwrites any file called \fIfilename\fP.gz without warning (if you don't give a filename, e.g. because you are reading from stdin, then zsync will use the name supplied with -f, or as a last fallback, zsync-target.gz).
-.-.
Wrong distance (not two spaces) between sentences in the input file.
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.
Mark a final abbreviation point as such by suffixing it with "\&".
Some sentences (etc.) do not begin on a new line.
Split (sometimes) lines after a punctuation mark; before a conjunction.
Lines with only one (or two) space(s) between sentences could be split,
so latter sentences begin on a new line.
Use
#!/usr/bin/sh
sed -e '/^\./n' \
-e 's/\([[:alpha:]]\)\. */\1.\n/g' $1
to split lines after a sentence period.
Check result with the difference between the formatted outputs.
See also the attachment "general.bugs"
[List of affected lines removed.]
12:Constructs a metafile for the zsync client program to use to perform partial file downloads. \fIfilename\fR is the file that users wish to downloads; zsyncmake constructs the appropriate metafile and writes \fIfilename\fR.zsync in the current directory.
14:zsync will need at least one URL from which to download the file content. If the .zsync will be in the same directory as the file to download, you can accept the default \- zsync includes a relative URL in the control file. If not, use the \fB\-u\fR option to specify the URL. You should also specify a URL for the uncompressed content with \-U if available, as zsync can make use of this for more efficient downloads sometimes. (You can edit the .zsync file and add these afterwards \- it has a simple key: value format in the header \- but I suggest you only do this once you are familiar with the tool.)
21:Specify the blocksize to the underlying rsync algorithm. A smaller blocksize may be more efficient for files where there are likely to be lots of small, scattered changes between downloads; a larger blocksize is more efficient for files with fewer or less scattered changes. This blocksize must be a power of two. If not specified, zsyncmake chooses one which it thinks is best for this file (currently either 2048 or 4096 depending on file size) - so normally tyou should not need to override the default.
24:Tells zsyncmake not to generate any instructions in the .zsync telling the client to compress the data it receives. This is implied by -z, but this option is here in case you compress a file yourself only for the transfer, but want the client to end up with the uncompressed file (e.g. you are transferring an ISO, which is held compressed on the server, but which the client cannot use unless it is uncompressed). Without -C, zsyncmake will produce directions for the client to compress the file it receives where appropriate; -C is here so you can stop it telling the client to do that.
27:Tells zsyncmake that the client must be able to receive the exact file that was supplied. Without this option, zsyncmake only gives a weaker guarantee - that the client will receive the data it contains (e.g. it might transfer the uncompressed version of a .gz to the client). Note that this still doesn't guarantee that the client will get it - the client could ignore the directives in the zsync file, or might be incapable of exactly reproducing the compression used. But with -e you know that zsyncmake has made it possible to get the exact data - it will exit with an error if it cannot.
36:Specifies the URL from which users can download the content of the supplied file. Users need the control file in order to find out what parts of the file they already have, and they need the URLs to retrieve the parts of the file that they don't already have. You can specify multiple URLs by specifying \-u multiple times. If not specified, zsync assumes that the file and the .zsync will reside in the same public directory, and includes a single relative URL.
39:Specifies a URL corresponding to the decompressed content of the file (only applicable if it is a gzip file). zsync can sometimes download more efficiently from the uncompressed data than from the compressed data \- it will take advantage of this if available. If no URLs are specifies, zsync looks for a file without the .gz extension and assumes that this will be in the same public dir as the .zsync, and includes a relative URL to it.
48:Compress the file to transfer. Note that this overwrites any file called \fIfilename\fP.gz without warning (if you don't give a filename, e.g. because you are reading from stdin, then zsync will use the name supplied with -f, or as a last fallback, zsync-target.gz).
50:zsync can work with compressed data, and, in most cases where the data is not already compressed, it is more efficient to compress it first. While you can just compress the file to transfer with gzip, if you use this option then zsyncmake will compress the file for you, producing a .gz file which is optimised for zsync. This can be 30% more efficient at download time than compressing with gzip --best - but the compressed file will not be as small at that produced by gzip.
53:zsyncmake automatically looks inside gzip compressed files and exports the underlying, uncompressed data to the zsyncmake file. In testing this has proved to provide greater download efficiency. \-Z overrides the default behaviour and treats gzip files as just binary data. Use this if it is essential that the user receives the compressed data (for instance because a cryptographic signature is available only for the compressed data). zsync is typically no use if you specify \-Z, unless the gzip file was compressed with the special \-\-rsync option to make it friendly to differential transfers.
62:In this case there is a large, compressible file to transfer. This creates a gzipped version of the file (optimised for zsync), and a .zsync file. A URL is automatically added assuming that the two files will be served from the same directory on the web server.
67:should download from the given URL. This example is for downloading a source
-.-.
Split lines longer than 80 characters (fill completely
an A4 sized page line on a terminal)
into two or more lines.
Appropriate break points are the end of a sentence and a subordinate
clause; after punctuation marks.
Add "\:" to split the string for the output, "\<newline>" in the source.
[List of affected lines removed.]
Longest line is number 14 with 606 characters
zsync will need at least one URL from which to download the file content. If the .zsync will be in the same directory as the file to download, you can accept the default \- zsync includes a relative URL in the control file. If not, use the \fB\-u\fR option to specify the URL. You should also specify a URL for the uncompressed content with \-U if available, as zsync can make use of this for more efficient downloads sometimes. (You can edit the .zsync file and add these afterwards \- it has a simple key: value format in the header \- but I suggest you only do this once you are familiar with the tool.)
-.-.
Use \(en (en-dash) for a dash at the beginning (end) of a line,
or between space characters,
not a minus (\-) or a hyphen (-), except in the NAME section.
zsyncmake.1:21:Specify the blocksize to the underlying rsync algorithm. A smaller blocksize may be more efficient for files where there are likely to be lots of small, scattered changes between downloads; a larger blocksize is more efficient for files with fewer or less scattered changes. This blocksize must be a power of two. If not specified, zsyncmake chooses one which it thinks is best for this file (currently either 2048 or 4096 depending on file size) - so normally tyou should not need to override the default.
zsyncmake.1:27:Tells zsyncmake that the client must be able to receive the exact file that was supplied. Without this option, zsyncmake only gives a weaker guarantee - that the client will receive the data it contains (e.g. it might transfer the uncompressed version of a .gz to the client). Note that this still doesn't guarantee that the client will get it - the client could ignore the directives in the zsync file, or might be incapable of exactly reproducing the compression used. But with -e you know that zsyncmake has made it possible to get the exact data - it will exit with an error if it cannot.
zsyncmake.1:50:zsync can work with compressed data, and, in most cases where the data is not already compressed, it is more efficient to compress it first. While you can just compress the file to transfer with gzip, if you use this option then zsyncmake will compress the file for you, producing a .gz file which is optimised for zsync. This can be 30% more efficient at download time than compressing with gzip --best - but the compressed file will not be as small at that produced by gzip.
-.-.
The name of a man page is typeset in bold (or italic) and the section in
roman (see man-pages(7)).
76:zsync(1)
-.-.
Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".
zsyncmake.1:14:zsync will need at least one URL from which to download the file content. If the .zsync will be in the same directory as the file to download, you can accept the default \- zsync includes a relative URL in the control file. If not, use the \fB\-u\fR option to specify the URL. You should also specify a URL for the uncompressed content with \-U if available, as zsync can make use of this for more efficient downloads sometimes. (You can edit the .zsync file and add these afterwards \- it has a simple key: value format in the header \- but I suggest you only do this once you are familiar with the tool.)
zsyncmake.1:21:Specify the blocksize to the underlying rsync algorithm. A smaller blocksize may be more efficient for files where there are likely to be lots of small, scattered changes between downloads; a larger blocksize is more efficient for files with fewer or less scattered changes. This blocksize must be a power of two. If not specified, zsyncmake chooses one which it thinks is best for this file (currently either 2048 or 4096 depending on file size) - so normally tyou should not need to override the default.
zsyncmake.1:24:Tells zsyncmake not to generate any instructions in the .zsync telling the client to compress the data it receives. This is implied by -z, but this option is here in case you compress a file yourself only for the transfer, but want the client to end up with the uncompressed file (e.g. you are transferring an ISO, which is held compressed on the server, but which the client cannot use unless it is uncompressed). Without -C, zsyncmake will produce directions for the client to compress the file it receives where appropriate; -C is here so you can stop it telling the client to do that.
zsyncmake.1:27:Tells zsyncmake that the client must be able to receive the exact file that was supplied. Without this option, zsyncmake only gives a weaker guarantee - that the client will receive the data it contains (e.g. it might transfer the uncompressed version of a .gz to the client). Note that this still doesn't guarantee that the client will get it - the client could ignore the directives in the zsync file, or might be incapable of exactly reproducing the compression used. But with -e you know that zsyncmake has made it possible to get the exact data - it will exit with an error if it cannot.
zsyncmake.1:30:Set the filename to include in the output file (this is what the file will be called when a user finished downloading it).
zsyncmake.1:39:Specifies a URL corresponding to the decompressed content of the file (only applicable if it is a gzip file). zsync can sometimes download more efficiently from the uncompressed data than from the compressed data \- it will take advantage of this if available. If no URLs are specifies, zsync looks for a file without the .gz extension and assumes that this will be in the same public dir as the .zsync, and includes a relative URL to it.
zsyncmake.1:48:Compress the file to transfer. Note that this overwrites any file called \fIfilename\fP.gz without warning (if you don't give a filename, e.g. because you are reading from stdin, then zsync will use the name supplied with -f, or as a last fallback, zsync-target.gz).
zsyncmake.1:53:zsyncmake automatically looks inside gzip compressed files and exports the underlying, uncompressed data to the zsyncmake file. In testing this has proved to provide greater download efficiency. \-Z overrides the default behaviour and treats gzip files as just binary data. Use this if it is essential that the user receives the compressed data (for instance because a cryptographic signature is available only for the compressed data). zsync is typically no use if you specify \-Z, unless the gzip file was compressed with the special \-\-rsync option to make it friendly to differential transfers.
zsyncmake.1:62:In this case there is a large, compressible file to transfer. This creates a gzipped version of the file (optimised for zsync), and a .zsync file. A URL is automatically added assuming that the two files will be served from the same directory on the web server.
-.-.
Only one space character is after a possible end of sentence
(after a punctuation, that can end a sentence).
zsyncmake.1:12:Constructs a metafile for the zsync client program to use to perform partial file downloads. \fIfilename\fR is the file that users wish to downloads; zsyncmake constructs the appropriate metafile and writes \fIfilename\fR.zsync in the current directory.
zsyncmake.1:14:zsync will need at least one URL from which to download the file content. If the .zsync will be in the same directory as the file to download, you can accept the default \- zsync includes a relative URL in the control file. If not, use the \fB\-u\fR option to specify the URL. You should also specify a URL for the uncompressed content with \-U if available, as zsync can make use of this for more efficient downloads sometimes. (You can edit the .zsync file and add these afterwards \- it has a simple key: value format in the header \- but I suggest you only do this once you are familiar with the tool.)
zsyncmake.1:21:Specify the blocksize to the underlying rsync algorithm. A smaller blocksize may be more efficient for files where there are likely to be lots of small, scattered changes between downloads; a larger blocksize is more efficient for files with fewer or less scattered changes. This blocksize must be a power of two. If not specified, zsyncmake chooses one which it thinks is best for this file (currently either 2048 or 4096 depending on file size) - so normally tyou should not need to override the default.
zsyncmake.1:24:Tells zsyncmake not to generate any instructions in the .zsync telling the client to compress the data it receives. This is implied by -z, but this option is here in case you compress a file yourself only for the transfer, but want the client to end up with the uncompressed file (e.g. you are transferring an ISO, which is held compressed on the server, but which the client cannot use unless it is uncompressed). Without -C, zsyncmake will produce directions for the client to compress the file it receives where appropriate; -C is here so you can stop it telling the client to do that.
zsyncmake.1:27:Tells zsyncmake that the client must be able to receive the exact file that was supplied. Without this option, zsyncmake only gives a weaker guarantee - that the client will receive the data it contains (e.g. it might transfer the uncompressed version of a .gz to the client). Note that this still doesn't guarantee that the client will get it - the client could ignore the directives in the zsync file, or might be incapable of exactly reproducing the compression used. But with -e you know that zsyncmake has made it possible to get the exact data - it will exit with an error if it cannot.
zsyncmake.1:36:Specifies the URL from which users can download the content of the supplied file. Users need the control file in order to find out what parts of the file they already have, and they need the URLs to retrieve the parts of the file that they don't already have. You can specify multiple URLs by specifying \-u multiple times. If not specified, zsync assumes that the file and the .zsync will reside in the same public directory, and includes a single relative URL.
zsyncmake.1:39:Specifies a URL corresponding to the decompressed content of the file (only applicable if it is a gzip file). zsync can sometimes download more efficiently from the uncompressed data than from the compressed data \- it will take advantage of this if available. If no URLs are specifies, zsync looks for a file without the .gz extension and assumes that this will be in the same public dir as the .zsync, and includes a relative URL to it.
zsyncmake.1:48:Compress the file to transfer. Note that this overwrites any file called \fIfilename\fP.gz without warning (if you don't give a filename, e.g. because you are reading from stdin, then zsync will use the name supplied with -f, or as a last fallback, zsync-target.gz).
zsyncmake.1:50:zsync can work with compressed data, and, in most cases where the data is not already compressed, it is more efficient to compress it first. While you can just compress the file to transfer with gzip, if you use this option then zsyncmake will compress the file for you, producing a .gz file which is optimised for zsync. This can be 30% more efficient at download time than compressing with gzip --best - but the compressed file will not be as small at that produced by gzip.
zsyncmake.1:53:zsyncmake automatically looks inside gzip compressed files and exports the underlying, uncompressed data to the zsyncmake file. In testing this has proved to provide greater download efficiency. \-Z overrides the default behaviour and treats gzip files as just binary data. Use this if it is essential that the user receives the compressed data (for instance because a cryptographic signature is available only for the compressed data). zsync is typically no use if you specify \-Z, unless the gzip file was compressed with the special \-\-rsync option to make it friendly to differential transfers.
zsyncmake.1:62:In this case there is a large, compressible file to transfer. This creates a gzipped version of the file (optimised for zsync), and a .zsync file. A URL is automatically added assuming that the two files will be served from the same directory on the web server.
zsyncmake.1:67:should download from the given URL. This example is for downloading a source
-.-.
Remove quotes when there is a printable
but no space character between them
and the quotes are not for emphasis (markup),
for example as an argument to a macro.
zsyncmake.1:1:.TH "zsyncmake" "1" "0.6.2" "Colin Phipps" "File Transfer"
zsyncmake.1:2:.SH "NAME"
zsyncmake.1:5:.SH "SYNTAX"
zsyncmake.1:10:.SH "DESCRIPTION"
zsyncmake.1:17:.SH "OPTIONS"
zsyncmake.1:54:.SH "EXAMPLES"
zsyncmake.1:71:.SH "AUTHORS"
-.-.
Space character after a macro call.
3:.LP
6:.LP
8:.LP
11:.LP
13:.LP
15:.LP
18:.LP
19:.TP
22:.TP
25:.TP
28:.TP
31:.TP
34:.TP
37:.TP
40:.TP
43:.TP
46:.TP
51:.TP
55:.LP
72:.LP
75:.LP
-.-.
Use "\-" instead of "-" in web addresses.
64:zsyncmake \-e \-u http://www.mirrorservice.org/sites/ftp.freebsd.org/pub/FreeBSD/ports/distfiles/zsync-0.2.2.tar.gz zsync-0.2.2.tar.gz
-.-.
Put a (long) web address on a new output line to reduce the posibility of
splitting the address between two output lines.
Or inhibit hyphenation with "\%" in front of the name.
64:zsyncmake \-e \-u http://www.mirrorservice.org/sites/ftp.freebsd.org/pub/FreeBSD/ports/distfiles/zsync-0.2.2.tar.gz zsync-0.2.2.tar.gz
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=0 -ww -z ":
troff:<stdin>:64: warning: [page 2, 6.6i]: cannot adjust line; underset by 7.907n
Output from "test-nroff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=0 -ww -z ":
troff:<stdin>:64: warning [page 1, line 131]: cannot break line in l adjust mode; overset by 22n
-.-
Spelling:
tyou -> you
-.-
Generally:
Split (sometimes) lines after a punctuation mark; before a conjunction.
-.-
Tables:
Put data, that are wider than the header in the (centered) last column,
in a "T{...\nT}" block(, when the table gets wider than the output line).
Table headers, that are wider than any data in the corresponding column,
do not need to be centered, so left adjustment (l, L) is sufficient.
--- zsyncmake.1 2025-12-16 20:58:22.297783949 +0000
+++ zsyncmake.1.new 2025-12-16 21:43:17.953207747 +0000
@@ -1,76 +1,91 @@
-.TH "zsyncmake" "1" "0.6.2" "Colin Phipps" "File Transfer"
-.SH "NAME"
-.LP
+.TH zsyncmake 1 0.6.2 "Colin Phipps" "File Transfer"
+.SH NAME
zsyncmake \- Build control file for zsync(1)
-.SH "SYNTAX"
-.LP
+.SH SYNTAX
zsyncmake [ { \-z | \-Z } ] [ \-e ] [ \-C ] [ \-u \fIurl\fR ] [ \-U \fIurl\fR ] [ \-b \fIblocksize\fR ] [ \-o \fIoutfile\fR ] [ \-f \fItargetfilename\fR ] [ \-v ] \fIfilename\fP
-.LP
+.LP
zsync \-V
-.SH "DESCRIPTION"
-.LP
+.SH DESCRIPTION
Constructs a metafile for the zsync client program to use to perform partial file downloads. \fIfilename\fR is the file that users wish to downloads; zsyncmake constructs the appropriate metafile and writes \fIfilename\fR.zsync in the current directory.
-.LP
+.LP
zsync will need at least one URL from which to download the file content. If the .zsync will be in the same directory as the file to download, you can accept the default \- zsync includes a relative URL in the control file. If not, use the \fB\-u\fR option to specify the URL. You should also specify a URL for the uncompressed content with \-U if available, as zsync can make use of this for more efficient downloads sometimes. (You can edit the .zsync file and add these afterwards \- it has a simple key: value format in the header \- but I suggest you only do this once you are familiar with the tool.)
-.LP
+.LP
Note that zsyncmake itself does not (currently) verify the URLs or download any data, you must provide the file data locally and check the URLs yourself.
-.SH "OPTIONS"
-.LP
-.TP
+.SH OPTIONS
+.TP
\fB\-b\fR \fIblocksize\fR
-Specify the blocksize to the underlying rsync algorithm. A smaller blocksize may be more efficient for files where there are likely to be lots of small, scattered changes between downloads; a larger blocksize is more efficient for files with fewer or less scattered changes. This blocksize must be a power of two. If not specified, zsyncmake chooses one which it thinks is best for this file (currently either 2048 or 4096 depending on file size) - so normally tyou should not need to override the default.
-.TP
+Specify the blocksize to the underlying rsync algorithm.
+A smaller blocksize may be more efficient for files where there are
+likely to be lots of small, scattered changes between downloads; a larger
+blocksize is more efficient for files with fewer or less scattered
+changes. This blocksize must be a power of two. If not specified,
+zsyncmake chooses one which it thinks is best for this file
+(currently either 2048 or 4096 depending on file size)
+\(en so normally you should not need to override the default.
+.TP
\fB\-C\fR
-Tells zsyncmake not to generate any instructions in the .zsync telling the client to compress the data it receives. This is implied by -z, but this option is here in case you compress a file yourself only for the transfer, but want the client to end up with the uncompressed file (e.g. you are transferring an ISO, which is held compressed on the server, but which the client cannot use unless it is uncompressed). Without -C, zsyncmake will produce directions for the client to compress the file it receives where appropriate; -C is here so you can stop it telling the client to do that.
-.TP
+Tells zsyncmake not to generate any instructions in the \&.zsync telling the client to compress the data it receives. This is implied by \-z, but this option is here in case you compress a file yourself only for the transfer, but want the client to end up with the uncompressed file (e.g.\& you are transferring an ISO, which is held compressed on the server, but which the client cannot use unless it is uncompressed). Without \-C, zsyncmake will produce directions for the client to compress the file it receives where appropriate; \-C is here so you can stop it telling the client to do that.
+.TP
\fB\-e\fR
-Tells zsyncmake that the client must be able to receive the exact file that was supplied. Without this option, zsyncmake only gives a weaker guarantee - that the client will receive the data it contains (e.g. it might transfer the uncompressed version of a .gz to the client). Note that this still doesn't guarantee that the client will get it - the client could ignore the directives in the zsync file, or might be incapable of exactly reproducing the compression used. But with -e you know that zsyncmake has made it possible to get the exact data - it will exit with an error if it cannot.
-.TP
+Tells zsyncmake that the client must be able to receive the exact file that was supplied. Without this option, zsyncmake only gives a weaker guarantee \(en that the client will receive the data it contains (e.g.\& it might transfer the uncompressed version of a \&.gz to the client). Note that this still doesn't guarantee that the client will get it \(en the client could ignore the directives in the zsync file, or might be incapable of exactly reproducing the compression used. But with \-e you know that zsyncmake has made it possible to get the exact data \(en it will exit with an error if it cannot.
+.TP
\fB\-f\fR \fIfilename\fR
Set the filename to include in the output file (this is what the file will be called when a user finished downloading it).
-.TP
+.TP
\fB\-o\fR \fIoutputfile\fR
Override the default output file name.
-.TP
+.TP
\fB\-u\fR \fIurl\fR
Specifies the URL from which users can download the content of the supplied file. Users need the control file in order to find out what parts of the file they already have, and they need the URLs to retrieve the parts of the file that they don't already have. You can specify multiple URLs by specifying \-u multiple times. If not specified, zsync assumes that the file and the .zsync will reside in the same public directory, and includes a single relative URL.
-.TP
+.TP
\fB\-U\fR \fIurl\fR
Specifies a URL corresponding to the decompressed content of the file (only applicable if it is a gzip file). zsync can sometimes download more efficiently from the uncompressed data than from the compressed data \- it will take advantage of this if available. If no URLs are specifies, zsync looks for a file without the .gz extension and assumes that this will be in the same public dir as the .zsync, and includes a relative URL to it.
-.TP
+.TP
\fB\-v\fR
Enable verbose messages.
-.TP
+.TP
\fB\-V\fR
Prints the version of zsync.
-.TP
+.TP
\fB\-z\fR
-Compress the file to transfer. Note that this overwrites any file called \fIfilename\fP.gz without warning (if you don't give a filename, e.g. because you are reading from stdin, then zsync will use the name supplied with -f, or as a last fallback, zsync-target.gz).
+Compress the file to transfer. Note that this overwrites any file called \fIfilename\fP.gz without warning (if you don't give a filename, e.g.\& because you are reading from stdin, then zsync will use the name supplied with \-f, or as a last fallback, zsync-target.gz).
+.TP
+zsync can work with compressed data, and, in most cases where the data is not already compressed, it is more efficient to compress it first. While you can just compress the file to transfer with gzip, if you use this option then zsyncmake will compress the file for you, producing a .gz file which is optimised for zsync. This can be 30% more efficient at download time than compressing with gzip \-\-best \(en but the compressed file will not be as small at that produced by gzip.
.TP
-zsync can work with compressed data, and, in most cases where the data is not already compressed, it is more efficient to compress it first. While you can just compress the file to transfer with gzip, if you use this option then zsyncmake will compress the file for you, producing a .gz file which is optimised for zsync. This can be 30% more efficient at download time than compressing with gzip --best - but the compressed file will not be as small at that produced by gzip.
-.TP
\fB\-Z\fR
zsyncmake automatically looks inside gzip compressed files and exports the underlying, uncompressed data to the zsyncmake file. In testing this has proved to provide greater download efficiency. \-Z overrides the default behaviour and treats gzip files as just binary data. Use this if it is essential that the user receives the compressed data (for instance because a cryptographic signature is available only for the compressed data). zsync is typically no use if you specify \-Z, unless the gzip file was compressed with the special \-\-rsync option to make it friendly to differential transfers.
-.SH "EXAMPLES"
-.LP
-zsyncmake \-C \-u http://ftp.uk.debian.org/debian/dists/sarge/main/binary\-i386/Packages.gz Packages.gz
+.SH EXAMPLES
+.ie \n(.g \{\
+ zsyncmake \-C \-u http://ftp.uk.debian.org/\:debian/\:dists/\:sarge/\:main/\:binary\-i386/Packages.gz Packages.gz
+.\}
+.el \{\
+ zsyncmake \-C \-u http://ftp.uk.debian.org/debian/dists/sarge/main/
+binary\-i386/Packages.gz Packages.gz
+.\}
.LP
-Note use of -C to save the client compressing the file on receipt; the Debian package system uses the file uncompressed.
+Note use of \-C to save the client compressing the file on receipt; the Debian package system uses the file uncompressed.
.LP
zsyncmake \-z my-subversion-dump
.LP
In this case there is a large, compressible file to transfer. This creates a gzipped version of the file (optimised for zsync), and a .zsync file. A URL is automatically added assuming that the two files will be served from the same directory on the web server.
.LP
-zsyncmake \-e \-u http://www.mirrorservice.org/sites/ftp.freebsd.org/pub/FreeBSD/ports/distfiles/zsync-0.2.2.tar.gz zsync-0.2.2.tar.gz
+.na
+.ie \n(.g \{\
+zsyncmake \-e \-u http://www.mirrorservice.org/\:sites/\:ftp.freebsd.org/\:\
+pub/\:FreeBSD/\:ports/\:distfiles/\:zsync\-0.2.2.tar.gz zsync-0.2.2.tar.gz
+.\}
+.el \{\
+zsyncmake \-e \-u http://www.mirrorservice.org/sites/ftp.freebsd.org/
+pub/FreeBSD/ports/distfiles/zsync\-0.2.2.tar.gz zsync-0.2.2.tar.gz
+.\}
+.ad
.LP
This creates a zsync referring to the named source tarball, which the client
should download from the given URL. This example is for downloading a source
tarball for a FreeBSD port, hence \-e is specified so the client will be able
to match its md5sum.
-
-.SH "AUTHORS"
-.LP
+.
+.SH AUTHORS
Colin Phipps <cph@moria.org.uk>
.SH "SEE ALSO"
-.LP
-zsync(1)
+.BR zsync (1)
Any program (person), that produces man pages, should check the output
for defects by using (both groff and nroff)
[gn]roff -mandoc -t -ww -b -z -K utf8 <man page>
To find trailing space use
grep -n -e ' $' -e ' \\f.$' -e ' \\"' <man page>
The same goes for man pages that are used as an input.
-.-
For a style guide use
mandoc -T lint
-.-
For general input conventions consult the man page "nroff(7)" (item
"Input conventions") or the Texinfo manual about the same item.
-.-
Any "autogenerator" should check its products with the above mentioned
'groff', 'mandoc', and additionally with 'nroff ...'.
It should also check its input files for too long (> 80) lines.
This is just a simple quality control measure.
The "autogenerator" may have to be corrected to get a better man page,
the source file may, and any additional file may.
-.-
Common defects:
Not removing trailing spaces (in in- and output).
The reason for these trailing spaces should be found and eliminated.
"git" has a "tool" to point out whitespace,
see for example "git-apply(1)" and git-config(1)")
-.-
Not beginning each input sentence on a new line.
Line length and patch size should thus be reduced when that has been fixed.
The script "reportbug" uses 'quoted-printable' encoding when a line is
longer than 1024 characters in an 'ascii' file.
See man-pages(7), item "semantic newline".
-.-
The difference between the formatted output of the original
and patched file can be seen with:
nroff -mandoc <file1> > <out1>
nroff -mandoc <file2> > <out2>
diff -d -u <out1> <out2>
and for groff, using
\"printf '%s\n%s\n' '.kern 0' '.ss 12 0' | groff -mandoc -Z - \"
instead of 'nroff -mandoc'
Add the option '-t', if the file contains a table.
Read the output from 'diff -d -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 -b -z"
export MAN_KEEP_STDERR=yes (or any non-empty value)
-.-
Reply to: