Breda:
The attached tarballs contain all the gstreamer and gdm man pages.
They have been reviewed and updated to reflect comments provided by
the community. Outstanding issues are as follows:
1) The fact that gdmconfig.1M and gdmsetup.1 require the same man page
but are in different man subsections. You know about this and it
sounds like we'll resolve it by simply putting two near-identical
man pages in the different subsections.
2) The complication with the gstreamer programs. Most of the programs
(except for gst-thumbnail and gstreamer-properties) come with
a wrapper script. For example.
gst-register is a wrapper script that calls gst-register-#.#.
The wrapper scripts take the following additional 3 options (and pass
along the rest to the real program):
--print Print wrapped command line
--gst-mm=STRING Force major/minor version
--gst-list-mm List found major/minor versions
The wrapper scripts will run the highest installed version of the program.
For example, if you have /bin/gst-register-0.7 and gst-register-0.8
installed on your system, running gst-register will run gst-register-0.8.
The --print option will echo back the command it will run, so in the above
example running "gst-register --print" will echo back "/bin/gst-register-0.8"
and will then run the command.
The --gst-mm option allows the user to specify a specific version to run,
if you don't want to run the default.
The --gst-list-mm option echos back the options that are available.
Not exactly sure how this should be represented in the man pages. Perhaps
the man pages should include a WRAPPER subsection which explains the above
options and the difference between the gst-foo and gst-foo-0.8
executables (basically that gst-foo is a wrapper for gst-foo-0.8).
3) The GDM maintainer, George Lebl, is not happy with the man pages that I wrote
because they duplicate a lot of the material that is available in the public
XML documentation which gets installed on the system to:
/usr/share/gnome/help/gdm/<lang>/gdm.xml.
An online version of these same docs can be viewed here:
http://www.5z.com/jirka/gdm-documentation/t1.html
The GDM maintainer feels that it is a bad idea to duplicate this information
in two places, and he prefers the XML format. He thinks that maintaining
this information in two places will be problematic and that there should only
be one definitive source for this information. Therefore, he thinks that the
man page should be minimal and include little more than the NAME, SYNOPSIS,
and USAGE sections and refer to the XML file for the rest.
I'm not sure that this is appropriate, or that XML is a valid format for
a man page to refer the user to. If not, what format (if any) would we
need to convert/transform the docs to in order to make them something we
could refer to from the man pages?
I told George that I would trade emails with you and find out if his approach
is workable for Sun. Obviously, if Sun requires this information to be in
the man page format for whatever reason, then we can go ahead and use the
man I wrote pages even if they don't get accepted back into the community.
I've cc:ed George on this email so he can participate in the discussion.
Please advise.
Thanks!
--
Brian
Attachment:
gdm.tar.gz
Description: application/gzip
Attachment:
gst-new-manpages.tar.gz
Description: application/gzip