GNOME Bugzilla – Bug 776063
add a basic unix man page for ges-launch-1.0
Last modified: 2016-12-16 17:06:16 UTC
ges-launch-1.0 lacks a unix man page, so I am adding a basic one which mentions at least the various "help" options. I also noticed that the description of the "--help-GES" is incorrect, so I am fixing this as well.
Created attachment 341917 [details] [review] ges: fix the description of the --help-GES command line option Use "Show GES Options" which is more appropriate and avoids duplication with --help-gst which already says "Show GStreamer Options".
Created attachment 341918 [details] [review] ges: add a basic unix man page for ges-launch-1.0 Do not list all the possible options in the man page but only the help options. This is in order to avoid duplication and prevent the man page from becoming obsolete in case the options change in the code but do not get updated in the man page.
Comment on attachment 341917 [details] [review] ges: fix the description of the --help-GES command line option Attachment 341917 [details] pushed as 1d32be0 - ges: fix the description of the --help-GES command line option
(In reply to Antonio Ospite from comment #0) > ges-launch-1.0 lacks a unix man page, so I am adding a basic one which > mentions at least the various "help" options. > > I also noticed that the description of the "--help-GES" is incorrect, so I > am fixing this as well. Thanks for that, we already have a man like documentation here: https://gstreamer.freedesktop.org/documentation/tools/ges-launch.html we should probably reuse that but I am not sure in what form, what do you think?
Ah, I see, it is in gst-docs: https://cgit.freedesktop.org/gstreamer/gst-docs/tree/markdown/tools/ges-launch.md AFAICS gst-launch and gst-inspect in gstreamer have their stand-alone man pages which duplicate the info in the markdown docs. One option could be to generate the unix man pages from the ones in gst-docs, however in my experience the tools that generate man pages from markdown are not that great; if this was the route to go, then using asciidoc or reStructuredText for the source document would produce better results (I have first hand experience with that). But again we would have to remember to re-generate the unix man pages when the source document changes. Using a git submodule to track the man pages and generate the unix man pages at build time could work, but do we have the _motivation_ for all this work? So I'd still go for the lazy route of providing just a minimal ges-launch unix man page which points to other ways to get the full information, possibly adding a link to the on-line man page in the unix man page.
(In reply to Antonio Ospite from comment #5) ... > So I'd still go for the lazy route of providing just a minimal ges-launch > unix man page which points to other ways to get the full information, > possibly adding a link to the on-line man page in the unix man page. Sounds like a plan :)
Created attachment 342019 [details] [review] [PATHC v2] ges: add a basic unix man page for ges-launch-1.0 Changes since v1: - added a link to the on-line documentation in the "SEE ALSO" section - minor cleanup and removal of unnecessary groff macros
commit 7ef6762c79258269589ed899aa5251ff42873a20 Author: Antonio Ospite <ao2@ao2.it> Date: Tue Dec 13 16:05:17 2016 +0100 ges: add a basic unix man page for ges-launch-1.0 Do not list all the possible options in the man page but only the help options. This is in order to avoid duplication and prevent the man page from becoming obsolete in case the options change in the code but do not get updated in the man page. https://bugzilla.gnome.org/show_bug.cgi?id=776063