develooper Front page | perl.perl5.porters | Postings from March 2009

Re: [PATCH] Markup in the NAME section is not portable

Thread Previous | Thread Next
Russ Allbery
March 5, 2009 14:13
Re: [PATCH] Markup in the NAME section is not portable
Message ID:
Michael G Schwern <> writes:

> Therein lies the problem.  As a module author I write in POD, not man.
> I don't have to or want to know any of this.  I want some expert to
> figure out how it should be translated into a man page or HTML or XML or
> a Windows help file or spelled out in skywriting.
> And I'm sure there's a line of Windows authors who would like to have
> words about the idea that they're writing man pages.
> And then what happens when another format decides it has its own set of
> special cases it doesn't want to display?
> The restrictions, details and worries of an individual format, even one
> as important as man pages, should not bubble up to the POD author.
> Instead the pod2x translator should take care of it.  As the author of a
> glue module your job is to make yourself miserable fussing over details
> like this to allow the POD author to be ignorant, lazy and happy.
> At minimum, Pod::Man can simply strip the offending formatting out.

Well, this is the key to this: when you write this documentation for Perl,
are you writing man pages but using POD to write them instead of *roff, or
are you writing some other type of documentation which we're converting
into a man page?

Historically in the Perl community (and by this I mean from back in the
1990s when Tom Christiansen was maintaining pod2man), the answer is the
first one.  The documents were man pages which are written in POD rather
than in *roff.  This is reflected in numerous ways, such as the
requirement that documents contain a NAME section following man
conventions, the NAME / SYNOPSIS / DESCRIPTION convention generally
followed, the conventions for options and use of lists that follow the
UNIX man page style guide, the formatting conventions for references to
programs and options, and so forth.

It's important here to separate the stylistic and section conventions from
the output format.  What we're talking about here isn't a requirement of
*roff (nroff renders markup in the NAME section just fine); rather, it's a
requirement of the standardized documentation format.  The only practical
issue we've uncovered with this in particular turned up when it was
converted to *roff and processed with a UNIX man program, but it's part of
the standard for the documentation format in general and it's possible
that other programs that read POD were also relying on it.  We're
rendering those man pages in many different output formats, such as HTML
or XML or Windows Help, but we've been using the formatting and
conventions of the UNIX man page to drive all of the core documentation.

Now, I can understand reconsidering this on the grounds that Perl is no
longer as closely linked to UNIX as it was originally.  However, I think
we should be cautious about the implications of changing this general
rule.  If, for example, documentation no longer requires a NAME section (a
requirement driven directly by the UNIX man page format and not
particularly meaningful for a general HTML document), that's a fairly
significant change that I think goes beyond just the problems that
Pod::Man would then encounter with attempting to make a conventional man
page from it.  I'm fairly sure that other parsers and other analyzers of
POD have also made use of these conventions, at least in doing ad hoc
parsing of POD documentation.

On the other hand, I think it's entirely reasonable to not expect authors
of POD documentation to know the rules for UNIX man pages.

Maybe the best approach here would be to write a style guide specifically
for POD documentation, laying out the expected sections and formatting
requirements, that we could agree on as the recommended documentation
style for Perl?  Then, people could rely on that without needing to worry
too much about whether it matched some other external convention.
(Obviously, for various reasons, I think it would be worthwhile if that
style matched the UNIX man page style fairly closely, particularly since
that's already the style that we're largely following, but it wouldn't
need to match exactly and we could investigate places where the formatter
should be able to correct, such as C<> markup in the NAME section.)

Russ Allbery (             <>

Thread Previous | Thread Next Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About