[0.4.x] lv-tool: Add man page + ensure it stays in sync

.github/workflows/enforce-copies-of-help-output-in-sync.yml

@@ -0,0 +1,57 @@
+# Libvisual - The audio visualisation framework.
+#
+# Copyright (C) 2023 Libvisual team
+#
+# Authors: Sebastian Pipping <sebastian@pipping.org>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as
+# published by the Free Software Foundation; either version 2.1
+# of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+name: Enforce that copies of --help output are in sync
+
+on:
+- pull_request
+- push
+
+jobs:
+  help_output_in_sync:
+    name: Check if copies of --help output are in sync
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v3.2.0
+
+      - name: Install build dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install --yes --no-install-recommends \
+            autopoint \
+            gettext \
+            help2man \
+            libsdl1.2-dev
+
+      - name: Build lv-tool
+        run: |-
+          set -x
+          cd libvisual
+          ./autogen.sh
+          make -j
+
+      - name: Check if the man page is in sync with --help output
+        run: |-
+          set -x -o pipefail
+          cd libvisual/tools/lv-tool
+          rm lv-tool-0.4.1  # to enforce a diff for the generator to remove
+          PATH="${PWD}:${PATH}" ./sync-manpage-with-help-output.sh
+          COLUMNS=99 man ./lv-tool-0.4.1 | cat
+          git diff --exit-code -- lv-tool-0.4.1

libvisual/po/de.po

@@ -7,7 +7,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: libvisual 0.4.0-2.2\n"
 "Report-Msgid-Bugs-To: https://github.com/Libvisual/libvisual/issues/\n"
-"POT-Creation-Date: 2023-01-27 22:45+0100\n"
+"POT-Creation-Date: 2023-02-01 21:15+0100\n"
 "PO-Revision-Date: 2017-08-10 18:46+GMT\n"
 "Last-Translator: Chris Leick <c.leick@vollbio.de>\n"
 "Language-Team: German <debian-l10n-german@lists.debian.org>\n"
@@ -900,7 +900,7 @@ msgstr ""
 msgid "Invalid depth passed to the scaler"
 msgstr "Ungültige Tiefe an Scaler übergeben"
 
-#: tools/lv-tool/lv-tool.cpp:816 tools/lv-tool/lv-tool.cpp:913
+#: tools/lv-tool/lv-tool.cpp:837 tools/lv-tool/lv-tool.cpp:934
 msgid "lv-tool"
 msgstr ""
 

libvisual/po/es_AR.po

@@ -7,7 +7,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: Libvisual Library 0.4.0\n"
 "Report-Msgid-Bugs-To: https://github.com/Libvisual/libvisual/issues/\n"
-"POT-Creation-Date: 2023-01-27 22:45+0100\n"
+"POT-Creation-Date: 2023-02-01 21:15+0100\n"
 "PO-Revision-Date: 2005-03-20 17:09-0300\n"
 "Last-Translator:  <dprotti@users.sourceforge.net>\n"
 "Language-Team: Spanish\n"
@@ -918,7 +918,7 @@ msgstr ""
 msgid "Invalid depth passed to the scaler"
 msgstr "Profundidad pasada al escalador inválida"
 
-#: tools/lv-tool/lv-tool.cpp:816 tools/lv-tool/lv-tool.cpp:913
+#: tools/lv-tool/lv-tool.cpp:837 tools/lv-tool/lv-tool.cpp:934
 msgid "lv-tool"
 msgstr ""
 

libvisual/po/es_ES.po

@@ -7,7 +7,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: Libvisual Library 0.4.0\n"
 "Report-Msgid-Bugs-To: https://github.com/Libvisual/libvisual/issues/\n"
-"POT-Creation-Date: 2023-01-27 22:45+0100\n"
+"POT-Creation-Date: 2023-02-01 21:15+0100\n"
 "PO-Revision-Date: 2005-03-20 17:09-0300\n"
 "Last-Translator:  <dprotti@users.sourceforge.net>\n"
 "Language-Team: Spanish\n"
@@ -918,7 +918,7 @@ msgstr ""
 msgid "Invalid depth passed to the scaler"
 msgstr "Profundidad pasada al escalador inválida"
 
-#: tools/lv-tool/lv-tool.cpp:816 tools/lv-tool/lv-tool.cpp:913
+#: tools/lv-tool/lv-tool.cpp:837 tools/lv-tool/lv-tool.cpp:934
 msgid "lv-tool"
 msgstr ""
 

libvisual/po/libvisual-0.4.pot

@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: libvisual 0.4.1\n"
 "Report-Msgid-Bugs-To: https://github.com/Libvisual/libvisual/issues/\n"
-"POT-Creation-Date: 2023-01-27 22:45+0100\n"
+"POT-Creation-Date: 2023-02-01 21:15+0100\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: LANGUAGE <LL@li.org>\n"
@@ -871,6 +871,6 @@ msgstr ""
 msgid "Invalid depth passed to the scaler"
 msgstr ""
 
-#: tools/lv-tool/lv-tool.cpp:816 tools/lv-tool/lv-tool.cpp:913
+#: tools/lv-tool/lv-tool.cpp:837 tools/lv-tool/lv-tool.cpp:934
 msgid "lv-tool"
 msgstr ""

libvisual/tools/lv-tool/.gitignore

@@ -1 +1 @@
-/lv-tool
+/lv-tool-0.4

libvisual/tools/lv-tool/Makefile.am

@@ -8,3 +8,7 @@ lv_tool_0_4_SOURCES = lv-tool.cpp
 lv_tool_0_4_CPPFLAGS = -I$(top_srcdir) -I$(top_srcdir)/libvisual
 lv_tool_0_4_CXXFLAGS = $(SDL_CFLAGS)
 lv_tool_0_4_LDADD = $(SDL_LIBS) ../../libvisual/libvisual-@LIBVISUAL_VERSION_SUFFIX@.la
+
+man1_MANS = lv-tool-0.4.1
+
+EXTRA_DIST = lv-tool-0.4.1 sync-manpage-with-help-output.sh

libvisual/tools/lv-tool/lv-tool-0.4.1

@@ -0,0 +1,66 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man.
+.TH LV-TOOL-0.4 "1" "February 2023" "lv-tool-0.4 0.4.1" "User Commands"
+.SH NAME
+lv-tool-0.4 \- Command-line tool to interact with Libvisual
+.SH SYNOPSIS
+.B lv-tool-0.4
+[\fI\,options\/\fR]
+.SH DESCRIPTION
+.SS "Valid options:"
+.TP
+\fB\-\-help\fR,\ \fB\-h\fR
+This help text
+.TP
+\fB\-\-plugin\-help\fR,\ \fB\-p\fR
+List of installed plugins + information
+.TP
+\fB\-\-version\fR,\ \fB\-V\fR
+Print version and exit
+.TP
+\fB\-\-verbose\fR,\ \fB\-v\fR
+Increase log verbosity (may be used multiple times)
+.TP
+\fB\-\-dimensions\fR\ \c
+.IR wxh ,\ \fB\-D\fR\ \c
+.IR wxh 
+Request dimensions from display driver (no guarantee) [640x480]
+.TP
+\fB\-\-depth\fR\ \c
+.IR depth ,\ \fB\-c\fR\ \c
+.IR depth 
+Set output colour depth (automatic by default)
+.TP
+\fB\-\-input\fR\ \c
+.IR input ,\ \fB\-i\fR\ \c
+.IR input 
+Use this input plugin [debug]
+.TP
+\fB\-\-actor\fR\ \c
+.IR actor ,\ \fB\-a\fR\ \c
+.IR actor 
+Use this actor plugin [lv_gltest/lv_analyzer]
+.TP
+\fB\-\-seed\fR\ \c
+.IR seed ,\ \fB\-s\fR\ \c
+.IR seed 
+Set random seed
+.TP
+\fB\-\-fps\fR\ \c
+.IR n ,\ \fB\-f\fR\ \c
+.IR n 
+Limit output to n frames per second (if display driver supports it) [60]
+.TP
+\fB\-\-framecount\fR\ \c
+.IR n ,\ \fB\-F\fR\ \c
+.IR n 
+Output n frames,\ then exit.
+.TP
+\fB\-\-switch\fR\ \c
+.IR n ,\ \fB\-S\fR\ \c
+.IR n 
+Switch actor after n frames.
+.TP
+\fB\-\-exclude\fR\ \c
+.IR actors ,\ \fB\-x\fR\ \c
+.IR actors 
+Provide a list of actors to exclude.

libvisual/tools/lv-tool/lv-tool.cpp

@@ -512,23 +512,31 @@ namespace {
       }
   }
 
+  /** print commandline version */
+  void print_version(std::string const& name)
+  {
+      printf("%s %s\n", name.c_str (), PACKAGE_VERSION);
+  }
+
   /** print commandline help */
   void print_help(std::string const& name)
   {
-      printf("Usage: %s [options]\n\n"
+      printf("Usage: %s [options]\n"
+                  "\n"
                   "Valid options:\n"
-                  "\t--help\t\t\t-h\t\tThis help text\n"
-                  "\t--plugin-help\t\t-p\t\tList of installed plugins + information\n"
-                  "\t--verbose\t\t-v\t\tIncrease log verbosity (may be used multiple times)\n"
-                  "\t--dimensions <wxh>\t-D <wxh>\tRequest dimensions from display driver (no guarantee) [%dx%d]\n"
-                  "\t--depth <depth> \t-c <depth>\tSet output colour depth (automatic by default)\n"
-                  "\t--input <input>\t\t-i <input>\tUse this input plugin [%s]\n"
-                  "\t--actor <actor>\t\t-a <actor>\tUse this actor plugin [%s/%s]\n"
-                  "\t--seed <seed>\t\t-s <seed>\tSet random seed\n"
-                  "\t--fps <n>\t\t-f <n>\t\tLimit output to n frames per second (if display driver supports it) [%d]\n"
-                  "\t--framecount <n>\t-F <n>\t\tOutput n frames, then exit.\n"
-                  "\t--switch <n>\t\t-S <n>\t\tSwitch actor after n frames.\n"
-                  "\t--exclude <actors>\t-x <actors>\tProvide a list of actors to exclude.\n"
+                  "  --help, -h                       This help text\n"
+                  "  --plugin-help, -p                List of installed plugins + information\n"
+                  "  --version, -V                    Print version and exit\n"
+                  "  --verbose, -v                    Increase log verbosity (may be used multiple times)\n"
+                  "  --dimensions <wxh>, -D <wxh>     Request dimensions from display driver (no guarantee) [%dx%d]\n"
+                  "  --depth <depth>, -c <depth>      Set output colour depth (automatic by default)\n"
+                  "  --input <input>, -i <input>      Use this input plugin [%s]\n"
+                  "  --actor <actor>, -a <actor>      Use this actor plugin [%s/%s]\n"
+                  "  --seed <seed>, -s <seed>         Set random seed\n"
+                  "  --fps <n>, -f <n>                Limit output to n frames per second (if display driver supports it) [%d]\n"
+                  "  --framecount <n>, -F <n>         Output n frames, then exit.\n"
+                  "  --switch <n>, -S <n>             Switch actor after n frames.\n"
+                  "  --exclude <actors>, -x <actors>  Provide a list of actors to exclude.\n"
                   "\n",
                   name.c_str (),
                   width, height,
@@ -538,6 +546,14 @@ namespace {
                   frame_rate);
   }
 
+  void print_welcome()
+  {
+      // print warm welcome
+      std::cerr << "lv-tool" << " - "
+                << "Libvisual " << PACKAGE_VERSION
+                << " commandline tool - "
+                << PACKAGE_URL << "\n";
+  }
 
   /**
    * parse commandline arguments
@@ -550,6 +566,7 @@ namespace {
       static struct option loptions[] = {
           {"help",        no_argument,       0, 'h'},
           {"plugin-help", no_argument,       0, 'p'},
+          {"version",     no_argument,       0, 'V'},
           {"verbose",     no_argument,       0, 'v'},
           {"dimensions",  required_argument, 0, 'D'},
           {"input",       required_argument, 0, 'i'},
@@ -570,16 +587,24 @@ namespace {
           switch(argument) {
               // --help
               case 'h': {
+                  print_welcome();
                   print_help(argv[0]);
                   return 1;
               }
 
               // --plugin-help
               case 'p': {
+                  print_welcome();
                   print_plugin_help();
                   return 1;
               }
 
+              // --version
+              case 'V': {
+                  print_version(argv[0]);
+                  return 1;
+              }
+
               // --verbose
               case 'v': {
                   VisLogVerboseness level = visual_log_get_verboseness ();
@@ -725,12 +750,6 @@ namespace {
 int main (int argc, char **argv)
 {
     try {
-        // print warm welcome
-        std::cerr << "lv-tool" << " - "
-                  << "Libvisual " << PACKAGE_VERSION
-                  << " commandline tool - "
-                  << PACKAGE_URL << "\n";
-
         // setup signal handlers
         setup_signal_handlers ();
 
@@ -749,6 +768,8 @@ int main (int argc, char **argv)
             return EXIT_SUCCESS;
         }
 
+        print_welcome();
+
         // Set system-wide random seed
         if (have_seed) {
             visual_random_context_set_seed(&__lv_internal_random_context, seed);

libvisual/tools/lv-tool/sync-manpage-with-help-output.sh

@@ -0,0 +1,45 @@
+#! /usr/bin/env bash
+# Libvisual - The audio visualisation framework.
+#
+# Copyright (C) 2023 Libvisual team
+#
+# Authors: Sebastian Pipping <sebastian@pipping.org>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as
+# published by the Free Software Foundation; either version 2.1
+# of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+set -e -u -o pipefail
+
+_BUILD_MONTH=2023-02  # for reproducible builds; bump when doing releases
+
+help2man_args=(
+    --no-info
+    --name 'Command-line tool to interact with Libvisual'
+    lv-tool-0.4
+)
+sed_args=(
+    # Be robust towards version difference between local help2man and CI help2man
+    -e 's,It was generated by help2man .*,It was generated by help2man.,'
+
+    # Improve formatting of values in "--arg <value>"
+    -e 's, <\([^>]\+\)>,\\ \\c\n.IR \1 ,g'
+
+    # Fix lack of space after comma in e.g. "--input input,-i input"
+    -e 's|, |,\\ |g'
+)
+
+SOURCE_DATE_EPOCH="$(date --date="${_BUILD_MONTH}-15" +%s)" \
+    help2man "${help2man_args[@]}" \
+    | sed "${sed_args[@]}" \
+    > lv-tool-0.4.1