printf(3) modifiers table badly formatted with mandoc

printf(3) modifiers table badly formatted with mandoc

[Thomas Klausner]

You can probably answer this one better than I. That's with mandoc-1.12.0.
 Thomas

----- Forwarded message from Nicolas Joly <njoly@pasteur.fr> -----

Date: Thu, 1 Mar 2012 13:41:26 +0100
From: Nicolas Joly <njoly@pasteur.fr>
To: Thomas Klausner <wiz@netbsd.org>
Subject: printf(3) modifiers table badly formatted with mandoc

Hi Thomas,

Looking into printf(3) man page, i found that the modifiers table is
badly formatted by mandoc, now the default. It exceed the 80 columns
limits, unlike the nroff output.

Looking into the mdoc source, i noticed that is uses a columnated list
where argument used for width specification include mdoc macros. While
nroff seems to interpret them to define the final widths, mandoc do
seems to use them as-is ... leading to the spacing differences.

.Bl -column ".Cm q Em (deprecated)" ".Vt signed char" ".Vt unsigned long long" ".Vt long long *"
.It Sy Modifier Ta Cm d , i Ta Cm o , u , x , X Ta Cm n
.It Cm hh Ta Vt "signed char" Ta Vt "unsigned char" Ta Vt "signed char *"
.It Cm h Ta Vt short Ta Vt "unsigned short" Ta Vt "short *"
.It Cm l No (ell) Ta Vt long Ta Vt "unsigned long" Ta Vt "long *"
.It Cm ll No (ell ell) Ta Vt "long long" Ta Vt "unsigned long long" Ta Vt "long long *"
.It Cm j Ta Vt intmax_t Ta Vt uintmax_t Ta Vt "intmax_t *"
.It Cm t Ta Vt ptrdiff_t Ta (see note) Ta Vt "ptrdiff_t *"
.It Cm z Ta (see note) Ta Vt size_t Ta (see note)
.It Cm q Em (deprecated) Ta Vt quad_t Ta Vt u_quad_t Ta Vt "quad_t *"
.El

I don't know if using macros is allowed there, and how to fix it
properly. Can you please have a look ?

Thanks.

-- 
Nicolas Joly

Projects and Developments in Bioinformatics
Institut Pasteur, Paris.

----- End forwarded message -----
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

Re: printf(3) modifiers table badly formatted with mandoc

[Ingo Schwarze]

Hi,

> Date: Thu, 1 Mar 2012 13:41:26 +0100
> From: Nicolas Joly <njoly@pasteur.fr>
> To: Thomas Klausner <wiz@netbsd.org>
> Subject: printf(3) modifiers table badly formatted with mandoc
> 
> Looking into printf(3) man page, i found that the modifiers table is
> badly formatted by mandoc, now the default. It exceed the 80 columns
> limits, unlike the nroff output.
> 
> Looking into the mdoc source, i noticed that is uses a columnated list
> where argument used for width specification include mdoc macros. While
> nroff seems to interpret them to define the final widths, mandoc do
> seems to use them as-is ... leading to the spacing differences.

Yes, that's a known issue:

  http://mdocml.bsd.lv/cgi-bin/cvsweb/TODO?cvsroot=mdocml&rev=HEAD

 - When the -width string contains macros, the macros must be rendered
   before measuring the width, for example
     .Bl -tag -width ".Dv message"
   in magic(5), located in src/usr.bin/file, is the same
   as -width 7n, not -width 11n.
   The same applies to .Bl -column column widths;
   reported again by Nicolas Joly Thu, 1 Mar 2012 13:41:26 +0100 via wiz@ 5 Mar

I just added the last two lines such that we are aware that more people
are suffering from the issue.

It is not trivial to fix and would probably require some reshuffling
of the mandoc framework.  In mandoc, the parser and the formatter
are well separated, to have an intermediate data structure retaining
all the semantic annotations.  Right now, the width is a number to
be calculated by the parser, but the width of text output generated
from macros cannot be determined before choosing a formatter and
actually running it.

> .Bl -column ".Cm q Em (deprecated)" ".Vt signed char" [...]
[...]
> I don't know if using macros is allowed there,

Well, people have done that in the past, and groff accepted it,
so from that perspective, it is a bug in mandoc.

Using macros in such places even has some merit because fonts etc.
may influence the width of typeset strings on non-fixed-width
output devices.

> and how to fix it properly.

For now, i'm sorry to say that removing the macros from the
width specifiers is the only workaround i'm aware of.
Fortunately, the number of affected pages does not seem
to be very large; or at least it wasn't in OpenBSD.

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv