Re: mandoc and volume titles

Steve Kargl wrote in
 <YqJihG7hegKkNj6M@troutmask.apl.washington.edu>:
 |On Thu, Jun 09, 2022 at 06:55:36PM +0200, Steffen Nurpmeso wrote:
 |> Steve Kargl wrote in
 |>  <YqIiLQUI7Y/QH3Qg@troutmask.apl.washington.edu>:
 |>|On Thu, Jun 09, 2022 at 05:29:04PM +0200, Steffen Nurpmeso wrote:
 |>|> Steve Kargl wrote in
 |>|>  <YqIEl0SgJytjD+AW@troutmask.apl.washington.edu>:
 |>|>|On Thu, Jun 09, 2022 at 09:17:02AM +0200, Baptiste Daroussin wrote:
 |>|>|> On Wed, Jun 08, 2022 at 04:35:08PM -0700, Steve Kargl wrote:
 ...
 |> These are all strings from the doc-common mdoc(7) (g)roff file
 |> which are then picked up by mdoc(7) as required by the context.
 |> (g)roff can give you what you want like this:
 |> 
 |>   .ds volume-operating-system steve
 |>   .ds volume-ds-8 kargl
 |> 
 |> (before the [.Dd,].Dt,.Os preamble), and i get then
 |> 
 |>   S-POSTGRAY(8) steve kargl S-POSTGRAY(8)
 |> 
 |> Ingo Schwarze just currently has a run on mandoc in the OpenBSD
 |> source tree since a couple of days, maybe if a FreeBSD folk would
 |> point him to doc-common strings (or at least the volume-ds-*
 |> ones), you would be fine out with the next release of mandoc.
 |
 |The first 6 lives of my file are
 |
 |.ds volume-operating-system steve
 |.ds volume-ds-8 kargl

If you use ".Dt TDI 1", you must set volume-ds-1.

 |.Dd June 8, 2022
 |.Dt TDI 1
 |.Sh NAME
 |.Nm tdi
 |
 |% mandoc tdi.1 | head -1

This is mandoc Mr. Kargl.  mandoc parses man(7) and mdoc(7)
documents into a tree of what it knows, and then interprets it so
that it matches what roff would generate.  (On the terminal; after
way over a decade of work it "can" other formats much better than
roff.)

There was a time when Ingo Schwarze as mandoc maintainer posted
mails stating how many percent (to the tenths iirc) of all OpenBSD
manuals come out equal.  But it still is not at hundred percent.

  ...
 |I cannot find mention of .ds in mandoc(1) nor mdoc(7) man pages.

Because it is a scut.  Not a roff interpreter.
(Having said that: it is also a good thing, as it is very fast and
can some things good; but it is not a roff interpreter, which as
a Unix lover makes me sad.)

But i _think_ at least rudimentary .ds support comes with the next
release, i seem to recall to have read something about .ds.

 |Depending groff documentation, which might not be installed as it
 |is a port, seems to be a bit dubious.

Quite vice versa.  mdoc is thirty years old, and could be
implemented because roff that is even older is such a powerful
system.

 |% groff -T ascii -mdoc tdi.1 | head -1
 |TDI(1)                  FreeBSD General Commands Manual            \
 |     TDI(1)
 |
 |It appears to no work?

Now that is overly interesting!
Yes.  Long story short (i _hate_ the way groff is maintained).
Please use a doc- prefix for your pleasure:

  #?0|kent:$ cat steve.4
  .Dd June 8, 2022
  .ds doc-volume-operating-system Steve
  .ds doc-volume-ds-4 Kargl
  .Dt TDI 4
  .Sh NAME
  .Nm tdi
  Hi.
  #?0|kent:nail.git$ groff -mdoc -Tutf8 steve.4
  TDI(4)                            Steve Kargl                           TDI(4)

  NAME
       tdi Hi.

                                   June 8, 2022

--steffen
|
|Der Kragenbaer,                The moon bear,
|der holt sich munter           he cheerfully and one by one
|einen nach dem anderen runter  wa.ks himself off
|(By Robert Gernhardt)