Errors in man pages of bzip2

Errors in man pages of bzip2

[Helge Kreutzmann]

[-- Attachment #1: Type: text/plain, Size: 3139 bytes --]

Dear bzip2 maintainer,
the manpage-l10n project maintains a large number of translations of
man pages both from a large variety of sources (including bzip2) as
well for a large variety of target languages.

During their work translators notice different possible issues in the
original (english) man pages. Sometimes this is a straightforward
typo, sometimes a hard to read sentence, sometimes this is a
convention not held up and sometimes we simply do not understand the
original.

We use several distributions as sources and update regularly (at
least every 2 month). This means we are fairly recent (some
distributions like archlinux also update frequently) but might miss
the latest upstream version once in a while, so the error might be
already fixed. We apologize and ask you to close the issue immediately
if this should be the case, but given the huge volume of projects and
the very limited number of volunteers we are not able to double check
each and every issue.

Secondly we translators see the manpages in the neutral po format,
i.e. converted and harmonized, but not the original source (be it man,
groff, xml or other). So we cannot provide a true patch (where
possible), but only an approximation which you need to convert into
your source format.

Finally the issues I'm reporting have accumulated over time and are
not always discovered by me, so sometimes my description of the
problem my be a bit limited - do not hesitate to ask so we can clarify
them.

I'm now reporting the errors for your project. If future reports
should use another channel, please let me know.

Man page: bzdiff.1
Issue: missing markup (B< >)

"cmp(1), diff(1), bzmore(1), bzless(1), bzgrep(1), bzip2(1)"
--
Man page: bzexe.1
Issue: markup of the command: B<bzexe /bin/cat>

"The I<bzexe> utility allows you to compress executables in place and have "
"them automatically uncompress and execute when you run them (at a penalty in "
"performance).  For example if you execute ``bzexe /bin/cat'' it will create "
"the following two files:"
--
Man page: bzexe.1
Issue: markup of file names:  I<>

"/bin/cat~ is the original file and /bin/cat is the self-uncompressing "
"executable file.  You can remove /bin/cat~ once you are sure that /bin/cat "
"works properly."
--
Man page: bzexe.1
Issue: missing markup (B< >)

msgid "bzip2(1), znew(1), zmore(1), zcmp(1), zforce(1)"
--
Man page: bzgrep.1
Issue: missing markup (B< >)

"grep(1), egrep(1), fgrep(1), bzdiff(1), bzmore(1), bzless(1), bzip2(1)"
--
Man page: bzip2.1
Issue: I<GNU gzip,> → I<GNU gzip>,

"Unlike I<GNU gzip,> I<bzip2> will not create a cascade of I<.bz2> suffixes "
"even when using the I<--force> option:"
--
Man page: bzmore.1
Issue: missing markup (B< >)

"more(1), less(1), bzip2(1), bzdiff(1), bzgrep(1)"

-- 
      Dr. Helge Kreutzmann                     debian@helgefjell.de
           Dipl.-Phys.                   http://www.helgefjell.de/debian.php
        64bit GNU powered                     gpg signed mail preferred
           Help keep free software "libre": http://www.ffii.de/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Errors in man pages of bzip2

[Mark Wielaard]

Hi Helge,

Sorry for the late reply.

On Sat, Feb 05, 2022 at 11:35:40AM +0100, Helge Kreutzmann wrote:
> Finally the issues I'm reporting have accumulated over time and are
> not always discovered by me, so sometimes my description of the
> problem my be a bit limited - do not hesitate to ask so we can clarify
> them.
> 
> I'm now reporting the errors for your project. If future reports
> should use another channel, please let me know.

If you could file future issues in bugzilla:
https://sourceware.org/bugzilla/enter_bug.cgi?product=bzip2
Then there is an archive. But sending reports to this list is also
fine.

> Man page: bzdiff.1
> Issue: missing markup (B< >)
> 
> "cmp(1), diff(1), bzmore(1), bzless(1), bzgrep(1), bzip2(1)"

I don't understand what is wrong here.

> --
> Man page: bzexe.1
> Issue: markup of the command: B<bzexe /bin/cat>
> 
> "The I<bzexe> utility allows you to compress executables in place and have "
> "them automatically uncompress and execute when you run them (at a penalty in "
> "performance).  For example if you execute ``bzexe /bin/cat'' it will create "
> "the following two files:"

I believe bzexe is a Debian extension that isn't part of bzip2 as we ship it.

> --
> Man page: bzexe.1
> Issue: markup of file names:  I<>
> 
> "/bin/cat~ is the original file and /bin/cat is the self-uncompressing "
> "executable file.  You can remove /bin/cat~ once you are sure that /bin/cat "
> "works properly."

As above.

> --
> Man page: bzexe.1
> Issue: missing markup (B< >)
> 
> msgid "bzip2(1), znew(1), zmore(1), zcmp(1), zforce(1)"

As above.

> --
> Man page: bzgrep.1
> Issue: missing markup (B< >)
> 
> "grep(1), egrep(1), fgrep(1), bzdiff(1), bzmore(1), bzless(1), bzip2(1)"

Again, I don't understand the issue here.

> --
> Man page: bzip2.1
> Issue: I<GNU gzip,> → I<GNU gzip>,
> 
> "Unlike I<GNU gzip,> I<bzip2> will not create a cascade of I<.bz2> suffixes "
> "even when using the I<--force> option:"

This phrase isn't in our variant of the bzip2.1 man page.

> --
> Man page: bzmore.1
> Issue: missing markup (B< >)
> 
> "more(1), less(1), bzip2(1), bzdiff(1), bzgrep(1)"

This is like above, I don't really understand what is wrong with the
way we use SEE ALSO in the manpages.

Thanks,

Mark

Re: Errors in man pages of bzip2

[Helge Kreutzmann]

[-- Attachment #1: Type: text/plain, Size: 2696 bytes --]

Hello Mark,
On Tue, Apr 19, 2022 at 11:36:50PM +0200, Mark Wielaard wrote:
> Sorry for the late reply.
> 
> On Sat, Feb 05, 2022 at 11:35:40AM +0100, Helge Kreutzmann wrote:
> > Finally the issues I'm reporting have accumulated over time and are
> > not always discovered by me, so sometimes my description of the
> > problem my be a bit limited - do not hesitate to ask so we can clarify
> > them.
> > 
> > I'm now reporting the errors for your project. If future reports
> > should use another channel, please let me know.
> 
> If you could file future issues in bugzilla:
> https://sourceware.org/bugzilla/enter_bug.cgi?product=bzip2
> Then there is an archive. But sending reports to this list is also
> fine.

I can do this; however in February I was told by Micah Snyder to use
https://gitlab.com/groups/bzip2/-/issues

Is the sourcware bugzilla now preferred?

> > Man page: bzdiff.1
> > Issue: missing markup (B< >)
> > 
> > "cmp(1), diff(1), bzmore(1), bzless(1), bzgrep(1), bzip2(1)"
> 
> I don't understand what is wrong here.

The entries in SEE ALSO are marked in bold, which usually is indicated
in our format with B<>, so it should be B<cmp>(1) instead of cmp(1)
and similarly for the others. If you use *roff, it could look like
.BR \%cmp (1),
.BR \%diff (1),
...
> > --
> > Man page: bzexe.1
> > Issue: markup of the command: B<bzexe /bin/cat>
> > 
> > "The I<bzexe> utility allows you to compress executables in place and have "
> > "them automatically uncompress and execute when you run them (at a penalty in "
> > "performance).  For example if you execute ``bzexe /bin/cat'' it will create "
> > "the following two files:"
> 
> I believe bzexe is a Debian extension that isn't part of bzip2 as we ship it.

Ok, then I mark this accordingly.

> > --
> > Man page: bzgrep.1
> > Issue: missing markup (B< >)
> > 
> > "grep(1), egrep(1), fgrep(1), bzdiff(1), bzmore(1), bzless(1), bzip2(1)"
> 
> Again, I don't understand the issue here.

Same as above, missing bold markup.

> > --
> > Man page: bzmore.1
> > Issue: missing markup (B< >)
> > 
> > "more(1), less(1), bzip2(1), bzdiff(1), bzgrep(1)"
> 
> This is like above, I don't really understand what is wrong with the
> way we use SEE ALSO in the manpages.


Same as above, missing bold markup.

Thanks for handling the issues!

Greetings

         Helge

-- 
      Dr. Helge Kreutzmann                     debian@helgefjell.de
           Dipl.-Phys.                   http://www.helgefjell.de/debian.php
        64bit GNU powered                     gpg signed mail preferred
           Help keep free software "libre": http://www.ffii.de/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Errors in man pages of bzip2

[Mark Wielaard]

[-- Attachment #1: Type: text/plain, Size: 1943 bytes --]

Hi Helge,

On Wed, Apr 20, 2022 at 04:44:27PM +0200, Helge Kreutzmann wrote:
> On Tue, Apr 19, 2022 at 11:36:50PM +0200, Mark Wielaard wrote:
> > On Sat, Feb 05, 2022 at 11:35:40AM +0100, Helge Kreutzmann wrote:
> > If you could file future issues in bugzilla:
> > https://sourceware.org/bugzilla/enter_bug.cgi?product=bzip2
> > Then there is an archive. But sending reports to this list is also
> > fine.
> 
> I can do this; however in February I was told by Micah Snyder to use
> https://gitlab.com/groups/bzip2/-/issues
> 
> Is the sourcware bugzilla now preferred?

I guess the coordination between the projects isn't ideal.  But yes,
for stable bzip2 1.0.x, which is what distros ship, sourceware is
preferred. The gitlab project is working on an experimental 1.1
version and rust translation.

> > > Man page: bzdiff.1
> > > Issue: missing markup (B< >)
> > > 
> > > "cmp(1), diff(1), bzmore(1), bzless(1), bzgrep(1), bzip2(1)"
> > 
> > I don't understand what is wrong here.
> 
> The entries in SEE ALSO are marked in bold, which usually is indicated
> in our format with B<>, so it should be B<cmp>(1) instead of cmp(1)
> and similarly for the others. If you use *roff, it could look like
> .BR \%cmp (1),
> .BR \%diff (1),

Aha, ok that makes sense given that we are referring to commands.

> > > --
> > > Man page: bzgrep.1
> > > Issue: missing markup (B< >)
> > > 
> > > "grep(1), egrep(1), fgrep(1), bzdiff(1), bzmore(1), bzless(1), bzip2(1)"
> > 
> > Again, I don't understand the issue here.
> 
> Same as above, missing bold markup.
> 
> > > --
> > > Man page: bzmore.1
> > > Issue: missing markup (B< >)
> > > 
> > > "more(1), less(1), bzip2(1), bzdiff(1), bzgrep(1)"
> > 
> > This is like above, I don't really understand what is wrong with the
> > way we use SEE ALSO in the manpages.
> 
> Same as above, missing bold markup.

I pushed to attached commit to markup the commands in the SEE ALSO
sections as bold.

Thanks,

Mark

[-- Attachment #2: 0001-Mark-SEE-ALSO-commands-with-.BR-in-bzdiff.1-bzgrep.1.patch --]
[-- Type: text/x-diff, Size: 1644 bytes --]

From 64d6fa68c1af46f6408f832443ce23709a2f0a66 Mon Sep 17 00:00:00 2001
From: Mark Wielaard <mark@klomp.org>
Date: Thu, 21 Apr 2022 00:56:04 +0200
Subject: [PATCH] Mark SEE ALSO commands with .BR in bzdiff.1, bzgrep.1 and
 bzmore.1

This makes sure all commands show up as bold in the man pages.

Suggested-by: Helge Kreutzmann <debian@helgefjell.de>
---
 bzdiff.1 | 7 ++++++-
 bzgrep.1 | 8 +++++++-
 bzmore.1 | 6 +++++-
 3 files changed, 18 insertions(+), 3 deletions(-)

diff --git a/bzdiff.1 b/bzdiff.1
index adb7a8e..f02fa24 100644
--- a/bzdiff.1
+++ b/bzdiff.1
@@ -38,7 +38,12 @@ or
 .I diff
 is preserved.
 .SH "SEE ALSO"
-cmp(1), diff(1), bzmore(1), bzless(1), bzgrep(1), bzip2(1)
+.BR cmp (1),
+.BR diff (1),
+.BR bzmore (1),
+.BR bzless (1),
+.BR bzgrep (1),
+.BR bzip2 (1)
 .SH BUGS
 Messages from the
 .I cmp
diff --git a/bzgrep.1 b/bzgrep.1
index 930af8c..54bb31f 100644
--- a/bzgrep.1
+++ b/bzgrep.1
@@ -53,4 +53,10 @@ program to be invoked. For example:
 Charles Levert (charles@comm.polymtl.ca). Adapted to bzip2 by Philippe
 Troin <phil@fifi.org> for Debian GNU/Linux.
 .SH "SEE ALSO"
-grep(1), egrep(1), fgrep(1), bzdiff(1), bzmore(1), bzless(1), bzip2(1)
+.BR grep (1),
+.BR egrep (1),
+.BR fgrep (1),
+.BR bzdiff (1),
+.BR bzmore (1),
+.BR bzless (1),
+.BR bzip2 (1)
diff --git a/bzmore.1 b/bzmore.1
index b437d3b..9850948 100644
--- a/bzmore.1
+++ b/bzmore.1
@@ -149,4 +149,8 @@ except that a header is printed before each file.
 .DT
 /etc/termcap		Terminal data base
 .SH "SEE ALSO"
-more(1), less(1), bzip2(1), bzdiff(1), bzgrep(1)
+.BR more (1),
+.BR less (1),
+.BR bzip2 (1),
+.BR bzdiff (1),
+.BR bzgrep (1)
-- 
2.30.2

Re: Errors in man pages of bzip2

[Helge Kreutzmann]

[-- Attachment #1: Type: text/plain, Size: 1449 bytes --]

Hello Mark,
On Thu, Apr 21, 2022 at 01:04:28AM +0200, Mark Wielaard wrote:
> On Wed, Apr 20, 2022 at 04:44:27PM +0200, Helge Kreutzmann wrote:
> > On Tue, Apr 19, 2022 at 11:36:50PM +0200, Mark Wielaard wrote:
> > > On Sat, Feb 05, 2022 at 11:35:40AM +0100, Helge Kreutzmann wrote:
> > > If you could file future issues in bugzilla:
> > > https://sourceware.org/bugzilla/enter_bug.cgi?product=bzip2
> > > Then there is an archive. But sending reports to this list is also
> > > fine.
> > 
> > I can do this; however in February I was told by Micah Snyder to use
> > https://gitlab.com/groups/bzip2/-/issues
> > 
> > Is the sourcware bugzilla now preferred?
> 
> I guess the coordination between the projects isn't ideal.  But yes,
> for stable bzip2 1.0.x, which is what distros ship, sourceware is
> preferred. The gitlab project is working on an experimental 1.1
> version and rust translation.

Thanks for the clarification. I added the sourceware bugzilla to our
configuration for bzip2. So if any translator should find something
else, I'll report it there.

Also thanks for handling the update.

Greetings

           Helge
-- 
      Dr. Helge Kreutzmann                     debian@helgefjell.de
           Dipl.-Phys.                   http://www.helgefjell.de/debian.php
        64bit GNU powered                     gpg signed mail preferred
           Help keep free software "libre": http://www.ffii.de/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]