Re: Bug#269787: manpage improvements ?

On Fri, Sep 03, 2004 at 03:40:58PM +0200, Siward de Groot wrote:
> Package: balsa
> Version: 2.0.17-2
> Severity: minor
> Title  : manpage improvements ?
> balsa::help::about :
> 	 The Balsa email client is part of the GNOME desktop  
> environment.
> * i am not using gnome desktop, but i am using balsa,
>    so maybe word 'suite' should be in here somewhere ?

Well the GNOME website seems to use both terms interchangeably.

> 	 If you need to report bugs, please do so at:
> * not use debian's bts ?

There's no difference really. If there's a bug I can't handle it gets
forwarded upstream anyway. Reporting bugs via Bugzilla (and bug-buddy)
reduces the turn-around time if the bug in question isn't a Debian
packaging problem.

> balsa::help::contents :
> * clicking it does nothing, statusbar says nothing about it,
>  pressing F1 gives same result

Do you have the yelp package installed? It is the GNOME Help browser. I
may have to include a dependency/suggest for it in future.

> ----------------------------------------------------------------------
> man balsa :
> * this is not a synopsis (see dict synopsis).
>  although word 'synopsis' is used in many manpages,
>  it is a bit too much to expect of newbie users to be able to
>    use a syntax-description as a synopsis.
>  maybe s/synopsis/syntax/i ?

It's a convention nevertheless. Yelp provides the friendlier help.

> * format is not easy to read,
>  in my local form, it currently looks like :
> 	 balsa							  \
> 	   [       --help					] \
> 	   [       --version					] \
> 	   [  -c | --checkmail					] \
> 	   [ (-m | --compose=)(<user>@<host>.<tld>|<url>)	] \
> 	   [ (-a | --attach=)<filename>				] \
> 	   [ (-o | --open-mailbox=)<mailbox>[:<mailbox>]...	] \
> 	   [  -u | --open-unread-mailbox			] \
> 	   [  -d | --debug-pop					]
>  maybe you like this format too ?

That's also a manpage convention. Traditionally, options are placed on
separate lines when they can only be used mutually exclusive from each

> 	 Balsa is an e-mail reader.
> * it is also a writer.
>  (if 'e-mail reader' is a generic term for a mua,
>   then please disregard this remark)

Good point. "e-mail client" perhaps?

> 	 This client is part of GNOME desktop environment.
> * same as in helptext
> * inexperienced newbies might not understand short word 'client' here.
>  is it really necessary or otherwise desirable ?

I believe the term client is widespread enough not to cause confusion.

> 	 For help on using Balsa,
> 	   see program documentation in help menu.
> * not available, as noted above
> * in my local copy, i have added packagedescription from
> -m --compose=USER HOST TLD
> 	 When invoked with this option, balsa
> 	   open a new message with specified address in To: field.
> 	 Parameter can be specified also in URL format,
> 	   it makes it possible to use balsa as mailto protocol handler
> 	   by setting mailto protocol command to balsa -m "%s"
> 	     in URL handlers section of GNOME control center.
> * what is tld ?

Top level domain. e.g. .com, .org, .net, .au, .uk
I can see how that might be confusing to some newbies.

> * url form of command is not shown in syntaxdescription

"URL handlers section of GNOME control center." should be probably be
replaced with "the Preferred Applications section of the GNOME Control

> -o --open-mailbox=MAILBOX
> 	 Makes Balsa open specified mailbox(es) at startup.
> 	 Multiple mailboxes are delimited by semicolons.
> * possibility of multiple arguments is not shown in syntaxdescription
> Any bugs found should be reported to Balsa Developer mailing list
> * (again) not use bts ?
> Before reporting bugs,
>   please check if bug is mentioned in FAQ's or mailing list archive.
> * not check bugs in debian's bts? not use reportbug?
> See section on Other Info for locations of these.
> * where can i find that section ?
> See AUTHORS file included with Balsa,
>   probably at /usr/share/doc/balsa-2.0.17/AUTHORS
> * actually at /usr/share/doc/balsa/AUTHORS

Siward is right. Balsa's Makefiles long stopped appending a version
number to the documentation subdirectory.

> Permission to use, copy, modify, and distribute
>   this software and its documentation
>   for any purpose and without fee
>   is hereby granted,
> * 'without fee' restriction looks technically nonfree to me,
>   as it seems to forbid redistribution-for-a-fee ;
>   maybe ask upstream to be clearer about it ?

A consensus was reached years ago that "without fee" meant without a fee
(royalty) to the author (copyright holder).

Thanks for the comments. I've forwarded the rest to upstream for their

Yours sincerely,
Andrew "Netsnipe" Lau

	Andrew "Netsnipe" Lau	<>
 Debian GNU/Linux Maintainer & UNSW Computing Students' Society President
		  "Nobody expects the Debian Inquisition!
     Our two weapons are fear and surprise...and ruthless efficiency!"

Attachment: signature.asc
Description: Digital signature

[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]