This is a massive rewrite of the help text and cli.rst section of the
manual. All command-line flags now have their own help and are
specifically index. qpdf --help is completely redone.
At one time, it seems that I was starting to use the <firstterm>
feature of docbook, but I forgot about it long ago, and there is
nothing consistent. In the absence of an actual glossary, just use
emphasis for terminology and don't tag it in any special way. This
could be fixed later if we wanted to.
Replace @1@replaceable@1@...@2@replaceable@2@ with
@3@replaceable@3@...@3@replaceable@3@ inside of :samp: and :file: so
that all remaining @1@replaceable@1@...@2@replaceable@2@ are outside.
Since the {...} syntax for replaceable only works in :samp: and
:file:, we will have to enclose the remaining ones in :samp: for them
to work.
:option: is stronger and assumes a reference to a list of options.
Since we don't have that yet, just use :samp: for options. Inside
literal code blocks, there is no expansion, so just remove markup.
Pandoc indented lists with two spaces after the dash, which is ugly
and messes up emacs fill-paragraph. I transformed the spacing using a
combination of this perl script and manual edits. I verified that the
HTML generated by sphinx was identical before and after the edits and
that this commit contains only whitespace changes. The perl script as
it stands does not do indentation quite right for variable lists, but
there were only about 8 cases that it missed, so I just fixed them
manually.
```perl
#!/usr/bin/env perl
require 5.008;
use warnings;
use strict;
use File::Basename;
my $whoami = basename($0);
my @liststack = ();
while (<>)
{
if (m/^( *- )\S/)
{
my $pre = $1;
while ((scalar(@liststack) > 0) &&
($liststack[-1] >= length($pre)))
{
pop(@liststack);
}
if ((scalar(@liststack) == 0) && ($pre =~ m/^ /))
{
push(@liststack, 1);
}
push(@liststack, length($pre));
my $n = scalar(@liststack);
#print "** $n\n";
my $newpre = (' ' x ($n - 1)) . '- ';
s/^$pre/$newpre/;
}
elsif (scalar(@liststack) > 0)
{
if ($_ ne "\n")
{
while (scalar(@liststack) > 0)
{
my $pre = m/^( *)/;
if (length($1) < $liststack[-1])
{
#print "XXX pop\n";
pop(@liststack);
}
else
{
last;
}
}
my $n = scalar(@liststack);
#print "** $n\n";
my $indent = ' ' x $n;
s/^ +/$indent/;
}
}
print;
}
```
