After an evaluation, GNOME has moved from Bugzilla to GitLab. Learn more about GitLab.
No new issues can be reported in GNOME Bugzilla anymore.
To report an issue in a GNOME project, go to GNOME GitLab.
Do not go to GNOME Gitlab for: Bluefish, Doxygen, GnuCash, GStreamer, java-gnome, LDTP, NetworkManager, Tomboy.
Bug 776063 - add a basic unix man page for ges-launch-1.0
add a basic unix man page for ges-launch-1.0
Status: RESOLVED FIXED
Product: GStreamer
Classification: Platform
Component: gst-editing-services
git master
Other Linux
: Normal enhancement
: 1.11.1
Assigned To: GStreamer Maintainers
GStreamer Maintainers
Depends on:
Blocks:
 
 
Reported: 2016-12-13 21:44 UTC by Antonio Ospite
Modified: 2016-12-16 17:06 UTC
See Also:
GNOME target: ---
GNOME version: ---


Attachments
ges: fix the description of the --help-GES command line option (977 bytes, patch)
2016-12-13 21:45 UTC, Antonio Ospite
committed Details | Review
ges: add a basic unix man page for ges-launch-1.0 (2.79 KB, patch)
2016-12-13 21:45 UTC, Antonio Ospite
none Details | Review
[PATHC v2] ges: add a basic unix man page for ges-launch-1.0 (2.96 KB, patch)
2016-12-15 12:25 UTC, Antonio Ospite
none Details | Review

Description Antonio Ospite 2016-12-13 21:44:46 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.
Comment 1 Antonio Ospite 2016-12-13 21:45:34 UTC
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".
Comment 2 Antonio Ospite 2016-12-13 21:45:40 UTC
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 3 Thibault Saunier 2016-12-14 12:14:12 UTC
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
Comment 4 Thibault Saunier 2016-12-14 12:14:29 UTC
(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?
Comment 5 Antonio Ospite 2016-12-14 14:25:57 UTC
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.
Comment 6 Thibault Saunier 2016-12-14 15:00:13 UTC
(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 :)
Comment 7 Antonio Ospite 2016-12-15 12:25:19 UTC
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
Comment 8 Thibault Saunier 2016-12-16 17:06:16 UTC
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