GNOME.org
 

Re: GDM man pages


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


That seems reasonable to me.  If we can find a solution that works for both
Sun and the community in the short timeframe before our freeze, then we could
go with that.  Otherwise, Sun might just go ahead and use the man pages I
put together for the time being and switch to the new mechanism when it is
available.


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)


Unfortunately lynx is not installed on Solaris by default, so HTML is
probably not an acceptable format for documentation that a man page
refers a user to, at least on Solaris.  I'll check with our docs team
on Monday, when they are back in the office.


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


I'm sorry, the docs do get installed to /usr/share/gnome/help/gdm.


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.


That's a valid point.  I'll talk to our docs team and find out what
they say.   And I'll let you know.  Hopefully we can find a solution
that meets everybody's needs in a nice way.

Though the XML docs would need to be a bit more complete if we wanted
to make them a complete replacement for the man pages.  Or are you
suggesting the man pages should just include sections like SYNOPSIS,
OPTIONS, FILES, etc. and refer to the XML docs for the DESCRIPTION info.
If you want the XML docs to be a complete replacement for the man
page, then they would have to go into more detail about all the
options that programs take, include the FILES information in one
place, etc.

Also, note that my gdm man pages go into some additional detail about
accessibility in the gdm.1 man page and into more detail about the
various gdmflexiserver --command options.  This probably needs to
be added to the XML docs if we want it to be the place where all
this information goes.

--

Brian
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]