Re: GDM man pages

[George <jirka 5z com>]

On Thu, Aug 05, 2004 at 10:44:45AM -0500, Brian Cameron 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.

I understand, however we already have the reference documentation which is
where all documentation should be IMO.  My point is not that gdm should be
documented but that it should be documented in one place only.  The man page
should just tell people to read the reference documentation IMO, because
otherwise the man page is doomed to be continually out of date as new things
are done.

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

It should not be hard to convert the gdm docs to a text format readable on
the console.  The man page could then list the file where the full
documentation is readable as text.  (We could also just create/install html
versions and point lynx at it)

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

We don't build/install the docs?  Eeek, that's a bug, they should be built
and installed.  They were some time ago ...

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

Well it's not just "too long", it is really the fact that the information is
in two places, rather then one authoritative place.  As one source of docs
improves the other does not etc..  Further suppose I do "man gdm" then it
doesn't really tell me that there is more extensive info available.

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

Man pages suck :)

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

no problem

George

-- 
George <jirka 5z com>
   I know not with what weapons World War III will be fought, but
   World War IV will be fought with sticks and stones.
                       -- Albert Einstein