Bug#269787: ReRe: Bug#269787: manpage improvements ?

[Siward de Groot]

On 09/03/04 16:42:03, Andrew Lau wrote:
>On Fri, Sep 03, 2004 at 03:40:58PM +0200, Siward de Groot wrote:
>> Package: balsa
>> Version: 2.0.17-2
>> Severity: minor

>> * 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.

Ah, well, no use being able to think for yourself i suppose :-)
but seriously, why not optimize this,
  when you're going to edit manpage anyway ?

>Do you have the yelp package installed? It is the GNOME Help browser.

i didnt. i just installed it. thanks for pointing that out.

i browsed it. it is generally nice and usefull ;
  i also found some small bugs in it :

* in 'introduction' it says:
  "See the abstract above for a quick feature rundown."
  i didnt find that abstract.
* in 'getting started' and elsewhere,
  there are extra linebreaks around words that consist of capitals,
  eg IMAP, POP3, MUA.
* 'main window' section on mailbox window doesnt mention
  pop-up menus that are available by right-clicking on a mailbox.
* at this point balsa crashed (help window remained allright),
  and i lost message i was composing, so i write this with xemacs,
  and paste it into balsa later.
  you probably have more important things to do
    than beautifying manpages, but i continue regardless.
o explanation of bcc etc is nice :-)
* 'message window' is a bit terse.
* 'display' tells about threaded view of messages ;
  i have often (also in kmail) thought it was stupid that
  when i have treaded view, and i delete first message of thread,
  because i have read it,
  then i find myself somewhere in middle of list,
  where next message in thread would be sorted had it been by itself,
  thus making it clumsy to read threads in order of arrival of first
    (or last) message.
* 'misc' tells about debugging. i turned it on now.
* 'address book' : balsa doesnt Suggests an addressbook,
  does it have one built in ?
* 'toolbar' : composer doesnt have cut/copy/paste for toolbar,
  while reader does,
  and i succeeded in cutting in composer
    with mouse-select followed by press-delete-key.
* i was looking for section on keypresses,
    for more nice tricks like this, but didnt find it.
* 'toolbar' is rather terse.
* 'filters' : "the match page" is a link that takes me to
  this same page, so effectively only a flicker is produced.
  second time i click it, it does nothing.
  then when i click 'the action page' and 'back',
  match page header appears at top of screen.
  strange.
o 'mailbox formats' has nice links.
  that might come in handy next time balsa says
    'inbox is not a mailbox'
    (mailbox probably shouldnt start with a newline, i guess).
o 'common tasks' is user-friendly too.
* 'authors' : /usr/share/doc/authors claims to have valid list for
  2.0.x , so i would assume it to apply to this version,
  but list in section 'authors' is different.
* glossary is called 'Unknown' in left panel ;
  it's nice to have a glossary.

 I
>may have to include a dependency/suggest for it in future.
that would be nice

>> SYNOPSIS :
>> * this is not a synopsis (see dict synopsis).
>It's a convention nevertheless. Yelp provides the friendlier help.
i agree that not many users need to read this manpage,
  but why go with a braindead convention ?

>> * 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 ?
>
>That's also a manpage convention.
i think my version reads faster and easier,
  and i'm not afraid of starting new, improved conventions.

>> DESCRIPTION
>> 	 Balsa is an e-mail reader.
>> * it is also a writer.

>Good point. "e-mail client" perhaps?

hmmm, i personally like something like
  "You can read and reply to your emails with Balsa" ;
  it is positive, it is encouraging, it is an operational definition,
  and it avoids need to classify balsa
    (i dont know a good class name anyway).

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

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

maybe.
in any case,
  reader can ignore word 'client' and not have less information.
what i meant to say is that
  word 'client' is not usefull here, only distracting.
  (that's why i used superfluous adverbs in my comment ;-).

>> * what is tld ?

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

afaik a fully qualified hostname is a hostname too,
  maybe you could just leave out .tld part,
  and (maybe superfluous) in description of option tell that
  hostname needs to be fully qualified ?

>> * 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".

paste error i suppose.

>Siward is right.

Hooray !

>A consensus was reached years ago that "without fee" meant without a =20
> fee
>(royalty) to the author (copyright holder).
>http://lists.debian.org/debian-legal/1999/08/msg00045.html

clarity is still desirable.
if copyright is decipherable by lawyers on debian-legal
  that have access to prior rulings (by themselves) on this matter
  then that is nice.
but copyright notice is meant for end users too.
and for real judges.

>Thanks for the comments.

i'm glad you like some of them :-)


have fun,

  Siward