Bug#377392: Bug#450432: ... and even more bugs like this?
On Sat, Nov 17, 2007 at 06:50:18PM -0800, Russ Allbery wrote:
> Colin Watson <cjwatson@debian.org> writes:
> >> W: dpkg-dev: manpage-has-errors-from-man usr/share/man/man1/dpkg-architecture.1.gz 104: warning: `C`' not defined
>
> > I'm not entirely sure what all this line noise is trying to achieve.
> > Looks to me like stuff like \f(CW\*(C`\-c\*(C' should just be \-c;
>
> It's intentional in general. I don't know why it's not defined, though.
> \f(CW sets a fixed-width font, and \*(C` and \*(C' add "" when fonts
> aren't supported but suppress the quotes when fonts are supported.
> pod2man has done this for eons.
In pod2man's case, it's almost fine. I think it would be helpful if it
.ds'ed C` and C' to the empty string in the troff branch, though.
However, dpkg-architecture.1 isn't a pod2man-generated page, and it
seems to have cribbed the use of these strings without also cribbing
their definitions. In this case, I don't think quotes would be desirable
anyway - the context is:
CC=i386\-gnu\-gcc dpkg\-architecture \f(CW\*(C`\-c\*(C'\fR debian/rules build
eval \`dpkg\-architecture \f(CW\*(C`\-u\*(C'\fR\`
One problem that seems to crop up a lot with inexperienced *roff users
is that they crib from other example pages without understanding which
facilities are effectively built into the language and which are
provided by bits at the top of the page. I've tried to provide examples
in /usr/share/doc/man-db/examples/ which should be good enough for many
people.
Personally I like to use the mdoc macros, which form a logical markup
language rather than a physical markup language, so you don't spend time
mucking about with font selections and can just say "this is a flag" or
"this is a program argument" or whatever instead. However, I think I
would echo Russ' recommendation to use POD if you don't know *roff well
and just want to write a manual page without the formatting getting in
your way.
Cheers,
--
Colin Watson [cjwatson@debian.org]
Reply to: