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

[G. Branden Robinson]

Update of bug #63958 (project groff):

                  Status:               Need Info => None                   

    _______________________________________________________

Follow-up Comment #2:

Thanks for following up, Ingo.

I'll interleave my original questions back into this.

[comment #1 comment #1:]
>> 1. How is mdoc(7) to know where to place the hanging indent?  man(7) does
it by measuring the width of the first argument to the `SY` macro, which is a
GNU extension.
> 1. mandoc(1) uses 4n, presumably for compatibility with groff.

I looked it up, and right now groff uses 8n for `Ft`. 
https://git.savannah.gnu.org/cgit/groff.git/tree/tmac/mdoc/doc-common#n102

However, that doesn't seem to influence the indentation of the return type
_or_ of the hanging indentation.  I'll have to look harder for the cause of
that 4n handing indent.

>> 2. mandoc mdoc(7) doesn't break after `Ft`; groff mdoc(7) does.

> 2. That's only because mandoc(1) does not support mixed-case section names
yet.  Apply s/Synopsis/SYNOPSIS/ and mandoc(1) works as expected.  Yes, this
will be fixed in mandoc(1), hopefully not in the too far future.

Sounds good.

>> 3. groff mdoc(7) appears to be computing the hanging indent based on the
argument to `Ft`.

> 3. I doubt that.  Apply s/void/unicorn/ and the indentation remains 4n.

Yup.  4n is hard-coded somewhere.

> 4. Do not use .Bl in the SYNOPSIS, in particular not for such an extremely
simple case.  The mdoc(7) code is OK as is.  I recommend using .Fo if there
are any long arguments or more than two arguments, but that's merely a weak
stylistic recommendation for readability of the source code.  See below for
how i would write this thing.
> 

> .Ft void
> .Fo timerdday
> .Fa "struct timespec *earliest"
> .Fa "struct timespec *latest"
> -Fa "struct timespec *resolution"
> .Fc


This does look much tidier for maintenance.
 
> Using \% in a SYNOPSIS seems bogus to me.

It is necessary even if automatic hyphenation is disabled, if one wants to
prevent breaks after "hard" (literal) hyphens.

If you never type a hyphen in your synopsis (and if the package/formatter
doesn't try to hyphenate words in the synopsis automatically), you'll never
need \%.

> The program ought to do the right thing by default, and i believe mandoc(1)
does.  If groff hyphenates type or argument names, it should be fixed.

Yes it should, and I have a fix prepared; bug #63957.  But the hard-hyphen/\%
caveat will remain because that's fundamentally an aspect of formatter
operation with no control knob in *roff--ever, as far as I know.  Well, okay,
in GNU troff you can maybe change the character attributes of "-".  With a
request.  That's not exactly portable.

> Having a hyphen in "struct timespec" seems even more bogus to me; is that
even valid C syntax?

This is an Alex-ism; I'm not sure why he wrote it that way.
 
> Then again, i don't recall ever seeing a function called timerdday(3)
before.  I neither found it in the OpenBSD nor in the FreeBSD tree.  I would
be quite surprised if it were, as you seem to claim, a BSD thingy.

No no no, I totally made up this function, hence the extremely bogus
pre-epochal document date.  It is however closely based on an example that
Alex Colomar did provide.

https://lists.gnu.org/archive/html/groff/2023-03/msg00085.html

Thanks for the feedback.  I think my take-aways from this are:

1. Double check subsection heading and base paragraph indentation amounts;
align them with man(7) if necessary.

2. Figure out where that 4n indentation is coming from.  *Nothing* seems to
have that measurement assigned to it.  (The closest match is "14n" for `Op`.)


    _______________________________________________________

Reply to this item at:

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

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