Subject: Man pages

From: "Paul D. Smith" <[email-masked]>
Date: 08 Mar 2000 13:49:44 -0500

One thing I'd like to do before we release is clean up the module man
pages.  Here I'm not talking about content (although probably some of
that could be done too), but rather format.

I think the format of many of the current man pages leaves much to be
desired.  Here's a sample formatted man page from FvwmButtons:

  NAME
       FvwmButtons - the FVWM buttonbox module

  SYNOPSIS
       FvwmButtons  is  spawned by fvwm, so no command line invoca-
       tion will work.  The correct syntax in ~/.fvwm2rc is:

       Module FvwmButtons [-g geometry] [-transient|-transientpanel] [name [configfile]]

       With the -g option you can specify the geometry of the  main
       window.   The  command line option takes precedence over any
       other geometry settings in the configuration file.

       The -transient option tells FvwmButtons to terminate  itself
       after  the  first  key  or  button  press  has been received
       (presses to open a sub panel do not count)  or  a  sub-panel
       has  been  closed  or re-spawned.  This is especially useful

          [...]

  DESCRIPTION
       The FvwmButtons module provides a window  of  buttons  which
       sits on the X terminal's root window. The user can press the
       buttons at any time, and trigger invocation of a user-speci-

          [...]

  INITIALIZATION
       During initialization, FvwmButtons will search for a config-
       uration  file which describes the buttonbox geometry, color,
       icons, and  actions.   The  format  of  this  file  will  be

          [...]

  INVOCATION
       FvwmButtons can be invoked by  inserting  the  line  'Module
       FvwmButtons'  in the .fvwm2rc file. This should be placed in

          [...]

  CONFIGURATION OPTIONS
       The following options in the .fvwmrc file are understood  by
       FvwmButtons:

          [...]

Etc.  Problems I see are: (a) the different categories aren't
well-defined, and not consistent across man pages for modules. (b) The
SYNOPSIS section should give just a discussion of the syntax for
starting the module, not discuss the options in detail as these do
(IMO).  (c) The SYNOPSIS text also seems to run together and is hard to
decipher.   (d) The SYNOPSIS information comes before the DESCRIPTION,
so you're reading technical details about invoking the module before you
even know what it does.  (e) It seems there may be some duplication of
sections (maybe related to (a)).

Also, few of the man pages use proper encoding for referring to other
man pages (typically by putting the name in italics, like this:

  .IR fvwm2 (1)

(obviously the . must be in column 1).

I also see a lot if use of escapes like \fIitalics\fP; I personally
think it's nicer and less error-prone to use the macros for that, like:

  .I italics

Etc.

What do you all think?  Can we come up with a standardized template for
module man pages--at least for the first bunch of boilerplate sections
(obviously some man pages have extra stuff others don't)?  Is anyone
interested in this?

-- 
-------------------------------------------------------------------------------
 Paul D. Smith <[email-masked]>         Network Management Development
 "Please remain calm...I may be mad, but I am a professional." --Mad Scientist
-------------------------------------------------------------------------------
   These are my opinions---Nortel Networks takes no responsibility for them.
--
Visit the official FVWM web page at <URL:http://www.fvwm.org/>.
To unsubscribe from the list, send "unsubscribe fvwm-workers" in the
body of a message to [email-masked].
To report problems, send mail to [email-masked]

---

From: Michael Han <[email-masked]>
Date: Wed, 08 Mar 2000 11:05:19 -0800

Previously from "Paul D. Smith"
>[snip]

I'd be interested in helping out, though I don't know much about
?roff. On the occassions that I've needed to make changes to manpages
with patches I've submitted, I've just gone by example of
surrounding/similar text (hence my agreement that a standardization of
some kind would be great -- I imagine there are others out there
providing manpage patches hewing to bad examples).

But still, I'd be happy to take care of scut work once some templates
were generated. Oh, and I'd be happy to do some looking into ?roff so
such things make better sense to me ;>
-- 
[email-masked]                         http://www.best.com/~mikehan/
coffee achiever                              San Francisco, California
"I will not be a snickerpuss." - Lisa
--
Visit the official FVWM web page at <URL:http://www.fvwm.org/>.
To unsubscribe from the list, send "unsubscribe fvwm-workers" in the
body of a message to [email-masked].
To report problems, send mail to [email-masked]

---

From: Dan Espen <[email-masked]>
Date: Wed, 08 Mar 2000 14:08:32 -0500

>        FvwmButtons - the FVWM buttonbox module
...
> (obviously some man pages have extra stuff others don't)?  Is anyone

I'm interested, and I've struggled with some of the issues you've raised.

  NAME
  SYNOPSIS
  DESCRIPTION
  INITIALIZATION
  INVOCATION
  CONFIGURATION OPTIONS

If you just proposed that the synopsis section be one line:

  Module FvwmButtons -x...

I agree.

The remaining 4 categories don't do much for me either.

I'd be inclined to put an overview in DESCRIPTION, and the rest of
the details under ... DETAILS?

The way these pages refer to reading the .fvwm2rc is clumsy at best.
The commands don't necessarily come from there.

The stuff about command line invocation is really uninteresting to
the average reader and should be buried somewhere.  (CAVEATS?).

--
Dan Espen
444 Hoes Lane  Room RRC 1C-214           E-mail: [email-masked]
Piscataway, NJ 08854                     Phone: (732) 699-5570
--
Visit the official FVWM web page at <URL:http://www.fvwm.org/>.
To unsubscribe from the list, send "unsubscribe fvwm-workers" in the
body of a message to [email-masked].
To report problems, send mail to [email-masked]

---

From: Dominik Vogt <[email-masked]>
Date: Thu, 16 Mar 2000 07:05:17 +0100

...

> think it's nicer and less error-prone to use the macros for that, like:

You may have noticed that these are exactly the reasons why I rewrote
the main man page.  The new style is based completely on the Linux
"man page howto".  Therein the meaning and order of standard sections
in man pages as well as the way to typeset them is set forth.

> (obviously some man pages have extra stuff others don't)?  Is anyone

Yes, I am.  I didn't start working on module man pages because the
main man page held enough work for a complete week in store.

Bye

Dominik ^_^

--
Dominik Vogt, [email-masked]
Reply-To: [email-masked]
--
The adjuration to be "normal" seems shockingly repellent to me; I see neither
hope nor comfort in sinking to that low level.  I think it is ignorance that
makes people think of abnormality only with horror and allows them to remain
undismayed at the proximity of "normal" to average and mediocre.  For surely
anyone who achieves anything is, essentially, abnormal.
                -- Dr. Karl Menninger, "The Human Mind", 1930