Re: address@hidden: help2man and indented help text]

[Alfred M. Szmidt]

   >I don't know how help2man does this in detail, but wouldn't it
   >work just to see if the next line as a option (either, -s or
   >--short).  And assume that if doesn't, that it is a continuation?
   >This would solve all cases I think.

   Perhaps, although it's been my experience that mucking with the
   logic to fix once case breaks another.

I can't think of any cases where the purposed "logic" would break any
previous case.

   There are conceivably cases where options are interspersed with
   text that is not meant to be part of the option description.

True, but I cannot think of any such text that starts in a different
column other then zero.  Atleast not in any GNU program.  Do you know
of any such output?

   >Then even something like:
   >
   >       -v, --very-long-option-name
   >                       is described on this line,
   >                         and this one...
   >
   >                         more text...
   >                       even more text
   >
   >Would work; since we only stop scanning when we come to a new
   >option.

   I'm not quite sure why you'd actually *want* to do this,

Well, it was a obscure example of what "new" things would be allowed.
Not that I would recommened the above.

   and taking the two real-world examples from the initial report, I
   don't believe that the current output is clearer, or more
   consistent than:

     -S                         sort by file size
         --sort=WORD            extension -X, none -U, size -S, time -t,
                                 version -v, status -c, time -t, atime -u,
                                 access -u, use -u

Agreed that this is clearer, but I still consider it a bug not to be
able to write a --help entry as it was written previously.

   [...]

     -H, --dereference-command-line
                                  follow symbolic links listed on the command 
line
         --dereference-command-line-symlink-to-dir
                                  follow each command line symbolic link
                                  that points to a directory

This makes things harder to read, which is why I think that help2man
should be more sane able handling such cases where the text is
indented.  It also doesn't make sense to say that "sometimes you can
indent the text, and other times you cannot" (--sort has the text
indented, while this one doesn't); this is both confusing to those who
write the --help output, and those who read it.


Cheers.