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

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

Thread Previous | Thread Next
From:
Russ Allbery
Date:
March 5, 2009 15:50
Subject:
Re: [PATCH] Markup in the NAME section is not portable
Message ID:
87d4cv8r8d.fsf@windlord.stanford.edu
Michael G Schwern <schwern@pobox.com> writes:

> To answer your question at the top, I write Perl documentation.  I use
> perldoc instead of man.  Guarantees I get the right version of the page
> and I know its always going to work.
>
> I agree there's no doubt that Perl module style is heavily derived from
> man page standards.  It would be very nice to write those down.  pod2man
> is the only place I believe anyone has tried.

I can try to tackle a perlpodstyle documentation page, which I can either
ship with podlators or hand off to the Perl core team as makes the most
sense.  I'm somewhat handicapped by not having time to read perl5-porters,
although I do read pod-people.

> It's important to distinguish between semantic information and
> formatting information.  POD is mostly semantic (with exceptions like
> I<> and B<>) but it doesn't have much.  We derive interesting semantics
> from conventions mostly centered around =head.  Those are important to
> keep in line because they provide more semantic information than POD
> alone.  The details of the formatting, I still hold, is up to the
> formatters.  They provide little semantic information and can easily be
> rendered or stripped out entirely by the formatters.
>
> Formatters can not add semantics but they can convert formats.  This is
> why it's important to have a well defined NAME section but not necessary
> to restrict what formatting (ie. B<> and C<> and all) can go in it.  The
> "Name - Description" layout is important because it gives the formatter
> semantic information.  Once the formatter decides "this bit is the name,
> this bit is the description" it can render them however it likes doing
> whatever it needs with the formatting tags.
>
> So while discussing and nailing down the total layout of Perl
> documentation is good, it's unnecessary to deciding about formats in
> NAME.  It's still up to the formatter to decide.

Okay, I can live with that (and modify Pod::Man to strip B<> and I<>
markup in NAME as well).  As long as we don't go farther down that path
and allow verbatim paragraphs, subheadings, or move away from the Name -
Description syntax, you're certainly correct that formatters can cope.

-- 
Russ Allbery (rra@stanford.edu)             <http://www.eyrie.org/~eagle/>

Thread Previous | Thread Next


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About