Make --help output more friendly to help2man

This commit is contained in:
Johannes 'josch' Schauer 2017-01-20 05:17:23 +01:00
parent ef36e86a46
commit 4040e907a3

View file

@ -1331,10 +1331,11 @@ useful to convert JPEG and JPEG2000 images to PDF.
The output is sent to standard output so that it can be redirected into a file The output is sent to standard output so that it can be redirected into a file
or to another program as part of a shell pipe. To directly write the output or to another program as part of a shell pipe. To directly write the output
into a file, use the -o or --output option. into a file, use the -o or --output option.
Options:
''', ''',
epilog='''\ epilog='''\
Colorspace Colorspace:
Currently, the colorspace must be forced for JPEG 2000 images that are not in Currently, the colorspace must be forced for JPEG 2000 images that are not in
the RGB colorspace. Available colorspace options are based on Python Imaging the RGB colorspace. Available colorspace options are based on Python Imaging
Library (PIL) short handles. Library (PIL) short handles.
@ -1345,8 +1346,7 @@ Colorspace
CMYK CMYK color CMYK CMYK color
CMYK;I CMYK color with inversion (for CMYK JPEG files from Adobe) CMYK;I CMYK color with inversion (for CMYK JPEG files from Adobe)
Paper sizes Paper sizes:
You can specify the short hand paper size names shown in the first column in You can specify the short hand paper size names shown in the first column in
the table below as arguments to the --pagesize and --imgsize options. The the table below as arguments to the --pagesize and --imgsize options. The
width and height they are mapping to is shown in the second column. Giving width and height they are mapping to is shown in the second column. Giving
@ -1357,8 +1357,7 @@ Paper sizes
%s %s
Fit options Fit options:
The img2pdf options for the --fit argument are shown in the first column in The img2pdf options for the --fit argument are shown in the first column in
the table below. The function of these options can be mapped to the geometry the table below. The function of these options can be mapped to the geometry
operators of imagemagick. For users who are familiar with imagemagick, the operators of imagemagick. For users who are familiar with imagemagick, the
@ -1382,8 +1381,32 @@ Fit options
enlarge | < | Y | Enlarges an image with dimensions smaller than the given enlarge | < | Y | Enlarges an image with dimensions smaller than the given
| | | ones (and otherwise behaves like "into"). | | | ones (and otherwise behaves like "into").
Examples Argument parsing:
Argument long options can be abbreviated to a prefix if the abbreviation is
anambiguous. That is, the prefix must match a unique option.
Beware of your shell interpreting argument values as special characters (like
the semicolon in the CMYK;I colorspace option). If in doubt, put the argument
values in single quotes.
If you want an argument value to start with one or more minus characters, you
must use the long option name and join them with an equal sign like so:
$ img2pdf --author=--test--
If your input file name starts with one or more minus characters, either
separate the input files from the other arguments by two minus signs:
$ img2pdf -- --my-file-starts-with-two-minuses.jpg
Or be more explicit about its relative path by prepending a ./:
$ img2pdf ./--my-file-starts-with-two-minuses.jpg
The order of non-positional arguments (all arguments other than the input
images) does not matter.
Examples:
Lines starting with a dollar sign denote commands you can enter into your Lines starting with a dollar sign denote commands you can enter into your
terminal. The dollar sign signifies your command prompt. It is not part of terminal. The dollar sign signifies your command prompt. It is not part of
the command you type. the command you type.
@ -1415,31 +1438,9 @@ Examples
$ img2pdf --output out.pdf --colorspace L input.jp2 $ img2pdf --output out.pdf --colorspace L input.jp2
Argument parsing Written by Johannes 'josch' Schauer <josch@mister-muffin.de>
Argument long options can be abbreviated to a prefix if the abbreviation is Report bugs at https://gitlab.mister-muffin.de/josch/img2pdf/issues
anambiguous. That is, the prefix must match a unique option.
Beware of your shell interpreting argument values as special characters (like
the semicolon in the CMYK;I colorspace option). If in doubt, put the argument
values in single quotes.
If you want an argument value to start with one or more minus characters, you
must use the long option name and join them with an equal sign like so:
$ img2pdf --author=--test--
If your input file name starts with one or more minus characters, either
separate the input files from the other arguments by two minus signs:
$ img2pdf -- --my-file-starts-with-two-minuses.jpg
Or be more explicit about its relative path by prepending a ./:
$ img2pdf ./--my-file-starts-with-two-minuses.jpg
The order of non-positional arguments (all arguments other than the input
images) does not matter.
''' % rendered_papersizes) ''' % rendered_papersizes)
parser.add_argument( parser.add_argument(
@ -1460,7 +1461,7 @@ Argument parsing
outargs = parser.add_argument_group( outargs = parser.add_argument_group(
title='General output arguments', title='General output arguments',
description='') description='Arguments controlling the output format.')
outargs.add_argument( outargs.add_argument(
'-o', '--output', metavar='out', type=argparse.FileType('wb'), '-o', '--output', metavar='out', type=argparse.FileType('wb'),
@ -1503,8 +1504,7 @@ RGB.''')
sizeargs = parser.add_argument_group( sizeargs = parser.add_argument_group(
title='Image and page size and layout arguments', title='Image and page size and layout arguments',
description='''\ description='''\
Every input image will be placed on its own page. The image size is controlled
Every input image will be placed on its own page. The image size is controlled
by the dpi value of the input image or, if unset or missing, the default dpi of by the dpi value of the input image or, if unset or missing, the default dpi of
%.2f. By default, each page will have the same size as the image it shows. %.2f. By default, each page will have the same size as the image it shows.
Thus, there will be no visible border between the image and the page border by Thus, there will be no visible border between the image and the page border by
@ -1593,8 +1593,10 @@ of the input image. If the orientation of a page gets flipped, then so do the
values set via the --border option. values set via the --border option.
''') ''')
metaargs = parser.add_argument_group(title='Arguments setting metadata', metaargs = parser.add_argument_group(
description='') title='Arguments setting metadata',
description='Options handling embedded timestamps, title and author '
'information.')
metaargs.add_argument( metaargs.add_argument(
'--title', metavar='title', type=str, '--title', metavar='title', type=str,
help='Sets the title metadata value') help='Sets the title metadata value')