public inbox for bzip2-devel@sourceware.org
 help / color / mirror / Atom feed
* Errors in man pages of bzip2
@ 2022-02-05 10:35 Helge Kreutzmann
  2022-04-19 21:36 ` Mark Wielaard
  0 siblings, 1 reply; 5+ messages in thread
From: Helge Kreutzmann @ 2022-02-05 10:35 UTC (permalink / raw)
  To: bzip2-devel

[-- 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 --]

^ permalink raw reply	[flat|nested] 5+ messages in thread

* Re: Errors in man pages of bzip2
  2022-02-05 10:35 Errors in man pages of bzip2 Helge Kreutzmann
@ 2022-04-19 21:36 ` Mark Wielaard
  2022-04-20 14:44   ` Helge Kreutzmann
  0 siblings, 1 reply; 5+ messages in thread
From: Mark Wielaard @ 2022-04-19 21:36 UTC (permalink / raw)
  To: Helge Kreutzmann; +Cc: bzip2-devel

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


^ permalink raw reply	[flat|nested] 5+ messages in thread

* Re: Errors in man pages of bzip2
  2022-04-19 21:36 ` Mark Wielaard
@ 2022-04-20 14:44   ` Helge Kreutzmann
  2022-04-20 23:04     ` Mark Wielaard
  0 siblings, 1 reply; 5+ messages in thread
From: Helge Kreutzmann @ 2022-04-20 14:44 UTC (permalink / raw)
  To: Mark Wielaard; +Cc: bzip2-devel

[-- 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 --]

^ permalink raw reply	[flat|nested] 5+ messages in thread

* Re: Errors in man pages of bzip2
  2022-04-20 14:44   ` Helge Kreutzmann
@ 2022-04-20 23:04     ` Mark Wielaard
  2022-04-21 15:47       ` Helge Kreutzmann
  0 siblings, 1 reply; 5+ messages in thread
From: Mark Wielaard @ 2022-04-20 23:04 UTC (permalink / raw)
  To: Helge Kreutzmann; +Cc: bzip2-devel

[-- 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


^ permalink raw reply	[flat|nested] 5+ messages in thread

* Re: Errors in man pages of bzip2
  2022-04-20 23:04     ` Mark Wielaard
@ 2022-04-21 15:47       ` Helge Kreutzmann
  0 siblings, 0 replies; 5+ messages in thread
From: Helge Kreutzmann @ 2022-04-21 15:47 UTC (permalink / raw)
  To: Mark Wielaard; +Cc: bzip2-devel

[-- 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 --]

^ permalink raw reply	[flat|nested] 5+ messages in thread

end of thread, other threads:[~2022-04-21 15:47 UTC | newest]

Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2022-02-05 10:35 Errors in man pages of bzip2 Helge Kreutzmann
2022-04-19 21:36 ` Mark Wielaard
2022-04-20 14:44   ` Helge Kreutzmann
2022-04-20 23:04     ` Mark Wielaard
2022-04-21 15:47       ` Helge Kreutzmann

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).