George:
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.
Okay, I have worked with Sun's documentation team, and they agree with your concerns. They are agreeable to having the man page refer to the gdm Help documentation to avoid duplicating information in more than one place. Attached is a tarball with updated man pages that refer to the Help documentation where appropriate. You'll notice that the new gdm.1 man page is much lighter. It could be made lighter still if the ACCESSIBILITY section were added to the Help docs. Also, the "FILES" section could be moved to the Help docs as well, but first we would have to add a section to the Help docs which summarizes this FILE information in one place rather than having it scattered about the Help docs as it is currently. On the other hand, it is perhaps not bad to keep the FILES section in the man page, since it is useful and doesn't duplicate much information. Also, the gdmflexiserver man page could be made smaller if the COMMANDS section were moved into the Help docs. I've left brief DESCRIPTION sections in the man pages that briefly explain what the program does. For example, the gdm man page is intended to be used for gdm, gdm-binary, gdmgreeter, gdmlogin, and gdmchooser. So it still has a brief descriptions of these programs. I've also left the SYNOPSIS and OPTIONS sections in the man page since it seems appropriate to leave at least this much information in a man page.
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)
The docs team has agreed that the Help docs are sufficient. Although making them available by HTML might not be a bad idea too. Let me know what you think. I need to know by Friday, though, since that is our cut-off date for man page work. It'd be nice to get this sorted by then, if possible. Thanks! -- Brian
Attachment:
gdm-man.tar.gz
Description: application/gzip