Bug#817959: bsdmainutils: [cal] The -M and -S options do not work

[Michael Meskes]

> I think that the cause may be the fact that a same man page for two
> different user commands is very unusual. Having two different man
> pages (possibly generated from the same source) would be better,
> IMHO.

You're free to submit a patch.

Michael
-- 
Michael Meskes
Michael at Fam-Meskes dot De, Michael at Meskes dot (De|Com|Net|Org)
Meskes at (Debian|Postgresql) dot Org
Jabber: michael at xmpp dot meskes dot org
VfL Borussia! Força Barça! Go SF 49ers! Use Debian GNU/Linux, PostgreSQL

Bug#817959: bsdmainutils: [cal] The -M and -S options do not work

[Vincent Lefevre]

On 2016-03-15 19:43:12 +0100, Michael Meskes wrote:
> On Sun, Mar 13, 2016 at 07:48:14PM +0100, Vincent Lefevre wrote:
> > According to the synopsis, "ncal -ej" is invalid because the option -e
> > is listed only in the second ncal line while the option -j is listed
> > only in the first ncal line. However, it doesn't fail:
> > 
> > $ ncal -ej
> > March 27 2016
> > 
> > Ditto with other combinations between {e,o} and {j,p,w,y}.
> 
> Right, the synopsis here essentially shows which options make sense together.
> If you specify a combination that is not listed one will not have an effect.

It would be better to get an error in such a case.

Back to the man page, it seems that I'm not the only one to find
it confusing. I've just found that a few hours after reported this
bug, some other user thought that the -M option was valid for cal,
after looking at the man page:

  https://lists.debian.org/debian-user-french/2016/03/msg00176.html

I think that the cause may be the fact that a same man page for two
different user commands is very unusual. Having two different man
pages (possibly generated from the same source) would be better, IMHO.

-- 
Vincent Lefèvre  - Web: 
100% accessible validated (X)HTML - Blog: 
Work: CR INRIA - computer arithmetic / AriC project (LIP, ENS-Lyon)

Bug#817959: bsdmainutils: [cal] The -M and -S options do not work

[Michael Meskes]

On Sun, Mar 13, 2016 at 07:48:14PM +0100, Vincent Lefevre wrote:
> I see that there have been various fixes, but the DESCRIPTION section
> says:
> 
>  -N  Switch to ncal mode.
> 
> while this option is no longer listed anywhere in the synopsis. It
> seems that it has been removed, so that it should be removed from
> the DESCRIPTION section.

Correct, this one I missed. Thanks. Fixed in git already. Next upload will be 
correct.

> According to the synopsis, "ncal -ej" is invalid because the option -e
> is listed only in the second ncal line while the option -j is listed
> only in the first ncal line. However, it doesn't fail:
> 
> $ ncal -ej
> March 27 2016
> 
> Ditto with other combinations between {e,o} and {j,p,w,y}.

Right, the synopsis here essentially shows which options make sense together.
If you specify a combination that is not listed one will not have an effect.

> Moreover, "cal -C" doesn't fail (which is consistent with the Usage
> message) but the -C option is not listed in the cal lines.

Right, because "cal" = "ncal -C", so it's just a noop.

Michael
-- 
Michael Meskes
Michael at Fam-Meskes dot De, Michael at Meskes dot (De|Com|Net|Org)
Meskes at (Debian|Postgresql) dot Org
Jabber: michael at xmpp dot meskes dot org
VfL Borussia! Força Barça! Go SF 49ers! Use Debian GNU/Linux, PostgreSQL

Bug#817959: bsdmainutils: [cal] The -M and -S options do not work

[Vincent Lefevre]

On 2016-03-13 18:33:19 +0100, Michael Meskes wrote:
> > > > The synopsis in a man page is not meant to list all options.
> > > Written down somewhere, or just your opinion?
> > From what I can see on other man pages (e.g., find, cp, mkdir).
> 
> Na, not at all. All of these make it explicitly clear that they do not
> list all options, or better, just list the meta word OPTION. Quite a
> different situation, is it not?

Not the find(1) man page. For the cp(1) and mkdir(1) man pages,
the issue is not the options, but the arguments. For instance,
"cp --version" does not match any synopsis line.

> > I'll try, but there was a severe regression according to some
> > other bug.
> 
> Depends on how you define "severe" I guess, but anyway, fixed since
> yesterday.

Now, with the current version bsdmainutils 9.0.8, the synopsis is:

 cal [-31jy] [-A number] [-B number] [-d -mm] [[month] year]
 cal [-31j] [-A number] [-B number] [-d -mm] -m month [year]
 ncal [-C31bhjJpwySM] [-A number] [-B number] [-H -mm-dd] [-d -mm]
 [-s country_code] [[month] year]
 ncal [-C31bhJeoSM] [-A number] [-B number] [-d -mm] [year]

I see that there have been various fixes, but the DESCRIPTION section
says:

 -N  Switch to ncal mode.

while this option is no longer listed anywhere in the synopsis. It
seems that it has been removed, so that it should be removed from
the DESCRIPTION section.

According to the synopsis, "ncal -ej" is invalid because the option -e
is listed only in the second ncal line while the option -j is listed
only in the first ncal line. However, it doesn't fail:

$ ncal -ej
March 27 2016

Ditto with other combinations between {e,o} and {j,p,w,y}.

Moreover, "cal -C" doesn't fail (which is consistent with the Usage
message) but the -C option is not listed in the cal lines.

-- 
Vincent Lefèvre  - Web: 
100% accessible validated (X)HTML - Blog: 
Work: CR INRIA - computer arithmetic / AriC project (LIP, ENS-Lyon)

Bug#817959: bsdmainutils: [cal] The -M and -S options do not work

[Michael Meskes]

> > > The synopsis in a man page is not meant to list all options.
> > Written down somewhere, or just your opinion?
> From what I can see on other man pages (e.g., find, cp, mkdir).

Na, not at all. All of these make it explicitly clear that they do not
list all options, or better, just list the meta word OPTION. Quite a
different situation, is it not?

> > Before we continue, please update to the latest version which does
> > has some
> > fixed to both these points.
> I'll try, but there was a severe regression according to some
> other bug.

Depends on how you define "severe" I guess, but anyway, fixed since
yesterday.

Michael
-- 
Michael Meskes
Michael at Fam-Meskes dot De, Michael at Meskes dot (De|Com|Net|Org)
Meskes at (Debian|Postgresql) dot Org
Jabber: michael at xmpp dot meskes dot org
VfL Borussia! Força Barça! SF 49ers! Use Debian GNU/Linux, PostgreSQL

Bug#817959: bsdmainutils: [cal] The -M and -S options do not work

[Vincent Lefevre]

On 2016-03-12 12:53:37 +0100, Michael Meskes wrote:
> On Sat, Mar 12, 2016 at 11:52:57AM +0100, Vincent Lefevre wrote:
> > The synopsis in a man page is not meant to list all options.
> 
> Written down somewhere, or just your opinion?

>From what I can see on other man pages (e.g., find, cp, mkdir).

[...]
> Before we continue, please update to the latest version which does has some
> fixed to both these points.

I'll try, but there was a severe regression according to some
other bug.

-- 
Vincent Lefèvre  - Web: 
100% accessible validated (X)HTML - Blog: 
Work: CR INRIA - computer arithmetic / AriC project (LIP, ENS-Lyon)

Bug#817959: bsdmainutils: [cal] The -M and -S options do not work

[Michael Meskes]

On Sat, Mar 12, 2016 at 11:52:57AM +0100, Vincent Lefevre wrote:
> Control: reopen -1
> Control: retitle -1 bsdmainutils: incomplete cal(1) man page

Seriously? I don't really like bts ping pong.

> The synopsis in a man page is not meant to list all options.

Written down somewhere, or just your opinion? Isn't the synopsis meant to show
how the options are listed etc.?

> Sometimes, only the main options are listed. Actually this is even

Can you back your claim with an example? 

> the case here. For instance:

Not exactly, your example is a bug that was since fixed.

> Moreover, contrary to what the synopsis and Usage output say,
> "ncal -ej" is invalid. But it doesn't return any error.

This statement I do not understand at all. Please elaborate.

> Even if the synopsis is completed, the description should say that
> not all options apply to cal and one should refer to the synopsis
> (if completed).

Why? Again, it's already in there so why put it down again? Can you show me
other manpages that do exactly as you say?

> Also, the synopsis is not very clear. For instance:
> ...

Before we continue, please update to the latest version which does has some
fixed to both these points.

There may be more in there and I'm more than willing to fix bugs, but the one
this bug report is about is none. 

Michael
-- 
Michael Meskes
Michael at Fam-Meskes dot De, Michael at Meskes dot (De|Com|Net|Org)
Meskes at (Debian|Postgresql) dot Org
Jabber: michael at xmpp dot meskes dot org
VfL Borussia! Força Barça! Go SF 49ers! Use Debian GNU/Linux, PostgreSQL

Bug#817959: bsdmainutils: [cal] The -M and -S options do not work

[Vincent Lefevre]

Control: reopen -1
Control: retitle -1 bsdmainutils: incomplete cal(1) man page

On 2016-03-12 11:01:46 +0100, Michael Meskes wrote:
> On Sat, Mar 12, 2016 at 04:32:11AM +0100, Vincent Lefevre wrote:
> > According to the cal(1) man page:
> > 
> >  -M  Weeks start on Monday.
> > 
> >  -S  Weeks start on Sunday.
> 
> Please check the synopsis too:
> 
> cal [-31jy] [-A number] [-B number] [-d -mm] [[month] year]
> cal [-31j] [-A number] [-B number] [-d -mm] -m month [year]
> ncal [-C31bhjJpwySM] [-A number] [-B number] [-H -mm-dd] [-d -mm]
>  [-s country_code] [[month] year]
> ncal [-C31bhJeoSM] [-A number] [-B number] [-d -mm] [year]
> 
> As you can see no -S or -M listed with cal.

The synopsis in a man page is not meant to list all options.
Sometimes, only the main options are listed. Actually this is even
the case here. For instance:

$ cal --help
cal: invalid option -- '-'
Usage: cal [general options] [-hjy] [[month] year]
   cal [general options] [-hj] [-m month] [year]
   ncal [general options] [-bhJjpwySM] [-s country_code] [[month] year]
   ncal [general options] [-bhJeoSM] [year]
General options: [-NC31] [-A months] [-B months]
For debug the highlighting: [-H -mm-dd] [-d -mm]

So, it appears that there is an option -N valid for cal, but not
listed in the synopsis (though listed in the description).

Moreover, contrary to what the synopsis and Usage output say,
"ncal -ej" is invalid. But it doesn't return any error.

Even if the synopsis is completed, the description should say that
not all options apply to cal and one should refer to the synopsis
(if completed).

Also, the synopsis is not very clear. For instance:

$ ncal -CJ
Usage: cal [general options] [-hjy] [[month] year]
   cal [general options] [-hj] [-m month] [year]
   ncal [general options] [-bhJjpwySM] [-s country_code] [[month] year]
   ncal [general options] [-bhJeoSM] [year]
General options: [-NC31] [-A months] [-B months]
For debug the highlighting: [-H -mm-dd] [-d -mm]

If I understand correctly, it should say something like on separate
lines:

  cal -N [ncal options and arguments]
  ncal -C [cal options and arguments]

BTW, in the Usage output, shouldn't the options -h and -j be moved
to the general options?

-- 
Vincent Lefèvre  - Web: 
100% accessible validated (X)HTML - Blog: 
Work: CR INRIA - computer arithmetic / AriC project (LIP, ENS-Lyon)

Bug#817959: bsdmainutils: [cal] The -M and -S options do not work

[Vincent Lefevre]

Package: bsdmainutils
Version: 9.0.6+b1
Severity: normal

According to the cal(1) man page:

 -M  Weeks start on Monday.

 -S  Weeks start on Sunday.

But:

zira% cal -M
Usage: cal [general options] [-hjy] [[month] year]
   cal [general options] [-hj] [-m month] [year]
   ncal [general options] [-bhJjpwySM] [-s country_code] [[month] year]
   ncal [general options] [-bhJeoSM] [year]
General options: [-NC31] [-A months] [-B months]
For debug the highlighting: [-H -mm-dd] [-d -mm]
zira% cal -S
Usage: cal [general options] [-hjy] [[month] year]
   cal [general options] [-hj] [-m month] [year]
   ncal [general options] [-bhJjpwySM] [-s country_code] [[month] year]
   ncal [general options] [-bhJeoSM] [year]
General options: [-NC31] [-A months] [-B months]
For debug the highlighting: [-H -mm-dd] [-d -mm]
zira% 

-- System Information:
Debian Release: stretch/sid
  APT prefers unstable-debug
  APT policy: (500, 'unstable-debug'), (500, 'stable-updates'), (500, 
'unstable'), (500, 'testing'), (500, 'stable'), (1, 'experimental')
Architecture: amd64 (x86_64)

Kernel: Linux 4.4.0-1-amd64 (SMP w/8 CPU cores)
Locale: LANG=POSIX, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash
Init: systemd (via /run/systemd/system)

Versions of packages bsdmainutils depends on:
ii  bsdutils 1:2.27.1-4
ii  debianutils  4.7
ii  libc62.22-2
ii  libncurses5  6.0+20160213-1
ii  libtinfo56.0+20160213-1

bsdmainutils recommends no packages.

Versions of packages bsdmainutils suggests:
ii  cpp   4:5.3.1-1
pn  vacation  
ii  wamerican [wordlist]  7.1-1
ii  whois 5.2.11

-- no debconf information