bugGNU roff - Bugs: bug #63958, [mdoc] decide how to set up...

 
 

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

Submitter:  G. Branden Robinson <gbranden>
Submitted:  Fri 24 Mar 2023 07:52:56 AM UTC
   
 
Category:  Macro mdoc Severity:  1 - Wish
Item Group:  Rendering/Cosmetics Status:  None
Privacy:  Public Assigned to:  gbranden
Open/Closed:  Open Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Tue 08 Aug 2023 09:39:19 PM UTC, comment #18: 

To re-iterate, right now, i don't see a need to change anything with respect to the topic of this ticket.

Unless i'm unaware of some arcane corner cases, i modeled the hanging indents in mandoc(1) to match how groff(1) does them.

Ragarding the variable-width indents in sections 1 & 8, i don't recall ever being unhappy with them.  That may be because the names of command line commands tend to be short.  Admittedly, in OpenBSD, Marc Espie blessed us with a check-lib-depends(1) manual page, but even that still looks passable, and it doesn't get much longer than that.  The dbus-update-activation-environment(1) manual arguably does look ugly, but such insanity is rare to the point that i would call it irrelevant for all practical purposes.

On the other hand, long function names in section 3 are not unusual, so with large variable indents, many pages in section 3 would look really bad.  On top of that, many section 3 pages document more than one function, and having a differently wide hanging indent for every function would also be ugly.  So the currently solution of always using 4n is just fine.


Ingo Schwarze <schwarze>
Group Member
Thu 03 Aug 2023 11:05:18 PM UTC, comment #17: 

Well, maybe one thing. SYNOPSIS is not justified in nroff/UCB mdoc: (this is with the latest commit to change the continuation indent already applied)



SYNOPSIS
     timerdday [-+abCefhiklmnprUuvXx] [-+o option] [-T [!]tty|-] [file [arg1
               ...]]
     timerdday [-+abCefhiklmnprUuvXx] [-+o option] [-T [!]tty|-] -c cmd [arg0
               ...]
     builtin-name foobar foobar foobar foobar foobar foobar foobar foobar
               [argument ...]

SYNOPSIS
     void
     timerdday(struct-timespec *earliest, struct-timespec *latest,
         struct-timespec *resolution);

     void
     tm(struct-timespec *earliest, struct-timespec *latest,
         struct-timespec *resolution);


… but it is in gnroff, looking bad:



SYNOPSIS
       timerdday    [-+abCefhiklmnprUuvXx]    [-+o   option]   [-T   [!]tty|-]
                 [file [arg1 ...]]
       timerdday [-+abCefhiklmnprUuvXx] [-+o  option]  [-T  [!]tty|-]  -c  cmd
                 [arg0 ...]
       builtin‐name  foobar  foobar  foobar foobar foobar foobar foobar foobar
                 [argument ...]

SYNOPSIS
       void
       timerdday(struct-timespec    *earliest,    struct-timespec     *latest,
           struct-timespec *resolution);

       void
       tm(struct-timespec       *earliest,       struct-timespec      *latest,
           struct-timespec *resolution);


I’m normally very much a fan of justified paragraphs, just maybe not for the SYNOPSIS…

Thorsten Glaser <mirabilos>
Thu 03 Aug 2023 10:53:27 PM UTC, comment #16: 

Oh wait, continuation indent is different depending on whether it’s a section 1/8 or section 2/3!

For section 1/8 (.Nm) we already behave identically (save for the base indent), so the Nm-based thing is already done õÕ

For section 2/3 (.Ft) however, we have that constant 8-column indent, whereas groff has… tests a four-space one. OK, let’s keep that.

Sorry, I originally had only tested one each, and not the same too. So, nothing to do for groff there.

Thorsten Glaser <mirabilos>
Thu 03 Aug 2023 10:47:08 PM UTC, comment #15: 


> Another approach would be to have every argumentful call to `Nm` update an
> internal register that stores the continuation indentation amount.


Is that not too late at that point? Don’t we need to set the
indent before the .Nm gets rendered?

I guess we could maybe put this as hack into the definition of Nm,
to work differently if it’s run in the SYNOPSIS.

But, honestly, a consistent four-space continuation indent to me sounds good enough.

btw we have http://www.mirbsd.org/manUSD/21.troff and http://www.mirbsd.org/manUSD/22.trofftut which are where I look when I need to know something ☻ (analogous to the section 7 pages in groff). Feel free to peruse.

Thorsten Glaser <mirabilos>
Thu 03 Aug 2023 10:40:07 PM UTC, comment #14: 


comment #13:

> (you can press ^Xe in a <textarea> in lynx,
>  and it will spawn your $EDITOR on it; it’s
>  okay for shorter things though)


Ah, that's right.  I remember discovering that.

Something else must have driven me off.

Cookie problems, maybe.
 

> The current continuation indent in gnroff in Debian sid
> seems to be… the width of Nm plus one space. Ingenious.
> (We’re talking about Sh SYNOPSIS here, right?)


I am if you are. :D
 

> This is wrong with multi-call binaries (those that inspect
> argv[0]), as they’ll use “.Nm othername” in SYNOPSIS. These
> aren’t uncommon, therefore I’d rather have a fixed four-space
> (in nroff) continuation indent. I think I’ll change this in
> my mdoc package, too, if I can find it…


Another approach would be to have every argumentful call to `Nm` update an internal register that stores the continuation indentation amount.

That would be analogous to what groff man(7)'s `SY` will do, if you use it as its man page suggests.

G. Branden Robinson <gbranden>
Group administrator
Thu 03 Aug 2023 10:22:45 PM UTC, comment #13: 



(you can press ^Xe in a <textarea> in lynx,
 and it will spawn your $EDITOR on it; it’s
 okay for shorter things though)

The current continuation indent in gnroff in Debian sid
seems to be… the width of Nm plus one space. Ingenious.
(We’re talking about Sh SYNOPSIS here, right?)

This is wrong with multi-call binaries (those that inspect
argv[0]), as they’ll use “.Nm othername” in SYNOPSIS. These
aren’t uncommon, therefore I’d rather have a fixed four-space
(in nroff) continuation indent. I think I’ll change this in
my mdoc package, too, if I can find it…

Yes, I know about baseline in typography, sorry for the
confusion; I meant the indentation of the main body texts.

Thorsten Glaser <mirabilos>
Thu 03 Aug 2023 10:03:39 PM UTC, comment #12: 

comment #11:

> Sorry, didn’t know about the formatting, it’s not all that clear in lynx, and the preview looked okay… in lynx, at least.


I think about 18 months ago I tried moving to lynx for my GNU Savannah interactions.  It was just too damn painful to use the multi-line text edit controls.
 

> I very much don’t like the mdocml output that doesn’t indent continuation lines. (On the other hand, UCB mdoc indents “too much”, per style(9) continuation indent is 4 spaces, not a tab like main indent.)


How do you find groff mdoc's continuation indentation amount?

> But at the same time, the baseline in groff is too far to the right.


"Baseline" is a dangerous word here.  In typography, and particularly in groff documentation, it's an italicized concept.

roff(7):


    While the formatter (and, later, output driver) is processing a
    page, it keeps track of its drawing position, which is the location
    at which the next glyph will be written, from which the next motion
    will be measured, or where a geometric object will commence
    rendering.  Notionally, glyphs are drawn from the text baseline
    upward and to the right.  (groff does not yet support right‐to‐left
    scripts.)  The text baseline is a (usually invisible) line upon
    which the glyphs of a typeface are aligned.  A glyph therefore
    “starts” at its bottom‐left corner.


But I understand you to mean the base/default paragraph indentation amount, and yup, we're back over to bug #64018 again.  ;-)

G. Branden Robinson <gbranden>
Group administrator
Thu 03 Aug 2023 09:31:04 PM UTC, comment #11: 

Sorry, didn’t know about the formatting, it’s not all that clear in lynx, and the preview looked okay… in lynx, at least.

I very much don’t like the mdocml output that doesn’t indent continuation lines. (On the other hand, UCB mdoc indents “too much”, per style(9) continuation indent is 4 spaces, not a tab like main indent.)

But at the same time, the baseline in groff is too far to the right.

Thorsten Glaser <mirabilos>
Thu 03 Aug 2023 09:20:06 PM UTC, comment #10: 

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:

> 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.

G. Branden Robinson <gbranden>
Group administrator
Thu 03 Aug 2023 08:37:11 PM UTC, 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).

The use of \% there is odd, I’d rather use \- there (which is needed to avoid getting ‐ anyway), but that leaves us with…

SYNOPSIS
     void
     timerdday(struct-timespec *earliest, struct-timespec *latest, -
             struct-timespec *resolution);

… which is also not right. 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"

Thorsten Glaser <mirabilos>
Sun 09 Apr 2023 08:57:22 PM UTC, comment #8: 

re comment #5:

re bug #63046: We both know that i dislike excessive, gratuitious configurability like that - it add complexity without any benefit, no need to discuss that over and over again.  I can live with it as long as the defaults are sane, such that i can hardcode the defaults into mandoc(1).

I call "5n is better" an objective assessment because it does not rely on personal taste but purely relies on factual arguments:

1. Both macro sets agree that subsection indentation is 3n, so that should not be changed.

2. Obviously, paragraph indentation must be greater than subsection indentation.  4n would not be a good choice because that's so close to 3n that subsection headers would not stand out from the text, because headers and text would be easy to confuse.

3. Looking at any mdoc(7) page containing subsections shows that 5n is sufficient to make the two instantly distinguishable.  Consequently, anything more than 5n is a waste.

I agree that subjective judgement would be required to decide whether any particular amount of waste would be acceptable to trade for some potential benefit.  But no one made any claim that 7n provides any benefit, the only fact mentioned is that's what groff_man(7) - and for compatibility, mandoc(1) man(7) - currently does.

Your detailed questions all seem irrelevant.  The fact that one implies a waste and the other does not makes the other better.

I would very much welcome a change from 7n to 5n and would make sure mandoc(1) immediately follows.

Ingo Schwarze <schwarze>
Group Member
Sun 09 Apr 2023 08:26:36 PM UTC, comment #7: 

That's weird--I thought put this into Need Info state.  Maybe there really is a Savannah bug here.

Anyway, I spun off the base paragraph indentation issue into bug #64018.

This issue--the Synopsis hanging indent matter--remains undecided with no clear path forward.

G. Branden Robinson <gbranden>
Group administrator
Sun 09 Apr 2023 08:25:35 PM UTC, comment #6: 

re comment #4:

Yes, i believe it must have been a widget-clicking goof on my part, and i didn't even notice it when the "status" changed.  Sorry for that.

I don't like interactive web interfaces except those that are strictly read-only, and it seems they don't like me all that much either.  :)

Ingo Schwarze <schwarze>
Group Member
Sun 09 Apr 2023 08:17:07 PM UTC, comment #5: 


comment #3:

> Besides, i don't think this has anything to with subsection heading indentation (which is 3n in both mdoc(7) and man(7)) nor with base paragraph indentation


I think you're correct on this point.

> (which is traditionally 7n in man(7) and 5n in mdoc(7)).


That appears to be true, when I "man groff_mdoc(7)" on my Debian-based system with Debian's groff 1.22.4 installed, and I don't think they altered this default.

> Please do not change the mdoc(7) indentation from 5n to 7n.


Er, I have to disclose that I already did, back on 29 October.

https://git.savannah.gnu.org/cgit/groff.git/commit/?id=2134257877b8da28b6d225d99a1c6d81592d9043

It seems horribly wrong to me for man pages to format in different ways gratuitously like this depending on the macro package used to render them.

This is one of the reasons I went to the trouble of bug #63046.

However, before you anticipate another conflict with me, I'm not convinced 7n/7.2n is something that should remain set in stone.

I see that McIlroy's 1979 man(7) implementation used a base paragraph indentation amount of .5i, which maps to 5n on typewriter devices since a default pitch of 10 (10 characters per inch) is assumed for them.

> I claim the 5n indentation is objectively better.  7n wastes too much screen real estate.


That is emphatically a subjective, not an objective, assessment.  Confusing these two is not a good way to build a convincing argument with me.

How does one measure the waste of screen real estate?  By counting empty character cells in a terminal window?  On how large a terminal window?  With or without adjustment?  With or without hyphenation?  If adjustment is enabled, do only empty character cells outside the paragraph margins count as wasted?  Most importantly, what percentage of empty character cells constitutes the threshold of waste, and how is that percentage "objectively" arrived at?  If a percentage is not used as the metric of screen real estate wastage, what is, where is it documented, and how is anyone else to have known of this "objective" metric?

>  The only reason i didn't reduce the 7n to 5n in mandoc(1) is groff compatibility.  But mandoc(1) does provide an option "-O mdoc" which, among other minor tweaks, implies "-O indent=5".


I see that I need to look up when and why groff changed to 7n/7.2n for man(7).  Who knows?  Maybe it was a SunOS change that groff copied back in 1989 without making a lot of noise about it, like the the `SB` macro and registers C, D, P, and X.

So I'll kick this back to status "Need Info" again as a homework assignment for myself.

I may end up agreeing with you that 5n/0.5i is the right base paragraph indentation for groff man(7) and groff mdoc(7) in groff 1.24, but claiming that 7n/7.2n "objectively wastes too much screen real estate" is not going to get us to a meeting of the minds.

G. Branden Robinson <gbranden>
Group administrator
Sun 09 Apr 2023 07:53:26 PM UTC, comment #4: 

If this ticket is a duplicate of another, the Savannah bug number it duplicates needs to be mentioned in a comment.

Otherwise I have to assume it was a widget-clicking goof...or some stochastic madness in PHP, that incredibly rigorous and well-behaved implementation language for presenting web content.

Setting status back to "none" (for now).

G. Branden Robinson <gbranden>
Group administrator
Sat 08 Apr 2023 07:47:42 PM UTC, comment #3: 

Your comment #2 seems fair enough in general, but note that i'm not guaranteed to be the happiest rabbit in the world if that ends up giving me a 31n indentation in X509_STORE_CTX_get_ex_new_index(3),
see https://man.openbsd.org/X509_STORE_CTX_get_ex_new_index.3 .

Oui, j'admet franchement qu'ils sont fous, ces Romains!


Besides, i don't think this has anything to with subsection heading indentation (which is 3n in both mdoc(7) and man(7)) nor with base paragraph indentation (which is traditionally 7n in man(7) and 5n in mdoc(7)).  Please do not change the mdoc(7) indentation from 5n to 7n.  I claim the 5n indentation is objectively better.  7n wastes too much screen real estate.  The only reason i didn't reduce the 7n to 5n in mandoc(1) is groff compatibility.  But mandoc(1) does provide an option "-O mdoc" which, among other minor tweaks, implies "-O indent=5".

Ingo Schwarze <schwarze>
Group Member
Sat 08 Apr 2023 06:41:24 PM UTC, comment #2: 

Thanks for following up, Ingo.

I'll interleave my original questions back into this.

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`.)

G. Branden Robinson <gbranden>
Group administrator
Sat 08 Apr 2023 06:13:09 PM UTC, comment #1: 

1. mandoc(1) uses 4n, presumably for compatibility with groff.
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.
3. I doubt that.  Apply s/void/unicorn/ and the indentation remains 4n.
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


Using \% in a SYNOPSIS seems bogus to me.  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.

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

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.

Ingo Schwarze <schwarze>
Group Member
Fri 24 Mar 2023 07:52:56 AM UTC, original submission:  

Input:


.Dd June 6, 1944
.Dt timerdday 3bsd
.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 .


mandoc 1.14.6 output (on Debian bullseye):


$ mandoc ../ATTIC/timerdday.mdoc | ul
timerdday(3bsd)                      3bsd                      timerdday(3bsd)

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.

Debian                           June 6, 1944                           Debian


groff Git HEAD (in my working copy with a pending fix for bug #63957):


$ ./test-groff -mandoc -Tascii ../ATTIC/timerdday.mdoc
timerdday(3bsd)                      LOCAL                     timerdday(3bsd)

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.

GNU                              June 6, 1944                  timerdday(3bsd)


Several questions occur to me:

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.

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

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

4. What's best practice?  Use a display with `-width`?

I'd like to discuss these points with an mdoc(7) maven at some point.  Ingo's the most likely candidate.

G. Branden Robinson <gbranden>
Group administrator

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by mirabilos (Posted a comment)
  • -email is unavailable- added by schwarze (Posted a comment)
  • -email is unavailable- added by gbranden (Submitted the item)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only logged-in users can vote.

     

    Follow 3 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2023-04-09 gbranden StatusDuplicate None
    2023-04-08 schwarze StatusNone Duplicate
    2023-04-08 gbranden StatusNeed Info None

    Back to the top

    Powered by Savane 3.13-758e.
    Corresponding source code