[bug #63958] [mdoc] decide how to set up hanging indent in Synopsis sections

[G. Branden Robinson]

Follow-up Comment #10, bug #63958 (project groff):

Hi Thorsten,

Please use Savannah's +verbatim+ and -verbatim- tokens (on lines by
themselves) when quoting literal content; it may protect us from confusion
imposed by helpful >cough< HTML formatting.

[comment #9 comment #9:]
> FWIW, AT&T nroff renders it as:
> 
> $ nrcon -mdoc /tmp/x | less
> timerdday(3)               BSD Programmer's Manual               
timerdday(3)
> 
> NAME
>      timerdday - compute time of launch operation within window
> 
> SYNOPSIS
>      void
>      timerdday(struct-timespec *earliest, struct-timespec *latest, struct-
>              timespec *resolution);
> 
> DESCRIPTION
>      Compute the optimal start time for a desired event to occur between
times
>      earliest and latest to within a granularity of resolution.
> 
> MirBSD #10-current               June 6, 1944                               
1
> 
> 
> For this, I did have to change the source though, to…
> 
> $ cat /tmp/x
> .Dd June 6, 1944
> .Dt timerdday 3
> .Os
> .Sh NAME
> .Nm timerdday
> .Nd compute time of launch operation within window
> .Sh SYNOPSIS
> .Ft void
> .Fn timerdday "\%struct-timespec *earliest" \
> "\%struct-timespec *latest" "\%struct-timespec *resolution"
> .Sh DESCRIPTION
> Compute the optimal start time for a desired event to occur between
> times
> .Va earliest No and Va latest
> to within a granularity of
> .Va resolution .
> 
> … to make it compile correctly (3bsd → 3, .Sh arguments uppercase as the
comparision is case-sensitive).

Neither of these surprise me with respect to "old school mdoc(7)".
 
> The use of \% there is odd,

It's no longer necessary, either, per comment #0 here and bug #63957.

> I’d rather use \- there (which is needed to avoid getting ‐ anyway),

Well, as Ingo pointed out, it's not syntactically valid in C to have a literal
hyphen in a type name.

However, it's a _completely_ academic question, or at least won't be if anyone
ever writes man pages for Lisp modules.

> but that leaves us with…
> 
> SYNOPSIS
>      void
>      timerdday(struct-timespec *earliest, struct-timespec *latest, -
>              struct-timespec *resolution);
> 
> … which is also not right.

I smell a bug in the USB mdoc macro package.  The fact that \% changes its
meaning depending on where it occurs in a word has caused problems elsewhere
too, see bug #64202 (and note that I don't agree with the final comment there;
I have found it unfruitful, as have others, to argue with Keith because he
elides any point he can't rebut and fills the vacated space with personal
abuse).

> To get good output, drop the \% as well:
> 
> SYNOPSIS
>      void
>      timerdday(struct-timespec *earliest, struct-timespec *latest,
>              struct-timespec *resolution);
> 
> From:
> 
> .Fn timerdday "struct\-timespec *earliest" \
> "struct\-timespec *latest" "struct\-timespec *resolution"

To get us back into context, the point of this bug is whether/how _mdoc_
should indent lines of a function synopsis that wrap, and whether that
indentation should depend on the width of the function name (and return type,
if set on the same line as the name).

My personal preference on an esthetic basis is to do what _groff man_(7) does
with `SY` arguments.  But that would also be, I suspect, the most work to
duplicate in _groff mdoc_(7).  Effort-wise, I suppose the easiest thing to do
is ignore indentation entirely, like _mandoc_ 1.14.6.


    _______________________________________________________

Reply to this item at:

  <https://savannah.gnu.org/bugs/?63958>

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/