Re: [Groff] Re: Bug#176575: mdoc: .Dt ignores volume name

[Werner LEMBERG]

From: Colin Watson <address@hidden>
Subject: [Groff] Re: Bug#176575: mdoc: .Dt ignores volume name
Date: Mon, 20 Jan 2003 13:28:26 +0000

> On Mon, Jan 13, 2003 at 09:08:35PM +0100, Robert Bihlmeyer wrote:
> > Package: groff-base
> > Version: 1.18.1-3
> > Severity: minor
> > 
> > Following advice from you, I've started using the mdoc
> > macros.  They're really nice.
> > 
> > A minor nit of mine is that I can't override the volume name
> > (displayed at the top center of my manpage).  The section is 1
> > which seems to hardcode the volume to "BSD General Commands
> > Manual".  First, my command is probably not general ... and it
> > sure isn't BSD.
> 
> I can only manage to override the volume name (apart from using one
> of the volume-as-* architecture names: alpha, amiga, etc.) when I
> pass "" as the section number.  Otherwise, both arbitrary volume
> names and the volume-ds-* names (USD, PS1, etc.) are ignored.
> 
> This feels like a bug to me: I would like to be able to specify both
> a section number and a customized volume name, rather than just
> using the default for the section.

Indeed, this is very inconvenient.  Here a patch which I've applied
to the CVS.  No you can say e.g.

  .Dt FOO \&1 "This is a test"

(note the `\&' to make the second parameter not a valid numeric
expression) without a warning.  I will also document this.


--- doc-common.old      Wed Oct 30 16:12:44 2002
+++ doc-common  Thu Feb 27 15:51:49 2003
@@ -321,11 +321,12 @@
 .          as doc-volume " \*[doc-volume-ds-\$2]
 .    \}\}\}
 .    el \{\
-.      ie "\$2"unass" .ds doc-volume DRAFT
-.      el \{ .ie "\$2"draft" .ds doc-volume DRAFT
-.      el \{ .ie "\$2"paper" .ds doc-volume UNTITLED
-.      el \
-.        tm mdoc warning: .Dt: unknown section `\$2' (#\n[.c])
+.      ie "\$2"unass" \
+.        ds doc-volume DRAFT
+.      el \{ .ie "\$2"draft" \
+.        ds doc-volume DRAFT
+.      el .if "\$2"paper" \
+.        ds doc-volume UNTITLED
 .      \}\}
 .      if \A\$3 \{\
 .        if d doc-volume-ds-\$3 \


> > I think the inability to override the default names is a bug in
> > itself.  Apart from that the default operating system should be
> > "Debian".

`Debian' itself isn't an operating system.  It's a distribution,
providing GNU/Linux.

> There is support for overriding details like this in mdoc.local, but
> I'm not sure it's right to do so in a distribution's package, since
> it will affect the display of existing mdoc pages imported from BSD.
> Can an mdoc expert comment?

I think you should provide correct default values in mdoc.local --
any man page which is specific to a certain operating system should
say that by using .Os properly.

> > Finally, the section names could be reevaluate: "Manual" is
> > somewhat redundant. "User Commands" fits (1) better than "General
> > Commands" IMHO.
> 
> These are probably historic, but I believe the BSD mdoc maintainers
> read the groff list, so I'm forwarding this comment along with your
> others.

I have no opinion here.  Ruslan?


    Werner