[Docutils-users] Problems formatting options in man page

[Skip Montanaro]

I'm trying to have my cake and eat it too. Perhaps someone here can help
with that quest.

I have a script. When run with the -h flag it emits the script's doc string
formatted using rst. I want to process that output into man pages (using
rst2man). For the most part, that works just fine. But I'm having trouble
seeing how I'm supposed to indent multi-line descriptions of the script's
command line flags. Here is the OPTIONS section of the doc string:

OPTIONS
=======

-f x,y[,axis[,color[,legend[,style[,marker]]]]] plot field x vs. field y
-b x,y,val,c set background to c where field y value >= val at x
-p file if given, will save the plot to the named file and exit.
-F fmt plot the X axis using fmt (default varies)
-s sep use sep as the field separator (default is comma)
-d dimension specify dimensions in (I think) inches, default 8 wide, 6 high
-T title set title of the plot
-r label set the label for the right y axis
-l label set the label for the left y axis
-x label set the label for the x axis
-H skip header at start of input
-L do not create a legend
-Y min:max[,min:max] set the initial min and max values for the left (and
optionally, right) Y axis

That last line is the problem. I generate my man page using this make
recipe:

python $< -h 2>&1 | rst2man \
| sed -e '/^\.de1 rstReportMargin/,/^\.\./d' \
-e '/^\.de1 INDENT/,/^\.\./d' \
-e '/^\.de UNINDENT/,/^\.\./d' \
| egrep -v '^\.(UN)?INDENT' > $@

The sed and grep commands are just a little cleanup. The problem is with
rst2man. It complains:

<stdin>:40: (ERROR/3) Unexpected indentation.

It appears it is complaining about the second line of the -Y description.
Is there some way to format this section so when simply spit to
stdout/stderr it reads okay (no lines greater than 80 columns), yet passes
muster when fed to rst2man?

Thx,

Skip

[Skip Montanaro]

Post by Skip Montanaro
I have a script. When run with the -h flag it emits the script's doc string
formatted using rst. I want to process that output into man pages (using
rst2man). For the most part, that works just fine. But I'm having trouble
seeing how I'm supposed to indent multi-line descriptions of the script's
command line flags.

I may have figured some/all of this out on my own, partly by tweaking
the docstring, and partly by updating docutils (we had been running
0.8) and deleting the sed and grep scripts after rst2man. (I think the
sed and grep commands were working around a bug in 0.8, but not doing
a very good job.)

Skip