Re: GDM man pages

[Brian Cameron <Brian Cameron Sun COM>]

George wrote:


> Wow, that's pretty long.  Are you sure all this needs to be in the man pages?
> I mean large part is duplicating the main docs, perhaps the man page should
> just give the very basic overview info and refer to the main docs.  This way
> the information does not get out of sync.

Yes, it is pretty long.  Although, to be honest, the gdm(1) man page is
still less than half the size of the dtlogin (CDE's login program) man
page.  That's mostly becuase in the CONFIGURATION section I say "refer
to the gdm.conf file" rather than listing all configuration choices out,
as the dtlogin man  page does.  So, yes, I think  it is appropriate for
a login program's man page to be long.  Login programs touch on a lot
of issues that are complicated, like security.  Login programs
interact with a lot of interfaces (environment variables, files), so
documenting a program like gdm is more weighty than for a program like
gnome-calculator.  I think it is reasonable to expect the man page to
be more substantial.

There are certain advantages to having this information in man page
format, as opposed to the online docs:

1) With a program like gdm, it is probably a common situation where a
   system administrator is working on gdm from a console or a telnet
   session, and may not have Xwindows running.  The gdm docs are best
   viewed with a browser, which may not always be available.

2) gdm currently doesn't build/install the docs, and they are only
   available online and in the source tarball.  We'd have to fix that
   so they get installed when you run "make install" in gdm.  It
   would obviously not be appropriate to give a URL to a site that
   requires net access to see the documentation.

3) I think most of the information in the man pages is actually
   pretty stable information.  I did not try to document the
   configuration, which I suspect is the most likely area of
   gdm to change.  Are the sections like "DESCRIPTION",
   "STANDARD GREETER", "GRAPHICAL GREETER", "CHOOSER", and
   "ACCESSIBILITY" really going to change that much?

   If there are specific areas that you think are going to be
   changing over time, and are perhaps too much work to keep
   maintained, then let me know and we can consider removing
   those sections.  But just removing sections because they
   seem "too long" doesn't seem a good reason to me.

4) Perhaps the online docs should refer to the man page for
   some information to keep things in sync instead of the
   other way around.  Or perhaps HTML-ized versions of the
   man pages could become a replacement for certain sections
   of the online docs.  This might be a better way to avoid
   multiple versions of the same docs since man pages are a more
   standard UNIX documentation mechanism than XML/HTML.
   I'm just playing devil's advocate here, trying to make sure
   we consider all the possible options.  :)

5) Man pages are cool.

Oh, by the way, if you are wondering why I wrote all the man pages
in ASCII format, that's because here at Sun we pass them off to
the docs team that way, and they convert them to NROFF.  I can
share the NROFF versions of the files with you after they are
done, though it will probably take a month or so.  Or I suppose
someone else could convert them if there's a desire to have them
sooner.

--

Brian