Re: mandoc and volume titles

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:
> > All,
> > 
> > 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)
> > 
> > I have created a bug report and attached the diff to it
> > if anyone is interested.
> > 
> > https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=264560
> 
> Hello Steve,
> 
> Regarding mandoc, I would like to keep it with as little custom patches
> as possible, regarding your patch, it sounds like a useful feature, have
> you considered talking directly to upstream about it to see if they are
> willing to integrate it directly?
> 
> https://mandoc.bsd.lv/contact.html ?
> 
> They are friendly and usually reactive.
> 

I was pointed to upstream in the bug report.  While a -V option
would work for me with single files, I think adding a .Vl macro
would be better.  The top of a file would look like

.Vl Volume Title
.Dd June 8, 2022
.Dt TIER 1

This would allow a specific volume title on each file such as

% mandoc -T pdf manual.1 appendx.1 > manaul.pdf

MANUAL(1)   Project X Tech Specs   MANUAL(1)
...
APPENDEX(1)  Support Library     APPENDIX(1)

I'll try talking to upstream.
-- 
Steve