Bug#269787: manpage improvements ?

[Siward de Groot]

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 =20
environment.
* i am not using gnome desktop, but i am using balsa,
    so maybe word 'suite' should be in here somewhere ?

	 If you need to report bugs, please do so at: =20
http://bugzilla.gnome.org/
* not use debian's bts ?

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

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

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

 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)

	 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 ?

	 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=3DUSER@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 ?
* url form of command is not shown in syntaxdescription

 -o --open-mailbox=3DMAILBOX
	 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

 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 ?