Re: To Breda - gdm man pages (was Re: [Fwd: [Fwd: BugId 5080466 :(P3/S3)Has been Updated - by alanc]])


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:


   An online version of these same docs can be viewed here:

   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.




Attachment: gdm.tar.gz
Description: application/gzip

Attachment: gst-new-manpages.tar.gz
Description: application/gzip

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