Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]
Groups > comp.lang.perl.misc > #8524
| From | Ivan Shmakov <oneingray@gmail.com> |
|---|---|
| Newsgroups | comp.lang.perl.misc |
| Subject | Re: issues with POD |
| Date | 2013-06-27 12:48 +0000 |
| Organization | Aioe.org NNTP Server |
| Message-ID | <8761wz90sq.fsf@violet.siamics.net> (permalink) |
| References | <87y5a8es4l.fsf@violet.siamics.net> <8761x09kjx.fsf@violet.siamics.net> <075t9a-b882.ln1@anubis.morrow.me.uk> <87li5w7xa3.fsf_-_@violet.siamics.net> <0fkt9a-kmb2.ln1@anubis.morrow.me.uk> |
>>>>> Ben Morrow <ben@morrow.me.uk> writes:
>>>>> Quoth Ivan Shmakov <oneingray@gmail.com>:
>>>>> Ben Morrow <ben@morrow.me.uk> writes:
>>>>> Quoth Ivan Shmakov <oneingray@gmail.com>:
>>>> As it seems, ExtUtils::MakeMaker assumes (SPACE, HYPHEN-MINUS,
>>>> SPACE) for the delimiter while handling ABSTRACT_FROM, and I'm
>>>> considering it a bug (yet to be filed.)
>>> It's not a bug. It's part of the syntax of a properly-formatted
>>> perldoc.
>> Which I see no reason /not/ to extend.
> 'I see no reason not to extend the syntax of HTML to allow Unicode
> quotes as well as ASCII. They're *so* much prettier.' (cf. xthread.)
The HTML syntax /allows/ Unicode quotes. Inside the payload,
that is. (Which the text of the NAME section certainly is.)
The good thing about HTML is that it doesn't try to parse
anything outside of (roughly) the <tags /> and &entities;.
Ever.
[...]
>> Frankly, I consider the unconditional replacement of " - " to be a
>> hack by itself.
> Pod is, by design, a somewhat loosely-specified format, mostly or
> (originally) entirely in ASCII, which relies on the formatter to make
> things look pretty where that's necessary. The format has been
> tightened up a little recently (it's no longer considered appropriate
> for the formatter to turn random references like 'printf(3)' into
> L<>, for instance), but this sort of intuition about punctuation is
> entirely expected. Inconsistency is also, necessarily, expected.
... And so is unpredictability.
>>> so if you don't get endashes in the output it's because your
>>> formatter doesn't know how to produce them.
>> Apparently, the HTML formatter at http://search.cpan.org/ doesn't
>> know how to produce EN DASHes, either.
> Apparently not. Apparently whoever wrote the relevant bit of code
> didn't think it was terribly important.
But I do. So, assuming that my intent is to provide quality
documentation (both the contents and the form) for the users of
the software I develop, should I satisfy the NAME convention, at
the cost of having to host the /proper/ HTML renditions of the
documentation by myself? Or should I instead disregard the
convention -- used by the developer's tools I won't use myself
anyway, -- to ensure that certain well-known Web resource will
have the documentation rendered properly?
>> ... Indeed, my first thought was to use DocBook or XHTML
> Ewww, yuck. Formats designed by and for pedants.
... Remind me not to ask you about TEI, then...
>> for the documentation right from the start, so to completely avoid
>> all those 40 years of formatting mess. Somehow, however, I became
>> assured that persuading http://search.cpan.org/ to allow for XHTML
>> documentation would be next to impossible a task, which is why I've
>> ended up following the mainstream.
>> Not that I'm particularly happy with it.
> Heh. I can just picture the conversation... Not to mention that
> command-line perldoc would no longer function, making your modules
> unusable.
"Command-line perldoc"? What's it?
>>> 'groff -man -Tps' at least will get them right.
>> Please note that -Tps produces not a document, but a program to be
>> executed (by a PostScript interpreter, in this case), which has
>> implications to both security
> That is a relevant concern under some circumstances; this is not one
> of them.
It's a valid concern whenever the code comes from a generally
untrusted source. Such as from a Web site its author put it to.
(Which is how the documentation for free software packages is
often distributed.)
> (I have, somewhat reluctantly, moved to using PDF instead of
> PostScript almost exclusively. I like PostScript: it's comfortingly
> insane. (The same could be said about Perl.))
Still, I don't quite understand why one might want to use an
ad-hoc graphics language, when there're general-purpose ones,
with a number of graphics libraries to choose from? (And that
includes Perl, BTW.)
Pretty much the same applies to the ad-hoc formatter languages,
such as roff or TeX. Or to the usual hacks, like having the
"document conversion" chain run as follows:
document.foo -> (conversion) -> program -> (interpreter) -> document.bar
>> and software freedom.
> Don't be so ridiculous.
Well, looking at the license the software I use to produce
PostScript may attach to the pieces of the code which end up in
the resulting "document" isn't exactly the thing I'd like to
spend my time on.
The same applies to the license for the JavaScript code the Web
sites I visit employ. Which is one more reason to prefer Lynx.
>> Therefore, unless there's a very good reason to use PostScript, my
>> suggestion would be to always stick to PDF. (Or perhaps SVG, as
>> long as single-page vector graphics is concerned.)
> In this particular case I had a rather good reason: my version of
> groff doesn't have a -Tpdf device.
To me, it looks much more like a very good reason to update the
particular groff install.
[...]
>>>> (It appears to assume that --quotes= is a string of two /octets/,
>>>> not two /characters,/ though.)
>>> Since the roff emitted by pod2man is normally ASCII-only, what's
>>> the difference?
>> First of all, pod2man(1) supports --utf8.
> That's new(ish), and not particularly well-supported.
The more's the effort, the better's the support. And
identifying (and reporting) bugs is part of such an effort.
(Unless the agreement would be to just drop POD altogether, and
move on to the better tools. Which I still hope for, even
understanding all the improbability of such a decision.)
>> Then, even if ASCII-only roff code is requested, pod2man(1) should
>> try to convert the --quotes= characters to the appropriate roff
>> escapes, just as it's claimed it does for non-ASCII sources:
> The characters passed to --quotes aren't the characters as they will
> appear in the output, they are roff escapes. (I don't really
> understand roff, but the characters you pass are inserted directly
> into a .ds line.)
Which means that it may require a more thorough code change to
fix the issue. (Thanks for the pointer, BTW.)
> Remember, all this stuff comes from perl 5.000, before perl (or
> groff, I expect) had any sort of Unicode support.
How could this justify having the bug remain unfixed?
--
FSF associate member #7257
Back to comp.lang.perl.misc | Previous | Next — Previous in thread | Next in thread | Find similar
CPAN vs. POD outside of .pm (.pl) files? Ivan Shmakov <oneingray@gmail.com> - 2013-06-17 14:20 +0000
Re: CPAN vs. POD outside of .pm (.pl) files? Ben Morrow <ben@morrow.me.uk> - 2013-06-17 16:12 +0100
Re: CPAN vs. POD outside of .pm (.pl) files? Ivan Shmakov <oneingray@gmail.com> - 2013-06-17 15:39 +0000
Re: CPAN vs. POD outside of .pm (.pl) files? Ben Morrow <ben@morrow.me.uk> - 2013-06-17 21:03 +0100
Re: CPAN vs. POD outside of .pm (.pl) files? Ivan Shmakov <oneingray@gmail.com> - 2013-06-27 05:42 +0000
Re: CPAN vs. POD outside of .pm (.pl) files? Ben Morrow <ben@morrow.me.uk> - 2013-06-27 08:12 +0100
issues with POD Ivan Shmakov <oneingray@gmail.com> - 2013-06-27 08:50 +0000
Re: issues with POD Ben Morrow <ben@morrow.me.uk> - 2013-06-27 12:32 +0100
Re: issues with POD Ivan Shmakov <oneingray@gmail.com> - 2013-06-27 12:48 +0000
Re: issues with POD Ben Morrow <ben@morrow.me.uk> - 2013-06-27 14:53 +0100
$ pod2man --quotes= Ivan Shmakov <oneingray@gmail.com> - 2013-06-27 15:20 +0000
Re: issues with POD Ivan Shmakov <oneingray@gmail.com> - 2013-06-27 15:25 +0000
Re: issues with POD Ben Morrow <ben@morrow.me.uk> - 2013-06-27 22:21 +0100
[OT] PostScript Ivan Shmakov <oneingray@gmail.com> - 2013-06-28 11:58 +0000
Re: issues with POD Ivan Shmakov <oneingray@gmail.com> - 2013-06-28 12:04 +0000
Re: issues with POD Shmuel (Seymour J.) Metz <spamtrap@library.lspace.org.invalid> - 2013-06-30 08:37 -0400
Re: issues with POD Ivan Shmakov <oneingray@gmail.com> - 2013-06-30 17:57 +0000
Re: issues with POD Shmuel (Seymour J.) Metz <spamtrap@library.lspace.org.invalid> - 2013-07-01 17:38 -0400
Re: issues with POD Rainer Weikusat <rweikusat@mssgmbh.com> - 2013-06-30 19:44 +0100
Re: issues with POD Rainer Weikusat <rweikusat@mssgmbh.com> - 2013-06-28 14:29 +0100
[OT] non-issues with non-solutions Ivan Shmakov <oneingray@gmail.com> - 2013-06-28 13:45 +0000
Re: [OT] non-issues with non-solutions Rainer Weikusat <rweikusat@mssgmbh.com> - 2013-06-28 15:13 +0100
Re: [OT] non-issues with non-solutions Rainer Weikusat <rweikusat@mssgmbh.com> - 2013-06-29 19:37 +0100
a-Moose-ing CGI Ivan Shmakov <oneingray@gmail.com> - 2013-06-30 07:56 +0000
Re: a-Moose-ing CGI Rainer Weikusat <rweikusat@mssgmbh.com> - 2013-06-30 14:05 +0100
Re: a-Moose-ing CGI Ben Morrow <ben@morrow.me.uk> - 2013-07-01 13:26 +0100
Re: a-Moose-ing CGI Rainer Weikusat <rweikusat@mssgmbh.com> - 2013-07-01 18:12 +0100
[OT] CGI: "Fast" vs. "classic" Ivan Shmakov <oneingray@gmail.com> - 2013-07-01 17:27 +0000
Re: [OT] CGI: "Fast" vs. "classic" Rainer Weikusat <rweikusat@mssgmbh.com> - 2013-07-01 18:45 +0100
Re: a-Moose-ing CGI Ben Morrow <ben@morrow.me.uk> - 2013-07-01 18:52 +0100
Re: issues with POD Ben Morrow <ben@morrow.me.uk> - 2013-07-01 13:29 +0100
Re: issues with POD "Peter J. Holzer" <hjp-usenet3@hjp.at> - 2013-07-01 17:19 +0200
Re: issues with POD Ben Morrow <ben@morrow.me.uk> - 2013-07-01 18:38 +0100
Re: issues with POD Mart van de Wege <mvdwege@mail.com> - 2013-07-02 10:13 +0200
Re: issues with POD "Dave Saville" <dave@invalid.invalid> - 2013-07-02 08:54 +0000
Re: issues with POD Ben Morrow <ben@morrow.me.uk> - 2013-07-02 11:42 +0100
perldoc and perl-doc Ivan Shmakov <oneingray@gmail.com> - 2013-07-02 11:17 +0000
Re: perldoc and perl-doc Rainer Weikusat <rweikusat@mssgmbh.com> - 2013-07-02 12:37 +0100
Re: perldoc and perl-doc Ivan Shmakov <oneingray@gmail.com> - 2013-07-02 14:34 +0000
Re: perldoc and perl-doc Jürgen Exner <jurgenex@hotmail.com> - 2013-07-02 08:18 -0700
Re: perldoc and perl-doc Ivan Shmakov <oneingray@gmail.com> - 2013-07-02 15:23 +0000
Re: perldoc and perl-doc Eric Pozharski <whynot@pozharski.name> - 2013-07-03 09:41 +0300
Re: perldoc and perl-doc "Peter J. Holzer" <hjp-usenet3@hjp.at> - 2013-07-02 17:38 +0200
Re: perldoc and perl-doc Ben Morrow <ben@morrow.me.uk> - 2013-07-02 16:37 +0100
Re: perldoc and perl-doc Rainer Weikusat <rweikusat@mssgmbh.com> - 2013-07-02 17:20 +0100
Re: perldoc and perl-doc Charlton Wilbur <cwilbur@chromatico.net> - 2013-07-02 12:08 -0400
[OT] MIME adoption in Usenet Ivan Shmakov <oneingray@gmail.com> - 2013-07-03 12:59 +0000
Re: [OT] MIME adoption in Usenet Ben Morrow <ben@morrow.me.uk> - 2013-07-03 17:49 +0100
Re: issues with POD tmcd@panix.com (Tim McDaniel) - 2013-06-27 18:43 +0000
csiph-web