GNOME.org
 

[balsa] Man-page cleanup

commit 9fd6c61f94624999b91e54172e687994124152ab
Author: Peter Bloomfield <PeterBloomfield bellsouth net>
Date:   Tue Feb 18 17:14:20 2020 -0500

    Man-page cleanup
    
    * balsa.1.in: update;
    * src/main.c (parse_options): revert the "--checkmail" option to
      its traditional (and documented) "--check-mail".

 ChangeLog  |   8 +++
 balsa.1.in | 228 +++++++++++++++++++++++++------------------------------------
 src/main.c |   2 +-
 3 files changed, 101 insertions(+), 137 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index 24ce23ab6..d4ad6705b 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2020-02-18  Peter Bloomfield  <pbloomfield bellsouth net>
+
+       Man-page cleanup
+
+       * balsa.1.in: update;
+       * src/main.c (parse_options): revert the "--checkmail" option to
+       its traditional "--check-mail".
+
 2020-02-18  Peter Bloomfield  <pbloomfield bellsouth net>
 
        Use a GThreadPool to open mailboxes
diff --git a/balsa.1.in b/balsa.1.in
index 076e98f55..a54a768eb 100644
--- a/balsa.1.in
+++ b/balsa.1.in
@@ -1,10 +1,9 @@
-.TH Balsa 1 "03 January 2003" "Version @VERSION@" "Gnome Manpage"
+.TH Balsa 1 "February 2020" "Version @VERSION@" "Gnome Manpage"
 .SH NAME
  Balsa \- the GNOME email client.
-
 .SH DESCRIPTION
 You can use Balsa to fetch, read, write and send e-mails.
-
+.PP
 It supports
   * local mailboxes in maildir, mbox and/or mh format,
   * nested mailboxes,
@@ -13,195 +12,152 @@ It supports
   * GnuPG/GPG encryption, LDAP, Kerberos and SSL,
   * MIME (view images, save parts),
   * multiple character sets,
-  * GPE address book,
-  * printing and spell-checking.  
-  
+  * vCard, GPE, and other address book formats,
+  * printing and spell-checking.
+.PP
 Balsa is an integral part of the GNOME desktop environment, but it can
-  also be used standalone though it may print some error messages then.
-
-For help on using Balsa, see the documentation in its help menu using
-  Yelp Gnome 2 help/documentation browser.
-
+also be used standalone though it may print some error messages then.
+.PP
+For help on using Balsa, see the documentation in its help menu.
+.PP
 This man page tells about the options of the '\fBbalsa\fR' command,
-  which is used to start Balsa.
-.RS 0
-.RE
-Most of these options let you tell Balsa that when it starts
-  it should immediately open a mailbox, or the composer ,
-  and things like that.
-.RS 0
-.RE
-There is also an option to debug POP connections.
+which is used to start Balsa.
+.PP
+Most of these options let you tell Balsa that when it starts it should
+immediately open a mailbox, or the composer, and things like that.
+.PP
+There is also an option to debug POP and IMAP connections.
+.PP
+When you start Balsa from the command line, not only can you use the
+command line options described below, any error messages are printed to
+that terminal too (whether you execute that command in the background
+or not).
 .PP
-When you start Balsa from the command line of an (x)terminal,
-  not only can you use the command line options described below,
-  any error messages are printed to that terminal too
-  (whether you execute that command in the background or not).
-
 .SH SYNTAX
-\fBbalsa \fR[  \fB\   \fR  \fB\-\-help                               \fR]
-\fR      \fR[  \fB\   \fR  \fB\-\-version                            \fR]
+\fBbalsa \fR[  \fB\-h \fR| \fB\-\-help                               \fR]
+\fR      \fR[  \fB\-v \fR| \fB\-\-version                            \fR]
 \fR      \fR[  \fB\-c \fR| \fB\-\-check-mail                         \fR]
 \fR      \fR[( \fB\-m \fR| \fB\-\-compose=\fR)\fIemail-address             \fR]
 \fR      \fR[( \fB\-a \fR| \fB\-\-attach=\fR)\fIfilename                   \fR]
 \fR      \fR[( \fB\-o \fR| \fB\-\-open\-mailbox=)\fImailbox\fR[\fI:mailbox\fR]... ]
 \fR      \fR[  \fB\-u \fR| \fB\-\-open\-unread\-mailbox                \fR]
-\fR      \fR[  \fB\-d \fR| \fB\-\-debug\-pop                          \fR]
-\fR      \fR[  \fB\-D \fR| \fB\-\-debug\-imap                         \fR]
+\fR      \fR[  \fB\-i \fR| \fB\-\-open\-inbox                         \fR]
 .SH OPTIONS
 .PP
-\fB\-? \fR, \fB\-\-help\fR
-.RS 7
-Displays a message describing command line syntax of Balsa,
-  giving many more options than are presented in this man page;
-  Balsa exits immediately after that.
-.RS 0
-.RE
-Some of these options work (and thus should be in this man page)
-  for example --display ,
-  others may not -
-  for example --disable-crash-dialog which is provided by GNOME GUI
-Library.  
-.RS 0
+\fB\-?\fR, \fB\-h\fR, \fB\-\-help\fR
+.RS
+Displays a message describing command line syntax of Balsa, giving many
+more options than are presented in this man page;
+Balsa exits immediately after that.
+.PP
+Some of these options work (and thus should be in this man page) for
+example --display, others may not - for example --disable-crash-dialog
+which is provided by GNOME GUI Library.
 .RE
-
 .PP
-\fB\-\-version\fR
-.RS 7
+\fB\-v\fR, \fB\-\-version\fR
+.RS
 Balsa prints its version and exits.
 .RE
-
-.PP 
-\fB\-c \fR, \fB\-\-check-mail\fR
-.RS 7
+.PP
+\fB\-c\fR, \fB\-\-check-mail\fR
+.RS
 Balsa starts and checks for new mail immediately.
 .RE
-
 .PP
-\fB\-i \fR, \fB\-\-open-inbox
-.RS 7
+\fB\-i\fR, \fB\-\-open-inbox
+.RS
 Balsa starts and opens the Inbox.
 .RE
-
-.PP
-\fB\-m \fIemail-address \fR, \fB\-\-compose=\fIemail-address\fR
-.RS 7
-When invoked with this option,
-  Balsa will open its email-composer for a new message
-  with the specified address in the To: field.
-.RS 0
-.RE
-The email-address parameter can be specified
-  as user@host, e.g. \fBbalsa-list gnome org \fR,
-  or in URL format, e.g. \fB"Balsa List <balsa-list gnome org>" \fR.
-.RS 0
-.RE
-You can use Balsa as mailto protocol handler
-  by, in the URL handlers section of the GNOME control center,
-  setting the mailto protocol command to : \fBbalsa -m "%s"\fR
-.RE
 .PP
-\fB\-a \fIFILENAME \fR, \fB\-\-attach=\fIFILENAME\fR
-.RS 7
-When invoked with this option,
-  Balsa will open its email-composer for a new message
-  with the specified file already attached to the message.
-.RS 0
+\fB\-m \fIemail-address\fR, \fB\-\-compose=\fIemail-address\fR
+.RS
+When invoked with this option, Balsa will open its email-composer for
+a new message with the specified address in the To: field.
+.PP
+The email-address parameter can be specified as user@host,
+e.g. \fBbalsa-list gnome org\fR, or in URL format,
+e.g. \fB"Balsa List <balsa-list gnome org>"\fR.
+.PP
+Balsa also serves as the mailto protocol handler.
 .RE
+.PP
+\fB\-a \fIFILENAME\fR, \fB\-\-attach=\fIFILENAME\fR
+.RS
+When invoked with this option, Balsa will open its email-composer for
+a new message with the specified file already attached to the message.
+.PP
 Example : \fBbalsa -a ~/balsa-new.1.gz\fR
 .RE
 .PP
 \fB\-o \fIMAILBOX\fR, \fB\-\-open-mailbox=\fIMAILBOX\fR...
-.RS 7
-This makes \FIBalsa\FR start and open the specified mailbox. The
-mailbox should be specified by its full URL.
-.RS 0
-.RE
+.RS
+This makes \FIBalsa\FR start and open the specified mailbox.
+The mailbox should be specified by its full URL.
+.PP
 Example : \fBbalsa -o imap://user mail example com/INBOX\fR
 \fBbalsa -o file:///var/mail/user\fR
 .RE
 .PP
-\fB\-u \fR, \fB\-\-open-unread-mailbox\fR
-.RS 7
+\fB\-u\fR, \fB\-\-open-unread-mailbox\fR
+.RS
 Open all mailboxes that may contain unread messages.
 .RE
-.PP
-\fB\-d \fR, \fB\-\-debug-pop\fR
-.RS 7
-Makes Balsa print the POP3 communication to stderr,
-  including the full text of every message.
-.RS 0
-.RE
-The former can be useful for debugging POP3 connections.
-.RE
-.PP
-\fB\-D \fR, \fB\-\-debug-imap\fR
-.RS 7
-Makes Balsa print the IMAP communication to stderr.
-.RS 0
-.RE
-This feature is useful for debugging IMAP problems.
-.RE
 .SH WEBSITE
 Balsa's website is \fI
 .UR https://pawsa.fedorapeople.org/balsa
-https://pawsa.fedorapeople.org/balsa\fR
-
+https://pawsa.fedorapeople.org/balsa\fR.
+.PP
 .SH SUGGESTIONS AND BUG REPORTS
 Any bugs found in Balsa can be reported through
-  the Balsa Developer mailing list at \fBbalsa-list gnome org \fR,
-  or the online bug-tracking system at \fBhttps://gitlab.gnome.org/GNOME/balsa/issues \fR.
-.RS 0
-.RE
-See https://pawsa.fedorapeople.org/balsa/bugs.html for more information on reporting Balsa bugs.
-
-Before reporting bugs, please check to see if the bug is mentioned 
-in the FAQ's or the mailing list archive \fI
+the Balsa Developer mailing list at \fBbalsa-list gnome org\fR,
+or by opening an issue at \fBhttps://gitlab.gnome.org/GNOME/balsa/issues\fR.
+.PP
+See https://pawsa.fedorapeople.org/balsa/bugs.html for more information
+on reporting Balsa bugs.
+.PP
+Before reporting bugs, please check to see if the bug is mentioned in
+the FAQ's or the mailing list archive \fI
 .UR https://mail.gnome.org/mailman/listinfo/balsa-list
 https://mail.gnome.org/mailman/listinfo/balsa-list\fR
-
+.PP
 When reporting Balsa bugs, it is important to include
   * a reliable way to reproduce the bug,
-  * version number of Balsa (as well as GTK and GNOME),
+  * version number of Balsa (as well as Gtk and GNOME),
   * OS name and version,
   * any relevant hardware specs.
-
+.PP
 If a bug is causing a crash, it is very useful if a stack trace can be
 provided.
-.RS 0
-.RE
+.PP
 And of course, patches to rectify the bug are even better.
-
+.PP
 .SH AUTHORS
 See the AUTHORS file included with Balsa, probably at
 \fB/usr/share/doc/balsa-@VERSION@/AUTHORS \fR.
-
+.PP
 .SH FILES
-\fB ~/.gnome2/balsa                   \fRBalsa's preferences file.
-\fB ~/.gnome2_private/balsa           \fRBalsa's POP and IMAP passwords file.
+\fB ~/.balsa/config                   \fRBalsa's preferences file.
+\fB ~/.balsa/config-private           \fRBalsa's POP and IMAP passwords file.
 \fB /etc/sound/events/balsa.soundlist \fRsystem-wide configuration file
-
+.PP
 .SH SEE ALSO
-Package names given in parenthesis are Debian package names.
-
+Package names given in parentheses are Debian package names.
+.PP
 \fBmailcap  \fR(5) - metamail capabilities file (package: mime-support)
-.RS 0
-.RE
+.PP
 \fBmetamail \fR(1) - infrastructure for mailcap-based multimedia mail
                                           (package: metamail)
-.RS 0
-.RE
+.PP
 \fBsendmail \fR(8) - a Mail Transfer Agent      (package: exim4-daemon-light)
-.RS 0
-.RE
+.PP
 \fByelp     \fR(1) - browse Gnome documentation (package: yelp)
-.RS 0
-.RE
+.PP
 \fBGNOME    \fR(1) - modern desktop environment (package: gnome-bin)
-
+.PP
 .SH COPYRIGHT
-(c) 1997-2003 Stuart Parmenter and others, see AUTHORS for a list of people.
-
-This is free software; see the source for copying conditions.  There
-is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
-PARTICULAR PURPOSE.
+(c) 1997-2020 Stuart Parmenter and others; see AUTHORS for a list of people.
+.PP
+This is free software; see the source for copying conditions.
+There is NO warranty;
+not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
diff --git a/src/main.c b/src/main.c
index 508a9c321..69ee0e45c 100644
--- a/src/main.c
+++ b/src/main.c
@@ -637,7 +637,7 @@ parse_options(int                       argc,
     static gboolean version;
     static gchar **remaining_args;
     static GOptionEntry option_entries[] = {
-        {"checkmail", 'c', 0, G_OPTION_ARG_NONE,
+        {"check-mail", 'c', 0, G_OPTION_ARG_NONE,
          &(cmd_check_mail_on_startup),
          N_("Get new mail on start-up"), NULL},
         {"compose", 'm', 0, G_OPTION_ARG_STRING, &(opt_compose_email),
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]