Subject: Re: fvwm2.1 manpage

From: [email-masked] (Paul D. Smith)
Date: 01 Mar 1999 10:19:49 -0500

%% [email-masked] (Julian Gilbey) writes:

  jg> I've just been reading through the fvwm2.1 manpage in the 2.2 release,
  jg> and have observed a concerning number of problems.  In essence, they
  jg> seem to be related to the fact that this release was called fvwm2 at
  jg> one stage and fvwm now.  I'm really confused.  When should the manpage
  jg> talk about fvwm and when about fvwm2?

IMO, everything should be "fvwm" except when referring to the actual
executable name (and the ~/.fvwm2rc file of course).

The name of the package is "FVWM".  To allow simple installation for
those places which want to keep both fvwm 1.xx and fvwm 2.xx, the
installed binary is named fvwm2 and it reads the config file .fvwm2rc.

  jg> - The title is wrong (.TH line): it talks about FVWM (2.xx), with date
  jg>   "late 20th century".

That looks right to me.

  jg> - Is the program called fvwm or fvwm2?

As above, the actual program is called "fvwm2" (for now?)

  jg> - What are the filenames and directory paths used?  Do they have fvwm2
  jg>   or fvwm components?

All directory components should use fvwm.  All filenames except for the
window manager program itself and its rc file should use "fvwm"; the
former two use "fvwm2".

  jg> - The documentation for Restart appears to say that fvwm will restart
  jg>   itself if Restart fvwm2 is called, but fvwm/fvwm.c seems to restart
  jg>   itself if Restart fvwm is called.

I'd have to look at this, but note you can put any program after the
Restart command.  Typically you'd want this program to be a window
manager :), but it doesn't have to be fvwm.

You can put "mwm", then it'll restart mwm.  You can put "twm", ditto.
And you can put "fvwm" or "fvwm2", and it should start those,
respectively.

-- 
-------------------------------------------------------------------------------
 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: [email-masked] (Julian Gilbey)
Date: Mon, 1 Mar 1999 18:10:24 +0000 (GMT)

>   jg> - The title is wrong (.TH line): it talks about FVWM (2.xx), with date

No, it should be FVWM 2.xx (1x) as it is in section 1x of the manual.

The .TH line should read something like:

.TH "FVWM 2.xx" 1x "22 Feb 1999"

Having a date of "late 20th century" doesn't really help people to
know which version the manpages relate to ;-)

   Julian

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

  Julian Gilbey, Dept of Maths, QMW, Univ. of London. [email-masked]
             Debian GNU/Linux Developer.  [email-masked]
       -*- Finger [email-masked] for my PGP public key. -*-
--
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: Fri, 05 Mar 1999 17:08:59 -0500

[email-masked] (Julian Gilbey) writes:
> >   jg> - The title is wrong (.TH line): it talks about FVWM (2.xx), with dat
> >   jg>   "late 20th century".
> > 
> > That looks right to me.
> 

As of some recent changes, the ".TH" line in fvwm/fvwm2.1 reads:

.TH FVWM2 2.xx "late 20th century"

It looks to me like it still needs fixing.

On my system, the man page installs into section 1, not 1x.

The phrase "late 20th century" clearly indicates that everyone
forgets to change the date after they change the page content.

I see some variation in how we do heading lines:

blue> find . -name '*.1' -exec grep '[.]TH' {} \;
.TH FvwmCommand 1x "May 11 1998"
.TH focus-link.pl 1
.TH FvwmConfig 1.20 "Mar 16 1994"
.TH FvwmConsole 1x "July 16 1996"
.TH FvwmConsoleC.pl 1x  "July 16 1996"
.TH FvwmDebug 1.20 "Jan 28 1994"
.TH FvwmGoodStuff 1.20 "Jan 28 1994"
.TH FVWM 2.xx "late 20th century"
.TH FvwmScript 3.1
.TH FvwmTaskBar 2.6 "June 30th, 1996"
.TH FvwmWharf 1.0 "October 1996" FvwmWharf
.TH FVWM 2.xx "late 20th century"
.TH FvwmAnimate 1.1 "October 1998"
.TH FvwmAudio 1.0 "Mar 28 1994"
.TH FvwmAuto 2.1 "Dec 1, 1994"
.TH FvwmBacker 0.1 "September 8th, 1994"
.TH FvwmBanner 1.20 "Jan 28, 1994"
.TH FvwmButtons 1 "Nov 1 1998"
.TH FvwmCpp 2.0 12/12/94
.TH FvwmEvent 1.0 "Apr 22 1998"
.TH FvwmForm 2.0 "November 1988"
.TH FvwmIconBox 0.64 "Jun 24 1994"
.TH FvwmIconMan 1.3 "June 17, 1998"
.TH FvwmIdent 1.20 "Jan 28 1994"
.TH FvwmM4 2.0 12/12/94
.TH FvwmPager 1.20 "Mar 16 1994"
.TH FvwmRearrange 1 "November 9, 1998" "FvwmRearrange 1.0" "FvwmRearrange 1.0"
.TH FvwmSave 1.20 "Jan 28 1994"
.TH FvwmSaveDesk 2.0 "Jul 6 1996"
.TH FvwmScroll 1.20 "April 14 1994"
.TH FvwmTalk 1.20 "Jan 28 1994"
.TH FvwmWinList 0.4h "May 27th, 1995"
.TH XPMROOT 1.01 "13 August 1993"

I guess it should really be:

.TH fvwm2 1 "03 March 1999"

On the other hand,  this "man page" stuff is  boring.  We already have
the "html",  why not move  it into the  source tree and remove the man
pages?

I think its pretty common for larger programs to not rely on man pages.

Lots of things fvwm2 does really need pictures.

--
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: Danek Duvall <[email-masked]>
Date: Fri, 5 Mar 1999 15:42:15 -0800

> the "html",  why not move  it into the  source tree and remove the man

I would strongly object to the removal of the man pages.  I always have a
terminal up, but I don't always have Netscape running, and I like less much
more than lynx as a pager.

If the primary documentation ends up being the html docs, fine; I can live
with that.  But I'll try to keep the man pages up to date with them, and
keep them in the distribution.

> I think its pretty common for larger programs to not rely on man pages.

Can you give examples?  Emacs and Vim are the only two programs I use which
rely more on online help than on man pages (and even so, there are minimal
ones).  In both cases, however, there are either hundreds or thousands of
configuration options and  packages, and both support a configuration
language.

Even perl and zsh, which have the largest sets of documentation I know of,
still have manpages.  With their volume, they're split into pieces, but
they're still quite manageable.  And neither program comes with any *other*
documentation (unless you consider the camel book).

Fvwm's manpage is half the size of all the zsh documentation, and I find it
to be extremely readable.

> Lots of things fvwm2 does really need pictures.

Probably so, but if I want to spend ten seconds checking the syntax of an
fvwm command, the man pages are much more suitable.

Danek

---

From: Jason L Tibbitts III <[email-masked]>
Date: 05 Mar 1999 18:16:27 -0600

>>>>> "DD" == Danek Duvall <[email-masked]> writes:

DD> Even perl and zsh, which have the largest sets of documentation I know
DD> of, still have manpages.

Well, Emacs doesn't (generally) have them, and it has more documentation
than Perl and Zsh combined.

One interesting about all three, though, is that nobody actually writes
manpages or HTML or Info pages for any of them.  They all instead use some
markup language.  Perl uses POD, Zsh uses YODL and Emacs uses TeXinfo.  It
seems to me that if we have some basic wish to have documentation in
multiple formats then some form of markup is preferable to keeping multiple
versions synchronized.

DD> And neither program comes with any *other* documentation (unless you
DD> consider the camel book).

Well, Perl doesn't come with any manpages at all; it creates them at
install time and can also create HTML, PostScript and PDF versions.  Zsh is
a different story because most folks don't have YODL to convert things.
But there are HTML and Info pages for Zsh; you can build them yourself if
you have the tools.

I'm not sure if the FVWM documentation is now so unmanageable that some
solution is called for, but it might be nice to have a documentation
champion.

 - J<

---

From: Dan Espen <[email-masked]>
Date: Fri, 05 Mar 1999 20:09:27 -0500

> than Perl and Zsh combined.

Guess the first  thing  that comes to  mind is  emacs.  Next would  be
"cc", at  least in the sense that  "man cc" does not  tell you  how to
write C programs.

> multiple formats then some form of markup is preferable to keeping multiple

I've seen POD and TeXinfo.  Anyone  know a meta-language for man pages
and html  that allows the  html  to include images, and  possibly some
animations?

> solution is called for, but it might be nice to have a documentation

I agree its not unmanageable, I still think its boring.  I don't think
I know  what you have  in mind for the  "documentation champion".  I'm
not sure I want to know.

---

From: Jason L Tibbitts III <[email-masked]>
Date: 05 Mar 1999 19:22:05 -0600

>>>>> "DE" == Dan Espen <[email-masked]> writes:

DE> I've seen POD and TeXinfo.  Anyone know a meta-language for man pages
DE> and html that allows the html to include images, and possibly some
DE> animations?

POD has =for, =begin and =end sections where you can include raw output for
that target.  See 'man perlpod'.

DE> I agree its not unmanageable, I still think its boring.

Writing docs is always boring.  I have someone helping me with docs for
Majordomo2; so far, several hundred pages of it.  Just reading it through
all the way is killing me.  He works as a translator; I write
programmer-speak and he pokes at the software and figures out what on Earth
I'm saying.  (The problem is that he knows programmer-speak too well
himself, so the end result still isn't always suitable for end users.)

DE> I don't think I know what you have in mind for the "documentation
DE> champion".

Someone who wants to read it all and make sure it's "good stuff".  You know
that kind of person.  The kind that reads the manual first.  The kind we
call "anal".  The kind that the end users will laud as a hero, because
without that person they'll have to read the source.

DE> I'm not sure I want to know.

Oops, too late.

 - J<

---

From: Dan Espen <[email-masked]>
Date: Fri, 05 Mar 1999 20:31:14 -0500

> that target.  See 'man perlpod'.

I'll check it out.

> without that person they'll have to read the source.

OK, I swear, I'm nothing like that.