Re: mandoc and volume titles

From: Steve Kargl <sgk_at_troutmask.apl.washington.edu>
Date: Fri, 10 Jun 2022 16:20:03 UTC
On Fri, Jun 10, 2022 at 02:31:26PM +0200, Steffen Nurpmeso wrote:
> Steve Kargl wrote in
>  <YqJ1VOcJYbXBg85T@troutmask.apl.washington.edu>:
>  |On Thu, Jun 09, 2022 at 11:49:06PM +0200, Steffen Nurpmeso wrote:
>  |> Steve Kargl wrote in
>  ...
>  |>|.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.
>  ...
>  |% 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.
>  |% mandoc steve.4
> 
> Well you can ignore totally what i say.  And you can mess up
> software in the FreeBSD base system and introduce incompatible
> islands whenever you want to.

I don't see how a discussion on an idea that may make FreeBSD
more useful for its user is "messing up software".  But, you
have made it clear that such discussion are unwelcomed here.  

>   ...
>  |Having to install groff and adding undocumented .ds magic isn't the
>  ...
> 
> This is not magic but decade old stuff, whether you like it or
> not.

It is magic to the extent that doc-volume-* is undocumented in
mandoc(1) and mdoc(7).  It is magic to doc-volume-* to work 
with mandoc(1) as well mandoc does not recognize doc-volume-*

>   #?0|kent:free-src.git$ git grep -i doc-volume-ds release/5.5.0~50784 |
>     wc -l
>   31
> 
> (I do not track anything before 5.5.0.)

I have no idea what the above is meant to demonstrate.  But, if
your're tracking 5.5.0, groff lived in src/contrib, so yes, 
you'll like find doc-volumen-ds in the treele:kargl[216] cat a.c

% foreach i (1 2 3 4 5 6 7 8 9)
foreach? find /usr/src -name \*.$i -type f | xargs grep doc-volume | wc -l
foreach? end
    0
    0
    0
    0
    0
    0
    0
    0
    0

> 
>  |solution for a FreeBSD base system functionality.  In fact, I think
>  |it would be better to have the mdoc(7) package grow a .Vl macro to
>  |allow the volume title to be easily overridden.
> 
> You can think whatever you want, and fill the remaining two letter
> combinations until they are all gone.

Thanks for granting me permission to try to improve FreeBSD.

-- 
Steve