Manual (man) pages are outdated

[MestreLion]

man pages for the command-line tools boinc, boinccmd and boincmgr are outdated, missing newer options and still listing removed ones. A quick comparison with their respective --help shows many differences. A few examples:

boinccmd
 --get_cc_status : missing from man

boincmgr
  -s, --systray : mentioned in man, does not exist anymore
  - several new options missing from man

boinc
  --help shows 43 options, man lists only 21!

Also, some options are interdependent between tools and deserve extra clarification in manual. Like:

boinc --launched_by_manager
              core client was launched by Manager
boincmgr --boincargs=BOINC_ARGS
              Startup BOINC with these optional arguments.

... so do I have to issue boincmgr --boincargs=--launched_by_manager ??? This hardly makes any sense. Besides, why would boinc care if it was started by manager or not?

Also:

boincmgr -a, --autostart BOINC Manager was started by the operating system automatically

Again, why would manager care? And what exactly "started by the operating system automatically" means? Gnome's "Startup Applications"? Something else?

man pages really need some love :)

[Dave (xclusive585)]

Strangely boinc cares very much who launched it. And if you add a project
as one user, and another user launches boinc in the future, even the
daemon, it won't go well.

Lately the New versions, as long as you launch boincmgr from your desktop
environment it will properly connect to the daemon.

I don't know if this behavior is specific to the debian/ubuntu build, or if
it's like this upstream as well.

-Dave
On Mar 2, 2013 2:45 PM, "MestreLion" <email address hidden> wrote:

> Public bug reported:
>
> man pages for the command-line tools boinc, boinccmd and boincmgr are
> outdated, missing newer options and still listing removed ones. A quick
> comparison with their respective --help shows many differences. A few
> examples:
>
> boinccmd
> --get_cc_status : missing from man
>
> boincmgr
> -s, --systray : mentioned in man, does not exist anymore
> - several new options missing from man
>
> boinc
> --help shows 43 options, man lists only 21!
>
> Also, some options are interdependent between tools and deserve extra
> clarification in manual. Like:
>
> boinc --launched_by_manager
> core client was launched by Manager
> boincmgr --boincargs=BOINC_ARGS
> Startup BOINC with these optional arguments.
>
> ... so do I have to issue boincmgr --boincargs=--launched_by_manager
> ??? This hardly makes any sense. Besides, why would boinc care if it was
> started by manager or not?
>
> Also:
>
> boincmgr -a, --autostart BOINC Manager was started by the
> operating system automatically
>
> Again, why would manager care? And what exactly "started by the
> operating system automatically" means? Gnome's "Startup Applications"?
> Something else?
>
> man pages really need some love :)
>
> ** Affects: boinc (Ubuntu)
> Importance: Undecided
> Status: New
>
>
> ** Tags: manpage
>
> --
> You received this bug notification because you are a member of Debian
> BOINC Maintainers, which is subscribed to boinc in Ubuntu.
> https://bugs.launchpad.net/bugs/1140560
>
> Title:
> Manual (man) pages are outdated
>
> To manage notifications about this bug go to:
> https://bugs.launchpad.net/ubuntu/+source/boinc/+bug/1140560/+subscriptions
>
> --
> pkg-boinc-devel mailing list
> <email address hidden>
> http://lists.alioth.debian.org/cgi-bin/mailman/listinfo/pkg-boinc-devel
>

[Gianfranco Costamagna (costamagnagianfranco)]

The page describing the man is here
doc/manpages/boinc.xml

is handled by upstream people, even if written by Steffen Moeller, the debian mantainer.

So patches are welcome, or maybe feel free to open an upstream ticket

[MestreLion (mestrelion)]

@LocusOfBorg: My Groff/Nroff skills are quite limited, so its better I don't touch the manpages myself. Besides, I lack the knowledge to properly explain some of the "trickier" options like boincmgr --autostart and boinc --launched_by_manager

I would gladly report it upstream, tho... directions please?

[Gianfranco Costamagna (costamagnagianfranco)]

http://boinc.berkeley.edu/trac/newticket

but I think is better to directly ask to Steffen Moeller

[ChristianB (djangofett)]

I already updated the pages. Whoever is interested in proof-reading can drop me a message. I will send them to upstream in the next days.

[ChristianB (djangofett)]

For the record: a fix to this was introduced in upstream today. This issue can be closed with the next package release.

[Gianfranco Costamagna (costamagnagianfranco)]

I already saw this commit, waiting for a .56 release (I won't update to .55 because there is only one fix in xml parsing inside)

[Gianfranco Costamagna (costamagnagianfranco)]

I'm uploading .56 release in my ppa right now.

[Launchpad Janitor (janitor)]

This bug was fixed in the package boinc - 7.0.65+dfsg-1

---------------
boinc (7.0.65+dfsg-1) unstable; urgency=low

  [ Gianfranco Costamagna ]
  * New upstream release.
  * debian/control.in dropped version check
      - pkg-config (>= 0.15) (version 0.25 in stable)
      - autoconf (>= 2.59) (version 2.67 in stable)
      - automake1.9 (>= 1.9.3) (version 1.9.6 in stable)
      - libcurl4-openssl-dev (>= 7.17.1) (version 7.21.0 in stable)
      - python (>= 2.3) (version 2.6.6 in stable)
      - Breaks: udev (<< 136-1) (version 164 in stable)
      - removed boinc-app-seti from boinc-client Suggests field
      - Bumped debhelper required version to 8
    debian/compat
      - Bumped to version 8

  [ Steffen Moeller ]
  * Merged work on packaging of BOINC server code
  * boinc-cgi-stripchart package now built together with server parts

 -- Gianfranco Costamagna <email address hidden> Tue, 30 Apr 2013 21:45:44 +0200