GNOME Bugzilla – Bug 773917
gstreamer: tools: cleanup man pages and install them when building with meson
Last modified: 2016-11-23 09:43:06 UTC
Created attachment 339080 [details] [review] gstreamer: tools: cleanup man pages and install them when building with meson Hi, I was thinking about writing a man page for ges-launch-1.0 and ended up cleaning up the man pages in gstreamer/tools and allow to install them with meson... See the patches in the attachment, note that they change a bit the current look of the man pages, namely the program names now have the API version number always appended to them (i.e. gst-launch-1.0, instead of just gst-launch, etc.) I think this makes sense because that's the form the executable and the man pages file names use. I took a gradual approach and kept the pre-processing with sed; IMHO in the long run the pre-processing step could be dropped, and have @GST_API_VERSION_NUMBER@ everywhere directly in the templates. I didn't do this for now because in meson GST_API_VERSION is a quoted string, and configure_file() would add the double quotes around the version number, so I introduced a GST_API_VERSION_NUMBER variable and took care of this difference in a shell script. Ciao ciao, Antonio
Comment on attachment 339080 [details] [review] gstreamer: tools: cleanup man pages and install them when building with meson Thanks, but please attach patches separately (use git-bz to make that easy)
Ah, I didn't know about git-bz. I'll attach the patches with it then. Thanks, Antonio
Created attachment 339141 [details] [review] tools/gst-*.1.in: escape dashes in the man pages The portable way to have the dashes to be rendered as ASCII minuses is to use the sequence backslash-dash, use this style at least for text that can be copied and pasted (e.g. command names, file names, element options). Also use backslash-dash in the NAME section as suggested by lexgrog(1).
Created attachment 339142 [details] [review] tools/gst-launch.1.in: don't use GST_API_VERSION in the programs names Let the preprocessing step with sed append the API version to the program names.
Created attachment 339143 [details] [review] tools/Makefile.am: fix replacing programs names in the generated man pages
Created attachment 339144 [details] [review] tools/gst-launch.1.in: don't start lines with single quotes
Created attachment 339145 [details] [review] tools/gst-launch.1.in: put the examples descriptions before the commands
Created attachment 339146 [details] [review] tools/gst-{inspect,typefind}.1.in: don't mention gst-feedback
Created attachment 339147 [details] [review] meson.build: add GST_API_VERSION_NUMBER to the configuration data
Created attachment 339148 [details] [review] tools/meson.build: generate the targets dynamically
Created attachment 339149 [details] [review] tools/meson.build: add commands to build and install the man pages
Comment on attachment 339141 [details] [review] tools/gst-*.1.in: escape dashes in the man pages commit 64c097d296730a799f92a1d3d3c8e0252050531f Author: Antonio Ospite <ao2@ao2.it> Date: Wed Nov 2 22:36:27 2016 +0100 tools: escape dashes in the man pages The portable way to have the dashes to be rendered as ASCII minuses is to use the sequence backslash-dash, use this style at least for text that can be copied and pasted (e.g. command names, file names, element options). Also use backslash-dash in the NAME section as suggested by lexgrog(1). https://bugzilla.gnome.org/show_bug.cgi?id=773917
Comment on attachment 339144 [details] [review] tools/gst-launch.1.in: don't start lines with single quotes commit 7521d5b3cf1ebaf812bf1a28f8e36a78b1017594 Author: Antonio Ospite <ao2@ao2.it> Date: Wed Nov 2 22:56:01 2016 +0100 tools: don't start lines with single quotes in man page When a line starts with a single quote it's treated in a special way by man, which may result in paragraphs of the man page not rendered by the man pager, so just avoid that. A possible solution could have been to escape the singe quote with a \(cq sequence but this is rather unreadable, instead the text has been reformatted to have the problematic quoted 'ppc' string on the previous line. https://bugzilla.gnome.org/show_bug.cgi?id=773917
Comment on attachment 339145 [details] [review] tools/gst-launch.1.in: put the examples descriptions before the commands commit 76656050b56dfea267780f08d0054ea2ad379e93 Author: Antonio Ospite <ao2@ao2.it> Date: Thu Nov 3 00:18:21 2016 +0100 tools: put the examples descriptions before the commands in man page Put the description of the example command lines before the command instead of after them. The new way is more intuitive. https://bugzilla.gnome.org/show_bug.cgi?id=773917
Comment on attachment 339146 [details] [review] tools/gst-{inspect,typefind}.1.in: don't mention gst-feedback commit ef3a60793ba179e3c9ae463589293dde9d78701d Author: Antonio Ospite <ao2@ao2.it> Date: Thu Nov 3 15:21:05 2016 +0100 tools: don't mention gst-feedback in man pages gst-feedback no longer exists. https://bugzilla.gnome.org/show_bug.cgi?id=773917
Comment on attachment 339148 [details] [review] tools/meson.build: generate the targets dynamically commit 4eb64cd2764d4624fcc2c6c6067d6b67361a773f Author: Antonio Ospite <ao2@ao2.it> Date: Thu Nov 3 13:34:18 2016 +0100 meson: tools: generate the targets dynamically The three targets are the same except for input and output files, use a loop and generate them dynamically. https://bugzilla.gnome.org/show_bug.cgi?id=773917
Thanks for working on this. As for all this GST_API_VERSION business, I think it's all very silly and should just be removed. I actually thought I'd done that already, but apparently not. Let's just hard-code -1.0 in the man page directly. I think we'll manage to do a sed replace every 5-10 years.
(In reply to Tim-Philipp Müller from comment #17) > Thanks for working on this. > > As for all this GST_API_VERSION business, I think it's all very silly and > should just be removed. I actually thought I'd done that already, but > apparently not. > > Let's just hard-code -1.0 in the man page directly. I think we'll manage to > do a sed replace every 5-10 years. The sed step is awful, I agree, I didn't mind the "configure" substitution, tho. Anyways if you want the -1.0 to be hardcoded that's fine, that means that the file name can be changed too, right? I mean to gst-launch-1.0.1, etc. to reflect that those are the final man pages with no pre-processing needed. Ciao, Antonio
That's not a problem IMHO (file name change). Let's just keep it simple :)
Created attachment 340534 [details] [review] tools: ship the final man pages directly, no more man pages templates
Created attachment 340535 [details] [review] meson: tools: install the man pages
commit 38b9aa4c333a3ffa6f0ef96b860714cf87d8ceb0 Author: Antonio Ospite <ao2@ao2.it> Date: Thu Nov 3 10:30:53 2016 +0100 meson: tools: install the man pages https://bugzilla.gnome.org/show_bug.cgi?id=773917 commit 2a5a8dd3c7461b45e25abaaf16cce43eb0d10ecf Author: Antonio Ospite <ao2@ao2.it> Date: Thu Nov 3 10:30:53 2016 +0100 tools: ship the final man pages directly, no more man pages templates Don't use templates for the man pages, the API version change is a rare event, so it's not really worth keeping in place the "sed" boilerplate to have it set at build time. Shipping the final man pages directly also makes it easer to install the man pages with meson (in a future commit). Note that now all the occurrences of the programs names have the API version as a suffix. Traditionally the example command lines looked like: gst-launch ... Now they look like: gst-launch-1.0 ... This reflects the actual programs names and makes it easier to copy and paste the example commands. Also, the .gitignore file is adjusted not to ignore the final man pages anymore. You may need to clean your src/build directory before pulling in this patch. https://bugzilla.gnome.org/show_bug.cgi?id=773917