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.

diff --git a/scripts/abc2ly.py b/scripts/abc2ly.py
index 05edf98ae5f339c000408080a8586e5a942aacd8..be84071e9f817c0d679afb15c95ff716827b5964 100644 (file)
--- 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 708214d3154fce87e7d8698328bdb95a15e761ca..9bc0a1400581d8abae7b461e885d1c2ca9ec4961 100644 (file)
--- 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 <janneke@gnu.org>',
@@ -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 5377727d80f6da893ccd0225bc902dee9e513a01..39a6fba4abf08c2cc1a68c05aa95769539df7ec3 100644 (file)
--- 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 630f6067decdd6b878aa8c7ddda34b956288f1fe..1f925c13bde7094a954d579f3e64c35cc4bc0c08 100644 (file)
--- 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 <janneke@gnu.org>',
@@ -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 18d047a137686b4423b007934d7319387ac1d94f..adc6f57526cf8e608ca464b5df4f00628d2098ce 100644 (file)
--- 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 4b5f2507aa4f424eacc10d4d7583398af9acbb23..6ddc78ae71df89b232885bf982493179a1fc13a0 100644 (file)
--- 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 c6e7dd53c226d427d32aa9f160714aa67cfd4404..886479a8936cfaaaa08f2117e2e6c177fcb7e037 100644 (file)
--- 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 <hanwen@xs4all.nl>,
     Jan Nieuwenhuizen <janneke@gnu.org> and
     Reinhold Kainhofer <reinhold@kainhofer.com>
-""")
+"""
++
+"""
+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'''))