Re: mandoc and volume titles

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:
>  |>  ...
>  |>|>> mandoc and mdoc(7) are a convenient system for writing
>  |>|>> documentation, but it has a drawback.  The volume
>  |>|>> title is hardcoded to a FreeBSD manual page.  For my
>  |>|>> personal projects, I would like to change the volume
>  |>|>> title.  For example.
>  |>|>> 
>  |>|>> % mandoc tier.1 | head -1
>  |>|>> TIER(1)           FreeBSD General Commands Manual             TIER(1)
>  |>|>> 
>  |>|>> I have hacked up mandoc to accept a -V option, which allows e.g.,
>  |>|>> 
>  |>|>> % mandoc -V "Steve's Menagerie" tier.1 | head -1
>  |>|>> TIER(1)                  Steve's Menagerie                     TIER(1)
>  |> 
>  |> Note .Dt has optional parameters.
>  ...
>  |So, I changed my local manpage to 
>  |
>  |Dd June 8, 2022
>  |.Dt TDI \*(XX 1 "Steve's Menagerie"
>  |.Sh NAME
>  |
>  |On FreeBSD, it produces 
>  |
>  |TDI(1)    FreeBSD General Commands Manual (steve's menagerie)      \
>  |    TDI(1)
>  |
>  |That is not what I'm after.  First, I want to completely replace the
>  |"FreeBSD General ..." volume title.  Second, the optional third
>  |parameter is in lower case.
>  |
>  |If mdoc had a .Vl macro, I could do
>  |
>  |.Vl Steve's Menagerie
>  |.Dd June 8, 2022
>  |.Dt TDI \*(XX 1 "Steve's Menagerie"
>  |.Sh NAME
>  |
>  |TDI(1)    Steve's Menagerie          TDI(1)
>  |
>  |> ) but that it is!  If i were you i would simply assign something
>  |> to the string volume-ds-8, as early as possible in the document
>  |> (before the mdoc(7) preamble), as in:
>  ...
>  |>   S-POSTGRAY(8)                 BSD in_fear_of_fear S-POSTGRAY(8)
>  |
>  |Where does the BSD come from?  Seems a bit odd to randomly appear.
> 
> 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
.Dd June 8, 2022
.Dt TDI 1
.Sh NAME
.Nm tdi

% mandoc tdi.1 | head -1
TDI(1)                  FreeBSD General Commands Manual                 TDI(1)

I cannot find mention of .ds in mandoc(1) nor mdoc(7) man pages.
Depending groff documentation, which might not be installed as it
is a port, seems to be a bit dubious.  

% groff -T ascii -mdoc tdi.1 | head -1
TDI(1)                  FreeBSD General Commands Manual                 TDI(1)

It appears to no work?

-- 
Steve