Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.debian.bugs.dist > #1188892 > unrolled thread

Bug#1065356: Issues in man pages of cron

Back to article view | Back to linux.debian.bugs.dist

Contents

  Bug#1065356: Issues in man pages of cron Helge Kreutzmann <debian@helgefjell.de> - 2024-03-03 12:10 +0100
    Bug#1065356: Issues in man pages of cron Georges Khaznadar <georges.khaznadar@free.fr> - 2024-03-03 19:00 +0100
      Bug#1065356: Issues in man pages of cron Helge Kreutzmann <debian@helgefjell.de> - 2024-03-03 20:00 +0100
        Bug#1065356: Issues in man pages of cron Georges Khaznadar <georges.khaznadar@free.fr> - 2024-03-04 11:50 +0100
          Bug#1065356: Issues in man pages of cron Helge Kreutzmann <debian@helgefjell.de> - 2024-03-04 18:40 +0100

#1188892 — Bug#1065356: Issues in man pages of cron

[Multipart message — attachments visible in raw view] — view raw

Package: cron
Version: 3.0pl1-186
Severity: minor
Tags: patch
X-Debbugs-CC: mario.blaettermann@gmail.com

Dear Debian cron maintainer,
the manpage-l10n project maintains a large number of translations of
man pages both from a large variety of sources (including cron) 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.

(Btw., do you have a working e-mail address of upstream?)

Man page: cron.8
Issue:    B<-L loglevel> → B<-L> I<loglevel>

"B<-L loglevel>"
--
Man page: crontab.1
Issue 1:  I<-h> → B<-h>
Issue 2:  I<crontab> → B<crontab>

"If the I<-h> option is given, I<crontab> shows a help message and quits "
"immediately."
--
Man page: crontab.1
Issue 1:  I<-h> → B<-h>
Issue 2:  I<crontab> → B<crontab>

"If the I<-n> option is given, it means \"dry run\": I<crontab> examines "
"\"your\" crontab for its syntax, and outputs a success message if this "
"syntax is correct, but nothing is written to any crontab."
--
Man page: crontab.1
Issue:    if, they exist, →  , if they exist,

"The files I</etc/cron.allow> and I</etc/cron.deny> if, they exist, must be "
"either world-readable, or readable by group ``crontab''. If they are not, "
"then cron will deny access to all users until the permissions are fixed."
--
Man page: crontab.1
Issue:    crontab(5), cron(8), spc(1) → B<crontab>(5), B<cron>(8), B<spc>(1)

"crontab(5), cron(8), spc(1)"
--
Man page: crontab.5
Issue:    I<su> → B<su>

"A I<crontab> file contains instructions to the I<cron>(8)  daemon of the "
"general form: ``run this command at this time on this date''.  Each user has "
"their own crontab, and commands in any given crontab will be executed as the "
"user who owns the crontab.  Uucp and News will usually have their own "
"crontabs, eliminating the need for explicitly running I<su>(1)  as part of a "
"cron command."
--
Man page: crontab.5
Issue:    LOGNAME → I<LOGNAME>

"Several environment variables are set up automatically by the I<cron>(8)  "
"daemon.  SHELL is set to /usr/bin/sh, and LOGNAME and HOME are set from the /"
"etc/passwd line of the crontab's owner.  HOME and SHELL may be overridden by "
"settings in the crontab; LOGNAME may not."
--
Man page: crontab.5
Issue:    I<ncal> or I<calendar> For → B<ncal>(1) or B<calendar>(1). For

"If the program itself cannot do the checks then a wrapper script would be "
"required.  Useful tools that could be used for date analysis are I<ncal> or "
"I<calendar> For example, to run a program the last Saturday of every month "
"you could use the following wrapper code:"

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

[toc] | [next] | [standalone]

#1188942

[Multipart message — attachments visible in raw view] — view raw

Dear Helge,

thank you for your detailed bug report.

Helge Kreutzmann a écrit :
> We use several distributions as sources and update regularly (at
> least every 2 month). 

Most changes here are probably specific to Debian; however they will
also apply to Debian derivatives.

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

The original format for Debian's manpages regarding cron is groff.

Unfortunately, it is not the easiest format for human translators, as it
is probably split in small chunks written to PO files, with little
meaning in each of them.

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

Debian bug reports are a valid channel for me.

> (Btw., do you have a working e-mail address of upstream?)

The upstream developer, Paul Vixie, had an e-mail address: paul@vix.com

However, he does no longer maintain cron, and Debian's cron package
comes from a fork, dated "Sun, 1 Dec 1996 16:21:52 -0600".  So, for
twenty eight years now, all of the development was made by various
debian developers, and is structured as a heap of 84 patches
(see the file
https://salsa.debian.org/debian/cron/-/blob/master/debian/patches/series?ref_type=heads)

Regarding the issues listed below, I do not fully understand the syntax.

If I consider the very first issue:
> 
> Man page: cron.8
> Issue:    B<-L loglevel> → B<-L> I<loglevel>
> 
> "B<-L loglevel>"
> --

and take a look at the manpage, which is in groff format, I can find some
matching line:

------------------------8<-------------------------------
$ zgrep loglevel /usr/share/man/man8/cron.8.gz 
.IR loglevel ]
.B \-L loglevel
------------------------8<-------------------------------

The last line (in groff) means: write "-L loglevel" with a bold font.
This probably has the same meaning as the line "B<-L loglevel>" in the
snipped above.

So how can I help? can I answer that the line "B<-L loglevel>" is the
current valid source for localizations?

Now let us consider the next issues:

> Man page: crontab.1
> Issue 1:  I<-h> → B<-h>
> Issue 2:  I<crontab> → B<crontab>
> 
> "If the I<-h> option is given, I<crontab> shows a help message and quits "
> "immediately."
> --


How can I help? Here is the match which I can find:

------------------------8<-------------------------------
zgrep -- -h  /usr/share/man/man1/crontab.1.gz 
crontab [ \-h]
.I \-h
------------------------8<-------------------------------

The last line (in groff format) would probably match Issue 1 above,
however once again I do not guess how I can help.

It would probably be a waste of energy to discuss now all and every
issue you sent me. Maybe we can first agree about a method to make the
task easier for both of us, and for the many contributors to translation
teams.

Please can you suggest me one or more techniques which might improve the
feedback, regarding the simple examples cited above? The main question
is "how can I help?", which can be rephrased as "what kind of answer
would you expect?".

Best regards,			Georges.

[toc] | [prev] | [next] | [standalone]

#1188948

[Multipart message — attachments visible in raw view] — view raw

Hello Georges,
Am Sun, Mar 03, 2024 at 06:37:25PM +0100 schrieb Georges Khaznadar:
> thank you for your detailed bug report.

You are welcome.

> Helge Kreutzmann a écrit :
> > We use several distributions as sources and update regularly (at
> > least every 2 month). 
> 
> Most changes here are probably specific to Debian; however they will
> also apply to Debian derivatives.

Yes, given that I could not reach upstream, I only reported those
issues which were actually present in the Debian version. I don't know
when and how I can report the rest.

> > 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.
> 
> The original format for Debian's manpages regarding cron is groff.

That's usual, but po4a transforms this in a more friendly format for
us translators.

> Unfortunately, it is not the easiest format for human translators, as it
> is probably split in small chunks written to PO files, with little
> meaning in each of them.

That's fine, don't worry. If in doubt we can always build the full
translated page and read it for consisteny. And small paragraphs are
usually better to handle and, potentially, reuse.

> > (Btw., do you have a working e-mail address of upstream?)
> 
> The upstream developer, Paul Vixie, had an e-mail address: paul@vix.com

Ok, so nothing new.

> However, he does no longer maintain cron, and Debian's cron package
> comes from a fork, dated "Sun, 1 Dec 1996 16:21:52 -0600".  So, for
> twenty eight years now, all of the development was made by various
> debian developers, and is structured as a heap of 84 patches
> (see the file
> https://salsa.debian.org/debian/cron/-/blob/master/debian/patches/series?ref_type=heads)
> 
> Regarding the issues listed below, I do not fully understand the syntax.
> 
> If I consider the very first issue:
> > 
> > Man page: cron.8
> > Issue:    B<-L loglevel> → B<-L> I<loglevel>
> > 
> > "B<-L loglevel>"
> > --
> 
> and take a look at the manpage, which is in groff format, I can find some
> matching line:
> 
> ------------------------8<-------------------------------
> $ zgrep loglevel /usr/share/man/man8/cron.8.gz 
> .IR loglevel ]
> .B \-L loglevel
> ------------------------8<-------------------------------
> 
> The last line (in groff) means: write "-L loglevel" with a bold font.
> This probably has the same meaning as the line "B<-L loglevel>" in the
> snipped above.

Yes, and this is what should be corrected.

> So how can I help? can I answer that the line "B<-L loglevel>" is the
> current valid source for localizations?

I'm not very good (if at all) at groff, by I think
the following might work:
.B \-L
.I loglevel

or even
.BI \-L loglevel

> Now let us consider the next issues:
> 
> > Man page: crontab.1
> > Issue 1:  I<-h> → B<-h>
> > Issue 2:  I<crontab> → B<crontab>
> > 
> > "If the I<-h> option is given, I<crontab> shows a help message and quits "
> > "immediately."
> > --
> 
> 
> How can I help? Here is the match which I can find:
> 
> ------------------------8<-------------------------------
> zgrep -- -h  /usr/share/man/man1/crontab.1.gz 
> crontab [ \-h]
> .I \-h
> ------------------------8<-------------------------------
> 
> The last line (in groff format) would probably match Issue 1 above,
> however once again I do not guess how I can help.

You put it in Italics, but the convention (see man-pages(7) and
man(7)) is to use bold, so this one is simply:

.B \-h

> It would probably be a waste of energy to discuss now all and every
> issue you sent me. Maybe we can first agree about a method to make the
> task easier for both of us, and for the many contributors to translation
> teams.

I hope this explains it. 

> Please can you suggest me one or more techniques which might improve the
> feedback, regarding the simple examples cited above? The main question
> is "how can I help?", which can be rephrased as "what kind of answer
> would you expect?".

First thanks for your ultra fast response - this is extraordinary
help already. And for your verbose questions, which make it easier for
me to respond.

I think most of the report boils down that you update the patches by
using .B instead of .I or sometimes .BI

I hope this explains it better.

Greetings

           Helge

P.S. And since there is probably little changes in cron nowadays, most
     likely few if none further reports from my side…

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

[toc] | [prev] | [next] | [standalone]

#1189021

[Multipart message — attachments visible in raw view] — view raw

Hello Helge,

Helge Kreutzmann a écrit :

> > > 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.
> > 
> > The original format for Debian's manpages regarding cron is groff.

Would the translators' work become easier if the manpages were rewritten
in some higher-level language than groff? I must admit that I am not at
ease with groff sources, and that I use weird hacks when modifying such
or such part of a manpage when some feature of cron or crontab is
changed.

The source in groff format often contains very short lines, where more
context would be necessary to grasp the sense.

So, please tell me whether it would be useful to rewrite the three
manpages in XML format? 

This would mean writing sensible paragraphs, with lines of seventy or
more characters, containing simple text and elements marked by tags like
<command></command> or <replaceable class="option"></replaceable>, which
convey more sense than the bare bold/italics directives available in
groff.

> That's usual, but po4a transforms this in a more friendly format for
> us translators.

Here is what I understood so far, from the first e-mail you sent me
yesterday, and from the enlightenments provided by the second one:

  Each report chunk is divided in two parts, a list of issues and a
  context string, which I describe below in some wild meta-language
  using square brackets:

  ---------------------------------------------------------------------
  Man page: [source file]
  Issue #n:     [incorrect format] → [fixed format]
  ...

  "[some context, extracted by po4a from the source file]"
  "..."
  --
  ---------------------------------------------------------------------

Please can you confirm or infirm that the interpretation above can be
trusted?

> I think most of the report boils down that you update the patches by
> using .B instead of .I or sometimes .BI

This is a particular consequence of a more general guideline, to follow
recommendations provided by `man man-pages`. I would feel more at ease
if this compliance was ensured by an automated process fed by a source
file with high-level syntactic markup.

> P.S. And since there is probably little changes in cron nowadays, most
>      likely few if none further reports from my side…

I began to maintain cron two years ago, and lowered the bug report count
by approximately one half (regarding reports in bugs.debian.org). Some
reports entailed creating new features, and modifying the manuals
accordingly. I fear that the fifty remaining bug reports will slowly,
but surely involve future changes in man pages, so rewriting them in a
high-level language would probably make future changes more consistent.

Please can you consider this proposition? I would rewrite an XML source
for the manpage crontab.1, and send it; then you run your tools
(probably po4a), and send me a feedback to tell me whether I introduced
more inconsistencies than the count of fixes.

Thank you in advance for your response.

Best regards,			Georges

[toc] | [prev] | [next] | [standalone]

#1189059

[Multipart message — attachments visible in raw view] — view raw

Hello Georges,
Am Mon, Mar 04, 2024 at 11:47:03AM +0100 schrieb Georges Khaznadar:
> Helge Kreutzmann a écrit :
> 
> > > > 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.
> > > 
> > > The original format for Debian's manpages regarding cron is groff.
> 
> Would the translators' work become easier if the manpages were rewritten
> in some higher-level language than groff? I must admit that I am not at
> ease with groff sources, and that I use weird hacks when modifying such
> or such part of a manpage when some feature of cron or crontab is
> changed.

Simple answer: No.

In the end, man pages are transformed into groff and this is what we
get, and our toolchain po4a handles it quite nicely. Actually,
translators do not see groff at all, but some pseudo language they are
familiar with. (Thats why I had to double check my groff proposals, I 
hardly see groff except when i discuss the issues in the man pages of 
groff themselves …)

> The source in groff format often contains very short lines, where more
> context would be necessary to grasp the sense.
> 
> So, please tell me whether it would be useful to rewrite the three
> manpages in XML format? 

From my POV it is not necessary. As said earlier, I think the context
is sufficient, translators can always build the entire (translated)
file to check and shorter paragraphs are easier to handle and reuse.

> This would mean writing sensible paragraphs, with lines of seventy or
> more characters, containing simple text and elements marked by tags like
> <command></command> or <replaceable class="option"></replaceable>, which
> convey more sense than the bare bold/italics directives available in
> groff.

In the end, this is up to you and we translators follow suite. Please
note, howver, that not all translations are maintained. Currently we
have (partial) translations for ko, fr, pl, fi, ro, de and id. There
are no active translators for ko, fi and id, and I'm not sure how fast
the translators for fr and pl will pick it up.

So from my POV I would suggest to keep them as is, unless the pain is
really large or you intend to add/update lots of content.

> > That's usual, but po4a transforms this in a more friendly format for
> > us translators.
> 
> Here is what I understood so far, from the first e-mail you sent me
> yesterday, and from the enlightenments provided by the second one:
> 
>   Each report chunk is divided in two parts, a list of issues and a
>   context string, which I describe below in some wild meta-language
>   using square brackets:
> 
>   ---------------------------------------------------------------------
>   Man page: [source file]
>   Issue #n:     [incorrect format] → [fixed format]
>   ...
> 
>   "[some context, extracted by po4a from the source file]"
>   "..."
>   --
>   ---------------------------------------------------------------------
> 
> Please can you confirm or infirm that the interpretation above can be
> trusted?

Yes, this is 100% correct. 

> > I think most of the report boils down that you update the patches by
> > using .B instead of .I or sometimes .BI
> 
> This is a particular consequence of a more general guideline, to follow
> recommendations provided by `man man-pages`. I would feel more at ease
> if this compliance was ensured by an automated process fed by a source
> file with high-level syntactic markup.

Yes, I see your point. And if you were to write this from scratch, I
would suggest doing so.

> > P.S. And since there is probably little changes in cron nowadays, most
> >      likely few if none further reports from my side…
> 
> I began to maintain cron two years ago, and lowered the bug report count
> by approximately one half (regarding reports in bugs.debian.org). Some
> reports entailed creating new features, and modifying the manuals
> accordingly. I fear that the fifty remaining bug reports will slowly,
> but surely involve future changes in man pages, so rewriting them in a
> high-level language would probably make future changes more consistent.

Ok, I see. Then my points from above a moot, if changes are planned or
underway at many places.

Thanks for handling cron without a responsive upstream!

> Please can you consider this proposition? I would rewrite an XML source
> for the manpage crontab.1, and send it; then you run your tools
> (probably po4a), and send me a feedback to tell me whether I introduced
> more inconsistencies than the count of fixes.

No need to do so. Once you have the man pages ready (and I mean the
man pages, not the XML sources) simply ship them. Of course, if you
want I can quickly glance over them to fix obvious oversights, for
this I don't need to involve po4a at all.

However, please note that I'm rather busy with real life atm, at least
through easter. I might perform quick checks if time permits, but
larger issues need to be postponed.

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/

[toc] | [prev] | [standalone]

Back to top | Article view | linux.debian.bugs.dist

csiph-web