From e72fc73821781e72d20730f0f79c2a16f52cc947 Mon Sep 17 00:00:00 2001 From: Werner Lemberg Date: Thu, 31 Jul 2008 14:35:20 +0200 Subject: [PATCH] Improve man pages in `scripts' directory. help2man is quite picky: . It needs newlines to properly identify the various sections. . Examples must start with a shell prompt character. . Multiple usage lines needs the same indentation. . I've replaced the `Bugs' string with an empty one in the call to the `addoption_group' since it confuses help2man otherwise. Note that man page output is still not optimal yet; some constructs can't be handled well by automatic parsing. --- scripts/abc2ly.py | 5 +++-- scripts/convert-ly.py | 8 ++++---- scripts/etf2ly.py | 5 +++-- scripts/lilypond-book.py | 15 ++++++++------- scripts/lilysong.py | 10 +++++----- scripts/midi2ly.py | 7 +++---- scripts/musicxml2ly.py | 28 ++++++++++++++++------------ 7 files changed, 42 insertions(+), 36 deletions(-) diff --git a/scripts/abc2ly.py b/scripts/abc2ly.py index 05edf98ae5..be84071e9f 100644 --- a/scripts/abc2ly.py +++ b/scripts/abc2ly.py @@ -1341,7 +1341,8 @@ def print_version (): def get_option_parser (): p = ly.get_option_parser (usage=_ ("%s [OPTION]... FILE") % 'abc2ly', description=_ ('''abc2ly converts ABC music files (see -%s) to LilyPond input.''') % 'http://www.gre.ac.uk/~c.walshaw/abc2mtex/abc.txt', +%s) to LilyPond input. +''') % 'http://www.gre.ac.uk/~c.walshaw/abc2mtex/abc.txt', add_help_option=False) p.version = "abc2ly (LilyPond) @TOPLEVEL_VERSION@" @@ -1358,7 +1359,7 @@ def get_option_parser (): p.add_option ('-s', '--strict', help=_ ("be strict about success"), action='store_true') p.add_option ('-b', '--beams', help=_ ("preserve ABC's notion of beams")) - p.add_option_group (ly.display_encode (_ ('Bugs')), + p.add_option_group ('', description=(_ ('Report bugs via') + ''' http://post.gmane.org/post.php''' '''?group=gmane.comp.gnu.lilypond.bugs\n''')) diff --git a/scripts/convert-ly.py b/scripts/convert-ly.py index 708214d315..9bc0a14005 100644 --- a/scripts/convert-ly.py +++ b/scripts/convert-ly.py @@ -32,8 +32,8 @@ _ ('''Update LilyPond input to newer version. By default, update from the version taken from the \\version command, to the current LilyPond version.''') + _ ("Examples:") + ''' - convert-ly -e old.ly - convert-ly --from=2.3.28 --to 2.5.21 foobar.ly + $ convert-ly -e old.ly + $ convert-ly --from=2.3.28 --to=2.5.21 foobar.ly > foobar-new.ly ''') copyright = ('Jan Nieuwenhuizen ', @@ -105,7 +105,7 @@ def get_option_parser (): default=False) p.add_option ("-s", '--show-rules', - help=_ ("show rules [default: --from=0, --to=%s]") % program_version, + help=_ ("show rules [default: -f 0, -t %s]") % program_version, dest='show_rules', action='store_true', default=False) @@ -116,7 +116,7 @@ def get_option_parser (): dest="to_version", default='') - p.add_option_group (ly.display_encode (_ ('Bugs')), + p.add_option_group ('', description=(_ ("Report bugs via") + ''' http://post.gmane.org/post.php''' '''?group=gmane.comp.gnu.lilypond.bugs\n''')) diff --git a/scripts/etf2ly.py b/scripts/etf2ly.py index 5377727d80..39a6fba4ab 100644 --- a/scripts/etf2ly.py +++ b/scripts/etf2ly.py @@ -1178,7 +1178,8 @@ Copyright (c) %s by def get_option_parser (): p = ly.get_option_parser (usage=_ ("%s [OPTION]... ETF-FILE") % 'etf2ly', description=_ ("""Enigma Transport Format is a format used by Coda Music Technology's -Finale product. etf2ly converts a subset of ETF to a ready-to-use LilyPond file."""), +Finale product. etf2ly converts a subset of ETF to a ready-to-use LilyPond file. +"""), add_help_option=False) p.add_option("-h", "--help", action="help", @@ -1194,7 +1195,7 @@ Finale product. etf2ly converts a subset of ETF to a ready-to-use LilyPond file action='store_true', ), - p.add_option_group (ly.display_encode (_ ('Bugs')), + p.add_option_group ('', description=(_ ('Report bugs via') + ''' http://post.gmane.org/post.php''' '''?group=gmane.comp.gnu.lilypond.bugs\n''')) diff --git a/scripts/lilypond-book.py b/scripts/lilypond-book.py index 630f6067de..1f925c13bd 100644 --- a/scripts/lilypond-book.py +++ b/scripts/lilypond-book.py @@ -58,9 +58,9 @@ _ ("Process LilyPond snippets in hybrid HTML, LaTeX, texinfo or DocBook document + '\n\n' + _ ("Examples:") + ''' - lilypond-book --filter="tr '[a-z]' '[A-Z]'" %(BOOK)s - lilypond-book --filter="convert-ly --no-version --from=2.0.0 -" %(BOOK)s - lilypond-book --process='lilypond -I include' %(BOOK)s + $ lilypond-book --filter="tr '[a-z]' '[A-Z]'" %(BOOK)s + $ lilypond-book -F "convert-ly --no-version --from=2.0.0 -" %(BOOK)s + $ lilypond-book --process='lilypond -I include' %(BOOK)s ''' % {'BOOK': _ ("BOOK")}) authors = ('Jan Nieuwenhuizen ', @@ -113,11 +113,12 @@ def get_option_parser (): p.add_option ('-F', '--filter', metavar=_ ("FILTER"), action="store", dest="filter_cmd", - help=_ ("pipe snippets through FILTER [convert-ly -n -]"), + help=_ ("pipe snippets through FILTER [default: `convert-ly -n -']"), default=None) p.add_option ('-f', '--format', help=_ ("use output format FORMAT (texi [default], texi-html, latex, html, docbook)"), + metavar=_ ("FORMAT"), action='store') p.add_option("-h", "--help", @@ -155,7 +156,7 @@ def get_option_parser (): default='') p.add_option ('--skip-lily-check', - help=_ ("do not fail if no lilypond output is found."), + help=_ ("do not fail if no lilypond output is found"), metavar=_ ("DIR"), action='store_true', dest='skip_lilypond_run', default=False) @@ -167,7 +168,7 @@ def get_option_parser (): default=False) p.add_option ('--lily-output-dir', - help=_ ("write lily-XXX files to DIR, link into --output dir."), + help=_ ("write lily-XXX files to DIR, link into --output dir"), metavar=_ ("DIR"), action='store', dest='lily_output_dir', default=None) @@ -196,7 +197,7 @@ def get_option_parser (): p.add_option ('-w', '--warranty', help=_ ("show warranty and copyright"), action='store_true') - p.add_option_group (ly.display_encode (_ ('Bugs')), + p.add_option_group ('', description=( _ ("Report bugs via") + ' http://post.gmane.org/post.php?group=gmane.comp.gnu.lilypond.bugs\n')) diff --git a/scripts/lilysong.py b/scripts/lilysong.py index 18d047a137..adc6f57526 100644 --- a/scripts/lilysong.py +++ b/scripts/lilysong.py @@ -36,14 +36,14 @@ import tempfile FESTIVAL_COMMAND = 'festival --pipe' VOICE_CODINGS = {'voice_czech_ph': 'iso-8859-2'} -_USAGE = """lilysong [ -p PLAY-PROGRAM ] FILE.xml [ LANGUAGE-CODE-OR-VOICE [ SPEEDUP ] ] -./lilysong FILE.ly [ LANGUAGE-CODE-OR-VOICE ] -./lilysong --list-voices -./lilysong --list-languages +_USAGE = """lilysong [-p PLAY-PROGRAM] FILE.xml [LANGUAGE-CODE-OR-VOICE [SPEEDUP]] + lilysong FILE.ly [LANGUAGE-CODE-OR-VOICE] + lilysong --list-voices + lilysong --list-languages """ def usage (): - print 'usage:', _USAGE + print 'Usage:', _USAGE sys.exit (2) def process_options (args): diff --git a/scripts/midi2ly.py b/scripts/midi2ly.py index 4b5f2507aa..6ddc78ae71 100644 --- a/scripts/midi2ly.py +++ b/scripts/midi2ly.py @@ -844,7 +844,7 @@ def convert_midi (in_file, out_file): def get_option_parser (): p = ly.get_option_parser (usage=_ ("%s [OPTION]... FILE") % 'midi2ly', - description=_ ("Convert %s to LilyPond input.") % 'MIDI', + description=_ ("Convert %s to LilyPond input.\n") % 'MIDI', add_help_option=False) p.add_option ('-a', '--absolute-pitches', @@ -888,10 +888,9 @@ def get_option_parser (): p.add_option_group (ly.display_encode (_ ("Examples")), description = r''' - midi2ly --key=-2:1 --duration-quant=32 \ - --allow-tuplet=4*2/3 --allow-tuplet=2*4/3 foo.midi + $ midi2ly --key=-2:1 --duration-quant=32 --allow-tuplet=4*2/3 --allow-tuplet=2*4/3 foo.midi ''') - p.add_option_group (ly.display_encode (_ ('Bugs')), + p.add_option_group ('', description=(_ ('Report bugs via') + ''' http://post.gmane.org/post.php''' '''?group=gmane.comp.gnu.lilypond.bugs\n''')) diff --git a/scripts/musicxml2ly.py b/scripts/musicxml2ly.py index c6e7dd53c2..886479a893 100644 --- a/scripts/musicxml2ly.py +++ b/scripts/musicxml2ly.py @@ -2141,26 +2141,30 @@ def get_all_voices (parts): def option_parser (): - p = ly.get_option_parser (usage = _ ("musicxml2ly [options] FILE.xml"), - description = _ ("Convert MusicXML from FILE.xml to LilyPond input. If the given filename is -, musicxml2ly reads from the command line.") + "\n", - add_help_option=False) + p = ly.get_option_parser (usage = _ ("musicxml2ly [OPTION]... FILE.xml"), + description = +_ ("""Convert MusicXML from FILE.xml to LilyPond input. +If the given filename is -, musicxml2ly reads from the command line. +"""), add_help_option=False) p.add_option("-h", "--help", action="help", help=_ ("show this help and exit")) p.version = ('''%prog (LilyPond) @TOPLEVEL_VERSION@\n\n''' - + -_ ("""This program is free software. It is covered by the GNU General Public -License and you are welcome to change it and/or distribute copies of it -under certain conditions. Invoke as `%s --warranty' for more -information.""") % 'lilypond' -+ """ -Copyright (c) 2005--2008 by ++ +_ ("""Copyright (c) 2005--2008 by Han-Wen Nienhuys , Jan Nieuwenhuizen and Reinhold Kainhofer -""") +""" ++ +""" +This program is free software. It is covered by the GNU General Public +License and you are welcome to change it and/or distribute copies of it +under certain conditions. Invoke as `%s --warranty' for more +information.""") % 'lilypond') + p.add_option("--version", action="version", help=_ ("show version number and exit")) @@ -2217,7 +2221,7 @@ Copyright (c) 2005--2008 by type = 'string', dest = 'output_name', help = _ ("set output filename to FILE, stdout if -")) - p.add_option_group (ly.display_encode (_ ('Bugs')), + p.add_option_group ('', description = (_ ("Report bugs via") + ''' http://post.gmane.org/post.php''' '''?group=gmane.comp.gnu.lilypond.bugs\n''')) -- 2.39.2