From 161bca5c0c43111f5d615330ed014294e6f964e3 Mon Sep 17 00:00:00 2001 From: Sebastian Pipping Date: Thu, 2 Feb 2023 19:41:00 +0100 Subject: [PATCH 1/7] lv-tool: Propagate lv-tool-0.4 rename to .gitignore --- libvisual/tools/lv-tool/.gitignore | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/libvisual/tools/lv-tool/.gitignore b/libvisual/tools/lv-tool/.gitignore index f1474ce89..ee9f4a83f 100644 --- a/libvisual/tools/lv-tool/.gitignore +++ b/libvisual/tools/lv-tool/.gitignore @@ -1 +1 @@ -/lv-tool +/lv-tool-0.4 From d6fad4314054ee995622d233ca0c968b2b31f059 Mon Sep 17 00:00:00 2001 From: Sebastian Pipping Date: Wed, 1 Feb 2023 19:16:12 +0100 Subject: [PATCH 2/7] lv-tool: Make --help output more friendly to help2man .. and more readable in source code. --- libvisual/tools/lv-tool/lv-tool.cpp | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/libvisual/tools/lv-tool/lv-tool.cpp b/libvisual/tools/lv-tool/lv-tool.cpp index 33d07c890..cca539460 100644 --- a/libvisual/tools/lv-tool/lv-tool.cpp +++ b/libvisual/tools/lv-tool/lv-tool.cpp @@ -515,20 +515,21 @@ namespace { /** 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 \t-D \tRequest dimensions from display driver (no guarantee) [%dx%d]\n" - "\t--depth \t-c \tSet output colour depth (automatic by default)\n" - "\t--input \t\t-i \tUse this input plugin [%s]\n" - "\t--actor \t\t-a \tUse this actor plugin [%s/%s]\n" - "\t--seed \t\t-s \tSet random seed\n" - "\t--fps \t\t-f \t\tLimit output to n frames per second (if display driver supports it) [%d]\n" - "\t--framecount \t-F \t\tOutput n frames, then exit.\n" - "\t--switch \t\t-S \t\tSwitch actor after n frames.\n" - "\t--exclude \t-x \tProvide a list of actors to exclude.\n" + " --help, -h This help text\n" + " --plugin-help, -p List of installed plugins + information\n" + " --verbose, -v Increase log verbosity (may be used multiple times)\n" + " --dimensions , -D Request dimensions from display driver (no guarantee) [%dx%d]\n" + " --depth , -c Set output colour depth (automatic by default)\n" + " --input , -i Use this input plugin [%s]\n" + " --actor , -a Use this actor plugin [%s/%s]\n" + " --seed , -s Set random seed\n" + " --fps , -f Limit output to n frames per second (if display driver supports it) [%d]\n" + " --framecount , -F Output n frames, then exit.\n" + " --switch , -S Switch actor after n frames.\n" + " --exclude , -x Provide a list of actors to exclude.\n" "\n", name.c_str (), width, height, From 138908e36526bf6cb3c03468dc9c5b47cbbe3151 Mon Sep 17 00:00:00 2001 From: Sebastian Pipping Date: Wed, 1 Feb 2023 19:51:07 +0100 Subject: [PATCH 3/7] lv-tool: Add --version for help2man and humans --- libvisual/tools/lv-tool/lv-tool.cpp | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/libvisual/tools/lv-tool/lv-tool.cpp b/libvisual/tools/lv-tool/lv-tool.cpp index cca539460..5f3255ce4 100644 --- a/libvisual/tools/lv-tool/lv-tool.cpp +++ b/libvisual/tools/lv-tool/lv-tool.cpp @@ -512,6 +512,12 @@ 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) { @@ -520,6 +526,7 @@ namespace { "Valid options:\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 , -D Request dimensions from display driver (no guarantee) [%dx%d]\n" " --depth , -c Set output colour depth (automatic by default)\n" @@ -551,6 +558,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'}, @@ -581,6 +589,12 @@ namespace { return 1; } + // --version + case 'V': { + print_version(argv[0]); + return 1; + } + // --verbose case 'v': { VisLogVerboseness level = visual_log_get_verboseness (); From 10119f9b88cdb467043fc1592c5b3b0674b73e10 Mon Sep 17 00:00:00 2001 From: Sebastian Pipping Date: Wed, 1 Feb 2023 19:51:16 +0100 Subject: [PATCH 4/7] lv-tool: Skip welcome banner for --version --- libvisual/tools/lv-tool/lv-tool.cpp | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/libvisual/tools/lv-tool/lv-tool.cpp b/libvisual/tools/lv-tool/lv-tool.cpp index 5f3255ce4..f0559ec4a 100644 --- a/libvisual/tools/lv-tool/lv-tool.cpp +++ b/libvisual/tools/lv-tool/lv-tool.cpp @@ -546,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 @@ -579,12 +587,14 @@ 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; } @@ -740,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 (); @@ -764,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); From 11581ac5b7015fc069f4a201869863cd65401240 Mon Sep 17 00:00:00 2001 From: Sebastian Pipping Date: Wed, 1 Feb 2023 21:01:18 +0100 Subject: [PATCH 5/7] lv-tool: Add and integrate man page --- libvisual/tools/lv-tool/Makefile.am | 4 ++ libvisual/tools/lv-tool/lv-tool-0.4.1 | 66 +++++++++++++++++++ .../lv-tool/sync-manpage-with-help-output.sh | 45 +++++++++++++ 3 files changed, 115 insertions(+) create mode 100644 libvisual/tools/lv-tool/lv-tool-0.4.1 create mode 100755 libvisual/tools/lv-tool/sync-manpage-with-help-output.sh diff --git a/libvisual/tools/lv-tool/Makefile.am b/libvisual/tools/lv-tool/Makefile.am index 9babf5d5f..fd995d78b 100644 --- a/libvisual/tools/lv-tool/Makefile.am +++ b/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 diff --git a/libvisual/tools/lv-tool/lv-tool-0.4.1 b/libvisual/tools/lv-tool/lv-tool-0.4.1 new file mode 100644 index 000000000..ce9b1032c --- /dev/null +++ b/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. diff --git a/libvisual/tools/lv-tool/sync-manpage-with-help-output.sh b/libvisual/tools/lv-tool/sync-manpage-with-help-output.sh new file mode 100755 index 000000000..b9e976f5c --- /dev/null +++ b/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 +# +# 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 " + -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 From 51a6586ca2c15e3b1bc70bdfad40f67451b3d305 Mon Sep 17 00:00:00 2001 From: Sebastian Pipping Date: Wed, 1 Feb 2023 21:16:06 +0100 Subject: [PATCH 6/7] lv-tool: Sync translation --- libvisual/po/de.po | 4 ++-- libvisual/po/es_AR.po | 4 ++-- libvisual/po/es_ES.po | 4 ++-- libvisual/po/libvisual-0.4.pot | 4 ++-- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/libvisual/po/de.po b/libvisual/po/de.po index fc59557e4..b92cdd716 100644 --- a/libvisual/po/de.po +++ b/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 \n" "Language-Team: German \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 "" diff --git a/libvisual/po/es_AR.po b/libvisual/po/es_AR.po index 5fabb2add..0dd3b67be 100644 --- a/libvisual/po/es_AR.po +++ b/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: \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 "" diff --git a/libvisual/po/es_ES.po b/libvisual/po/es_ES.po index 1d6fd63af..4ad84219e 100644 --- a/libvisual/po/es_ES.po +++ b/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: \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 "" diff --git a/libvisual/po/libvisual-0.4.pot b/libvisual/po/libvisual-0.4.pot index 07b6b2fc6..534038748 100644 --- a/libvisual/po/libvisual-0.4.pot +++ b/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 \n" "Language-Team: LANGUAGE \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 "" From 16e963419e2ace09fa19fc0144b102474d5df340 Mon Sep 17 00:00:00 2001 From: Sebastian Pipping Date: Wed, 1 Feb 2023 21:09:43 +0100 Subject: [PATCH 7/7] Actions: Enforce that lv-tool man page stays in sync with --help output --- .../enforce-copies-of-help-output-in-sync.yml | 57 +++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 .github/workflows/enforce-copies-of-help-output-in-sync.yml diff --git a/.github/workflows/enforce-copies-of-help-output-in-sync.yml b/.github/workflows/enforce-copies-of-help-output-in-sync.yml new file mode 100644 index 000000000..4909e777a --- /dev/null +++ b/.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 +# +# 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