Re: mandoc and volume titles

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.

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