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:
> 	 http://bugzilla.gnome.org/ * 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 :
> 
> SYNOPSIS :
> * 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
other.

> DESCRIPTION
> 	 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
>    http://packages.debian.org/testing/gnome/balsa
> 
> OPTIONS
> -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
Center".

> -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
> 
> SUGGESTIONS AND BUG REPORTS
> 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 ?
> 
> AUTHORS
> 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.

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

http://lists.debian.org/debian-legal/1999/08/msg00045.html

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

Yours sincerely,
Andrew "Netsnipe" Lau

-- 
---------------------------------------------------------------------------
	Andrew "Netsnipe" Lau	<http://www.cse.unsw.edu.au/~alau/>
 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]