Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.perl.misc > #8423 > unrolled thread

CPAN vs. POD outside of .pm (.pl) files?

Back to article view | Back to comp.lang.perl.misc

Contents

  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

Page 1 of 3  [1] 2 3  Next page →

#8423 — CPAN vs. POD outside of .pm (.pl) files?

	I see that CPAN automagically extracts the POD documentation out
	of the .pm and .pl files and presents it as HTML.

	However, now I decide to split the documentation off the .pm's.
	How do I request CPAN to extract my documentation out of
	stand-alone POD files instead? (and associate it with the
	respective .pm's?)

	TIA.

-- 
FSF associate member #7257	np. Strange Highways -- Dio

[toc] | [next] | [standalone]

#8427

Quoth Ivan Shmakov <oneingray@gmail.com>:
> 	I see that CPAN automagically extracts the POD documentation out
> 	of the .pm and .pl files and presents it as HTML.

What do you mean by 'CPAN'? The CPAN shell doesn't normally do this. Do
you mean search.cpan.org?

> 	However, now I decide to split the documentation off the .pm's.
> 	How do I request CPAN to extract my documentation out of
> 	stand-alone POD files instead? (and associate it with the
> 	respective .pm's?)

search.cpan.org already displays a list of all the .pod files in a
distribution under the 'Documentation' section. If a .pm file has no
Pod, and there is a .pod file next to it, it moves the .pod link up into
the 'Modules' section. See for example Net::SSLeay. 

It's probably important to get the NAME section of the Pod right. I
don't exactly know how the search.cpan.org/perldoc?foo links it uses for
L<> work, but I suspect they're indexed based on the NAME section.

Ben

[toc] | [prev] | [next] | [standalone]

#8429

>>>>> Ben Morrow <ben@morrow.me.uk> writes:
>>>>> Quoth Ivan Shmakov <oneingray@gmail.com>:

 >> I see that CPAN automagically extracts the POD documentation out of
 >> the .pm and .pl files and presents it as HTML.

 > What do you mean by 'CPAN'?  The CPAN shell doesn't normally do this.
 > Do you mean search.cpan.org?

	Yes, I've meant http://search.cpan.org/ specifically, even
	though I've inaccurately referenced the whole cpan.org
	infrastructure.

	I didn't mean cpan(1).

 >> However, now I decide to split the documentation off the .pm's.  How
 >> do I request CPAN to extract my documentation out of stand-alone POD
 >> files instead? (and associate it with the respective .pm's?)

 > search.cpan.org already displays a list of all the .pod files in a
 > distribution under the 'Documentation' section.  If a .pm file has no
 > Pod, and there is a .pod file next to it, it moves the .pod link up
 > into the 'Modules' section.

	(Which makes me wonder where is it documented?)

 > See for example Net::SSLeay.

 > It's probably important to get the NAME section of the Pod right.  I
 > don't exactly know how the search.cpan.org/perldoc?foo links it uses
 > for L<> work, but I suspect they're indexed based on the NAME
 > section.

	ACK, thanks!  Hopefully, such indexing won't insist on the use
	of a HYPHEN-MINUS (U+002D) there, instead of the arguably more
	appropriate EN DASH (U+2013).

	(FWIW, http://search.cpan.org/perldoc?Net::SSLeay appears to
	work.  Yet it uses the conventional HYPHEN-MINUS.)

-- 
FSF associate member #7257

[toc] | [prev] | [next] | [standalone]

#8447

Quoth Ivan Shmakov <oneingray@gmail.com>:
> >>>>> Ben Morrow <ben@morrow.me.uk> writes:
> >>>>> Quoth Ivan Shmakov <oneingray@gmail.com>:
> 
>  >> I see that CPAN automagically extracts the POD documentation out of
>  >> the .pm and .pl files and presents it as HTML.
> 
>  > What do you mean by 'CPAN'?  The CPAN shell doesn't normally do this.
>  > Do you mean search.cpan.org?
> 
> 	Yes, I've meant http://search.cpan.org/ specifically, even
> 	though I've inaccurately referenced the whole cpan.org
> 	infrastructure.
> 
> 	I didn't mean cpan(1).

OK. I asked because I think it's possible to configure at least cpanp to
install HTML documentation, and IIRC ActiveState have or used to patch
their CPAN.pm to do the same.

>  >> However, now I decide to split the documentation off the .pm's.  How
>  >> do I request CPAN to extract my documentation out of stand-alone POD
>  >> files instead? (and associate it with the respective .pm's?)
> 
>  > search.cpan.org already displays a list of all the .pod files in a
>  > distribution under the 'Documentation' section.  If a .pm file has no
>  > Pod, and there is a .pod file next to it, it moves the .pod link up
>  > into the 'Modules' section.
> 
> 	(Which makes me wonder where is it documented?)

I don't think it is. search.cpan.org is not part of the CPAN
infrastructure per se, it was just a useful website written by Graham
Barr which was given a domain under cpan.org. I believe the intention is
that it should index things in the same way as CPAN.pm and perldoc.

>  > See for example Net::SSLeay.
> 
>  > It's probably important to get the NAME section of the Pod right.  I
>  > don't exactly know how the search.cpan.org/perldoc?foo links it uses
>  > for L<> work, but I suspect they're indexed based on the NAME
>  > section.
> 
> 	ACK, thanks!  Hopefully, such indexing won't insist on the use
> 	of a HYPHEN-MINUS (U+002D) there, instead of the arguably more
> 	appropriate EN DASH (U+2013).

I wouldn't muck about with the formatting of the NAME section. pod2man
in particular is quite picky about it, and there are other tools which
rely on the format being right.

Ben

[toc] | [prev] | [next] | [standalone]

#8514

>>>>> Ben Morrow <ben@morrow.me.uk> writes:
>>>>> Quoth Ivan Shmakov <oneingray@gmail.com>:
>>>>> Ben Morrow <ben@morrow.me.uk> writes:

[...]

 >>> What do you mean by 'CPAN'?  The CPAN shell doesn't normally do
 >>> this.  Do you mean search.cpan.org?

 >> Yes, I've meant http://search.cpan.org/ specifically, even though
 >> I've inaccurately referenced the whole cpan.org infrastructure.

 >> I didn't mean cpan(1).

 > OK.  I asked because I think it's possible to configure at least
 > cpanp to install HTML documentation, and IIRC ActiveState have or
 > used to patch their CPAN.pm to do the same.

	That's interesting.  Thanks.

[...]

 >>> search.cpan.org already displays a list of all the .pod files in a
 >>> distribution under the 'Documentation' section.  If a .pm file has
 >>> no Pod, and there is a .pod file next to it, it moves the .pod link
 >>> up into the 'Modules' section.

 >> (Which makes me wonder where is it documented?)

 > I don't think it is.  search.cpan.org is not part of the CPAN
 > infrastructure per se, it was just a useful website written by Graham
 > Barr which was given a domain under cpan.org.

	Which seems to make it quite a "part," at least for a casual
	user like me.

 > I believe the intention is that it should index things in the same
 > way as CPAN.pm and perldoc.

	ACK, thanks.

 >>> It's probably important to get the NAME section of the Pod right.
 >>> I don't exactly know how the search.cpan.org/perldoc?foo links it
 >>> uses for L<> work, but I suspect they're indexed based on the NAME
 >>> section.

 >> ACK, thanks!  Hopefully, such indexing won't insist on the use of a
 >> HYPHEN-MINUS (U+002D) there, instead of the arguably more
 >> appropriate EN DASH (U+2013).

 > I wouldn't muck about with the formatting of the NAME section.

	FWIW, http://search.cpan.org/ seems to handle it just fine.
	Consider, e. g.:

http://search.cpan.org/perldoc?Tree::Range::base
http://search.cpan.org/perldoc?Tree::Range::RB

	Preasumably, it just indexes the PODs by the filename.

 > pod2man in particular is quite picky about it, and there are other
 > tools which rely on the format being right.

	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.)

	I've not seen any problem with pod2man(1) vs. NAME as of yet.
	What should I take note of?

	(It appears to assume that --quotes= is a string of two
	/octets/, not two /characters,/ though.)

-- 
FSF associate member #7257

[toc] | [prev] | [next] | [standalone]

#8516

Quoth Ivan Shmakov <oneingray@gmail.com>:
> >>>>> Ben Morrow <ben@morrow.me.uk> writes:
> >>>>> Quoth Ivan Shmakov <oneingray@gmail.com>:
> 
>  >> ACK, thanks!  Hopefully, such indexing won't insist on the use of a
>  >> HYPHEN-MINUS (U+002D) there, instead of the arguably more
>  >> appropriate EN DASH (U+2013).
> 
>  > I wouldn't muck about with the formatting of the NAME section.
> 
> 	FWIW, http://search.cpan.org/ seems to handle it just fine.
> 	Consider, e. g.:
> 
> http://search.cpan.org/perldoc?Tree::Range::base
> http://search.cpan.org/perldoc?Tree::Range::RB
> 
> 	Preasumably, it just indexes the PODs by the filename.

Presumably.

>  > pod2man in particular is quite picky about it, and there are other
>  > tools which rely on the format being right.
> 
> 	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.
Pod::Checker looks for a hyphen as well.

As I said, don't muck about with the formatting, there's no point. Note
that Pod::Man (at least) converts that hyphen into the roff escape
sequence for an endash (along with other instances of " - "), so if you
don't get endashes in the output it's because your formatter doesn't
know how to produce them. 'groff -man -Tps' at least will get them
right.

> 	I've not seen any problem with pod2man(1) vs. NAME as of yet.
> 	What should I take note of?
> 
> 	(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?

Ben

[toc] | [prev] | [next] | [standalone]

#8518 — issues with POD

>>>>> Ben Morrow <ben@morrow.me.uk> writes:
>>>>> Quoth Ivan Shmakov <oneingray@gmail.com>:
>>>>> Ben Morrow <ben@morrow.me.uk> writes:

[...]

 >>> pod2man in particular is quite picky about it, and there are other
 >>> tools which rely on the format being right.

 >> 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.

 > Pod::Checker looks for a hyphen as well.

 > As I said, don't muck about with the formatting, there's no point.
 > Note that Pod::Man (at least) converts that hyphen into the roff
 > escape sequence for an endash (along with other instances of " - "),

	Frankly, I consider the unconditional replacement of " - " to be
	a hack by itself.

	Why, I've seen a Usenet poster who'd use groff to format his
	messages.  Guess what he'd end up when quoting code?

 > 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.

--cut: http://search.cpan.org/perldoc?Digest --
NAME ^-

    Digest - Modules that calculate message digests
--cut: http://search.cpan.org/perldoc?Digest --

	Note the HYPHEN-MINUS propagated to the resulting HTML.

	... Indeed, my first thought was to use DocBook or XHTML 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.

	(A reminder to myself: suggest updates to [1].)

[1] http://www.tldp.org/HOWTO/DocBook-Demystification-HOWTO/

 > '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 and software freedom.

	(Not unlike HTML "adorned" with JavaScript, Java, or
	Adobe Flash, which became such a commonplace on the Web.)

	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.)

 >> I've not seen any problem with pod2man(1) vs. NAME as of yet.  What
 >> should I take note of?

 >> (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.  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:

    [...]  Many *roff implementations cannot handle non-ASCII
    characters, so this means all non-ASCII characters are converted
    either to a *roff escape sequence that tries to create a properly
    accented character (at least for troff output) or to "X".

-- 
FSF associate member #7257

[toc] | [prev] | [next] | [standalone]

#8521 — Re: issues with POD

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.)

>  > Pod::Checker looks for a hyphen as well.
> 
>  > As I said, don't muck about with the formatting, there's no point.
>  > Note that Pod::Man (at least) converts that hyphen into the roff
>  > escape sequence for an endash (along with other instances of " - "),
> 
> 	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.

>  > 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.

> 	... Indeed, my first thought was to use DocBook or XHTML

Ewww, yuck. Formats designed by and for pedants.

>       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.

>  > '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. (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.))

>       and software freedom.

Don't be so ridiculous.

> 	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.

>  >> I've not seen any problem with pod2man(1) vs. NAME as of yet.  What
>  >> should I take note of?
> 
>  >> (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.

>       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.) Remember, all this stuff comes from perl 5.000, before perl (or
groff, I expect) had any sort of Unicode support.

Ben

[toc] | [prev] | [next] | [standalone]

#8524 — Re: issues with POD

>>>>> 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

[toc] | [prev] | [next] | [standalone]

#8526 — Re: issues with POD

Quoth Ivan Shmakov <oneingray@gmail.com>:
> >>>>> 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.)

No, it isn't. That's exactly my point. The content of the NAME section
is syntax, and it needs to look like

    <title> - <abstract>

with an ASCII hyphen. You may not like this, but that's the way it is.

>  >>> 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?

The former. The assumption about NAME formatting is widespread, and you
don't know what types of systems people might be using your module on or
what sort of Pod-formatting tools they might have. Portability is more
important than typographical niceties.

>  >> 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?

Are you serious? Run 'perldoc Pod::Man' from your shell prompt.

More generally, providing HTML documentation means you *only* provide
HTML documentation. Pod can be converted to a great many formats (that's
the point).

>  >>> '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.)

Perl documentation distributed in any format other than Pod is
worthless, since perldoc can't find it.

>  > (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.)

Because my printer speaks PostScript? (Actually it doesn't, but
historically that was the reason for using it.)

>  >> 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.

Me either. What makes you think the Turing-completeness of the language
used makes any difference to that, though? I very much doubt any such
licences are enforcable, in any case; certainly not if you're just using
the document as a document, and not trying to pick it apart and use the
bits to write your own PostScript driver.

>  >> 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.

That would be the FreeBSD base system. The groff there is not going to
be updated, it's going to be replaced, because newer groffs are GPLv3.

> 	(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.)

We're not going to do that. We *like* Pod. Personally, when I'm writing
technical documentation, I would write in Pod for choice. I appreciate
its lack of clutter.

>  >> 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.)

...no, it means that changing it would break backcompat, so it's
probably not going to happen. (Not to mention that the whole question of
dealing with non-ASCII command-line arguments is largely unsolved on
non-Win32 systems.)

>  > 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?

Because noone in a position to change it thinks it's a bug, or thinks
it's worth fixing? We're talking about pod2man here; I doubt anyone's
run it with --quotes for a very long time.

Ben

[toc] | [prev] | [next] | [standalone]

#8527 — $ pod2man --quotes=

>>>>> Ben Morrow <ben@morrow.me.uk> writes:
>>>>> Quoth Ivan Shmakov <oneingray@gmail.com>:
>>>>> Ben Morrow <ben@morrow.me.uk> writes:

[...]

 >>> 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.)

 > ... no, it means that changing it would break backcompat, so it's
 > probably not going to happen.

	How would it?  Currently, the use of --quotes= with arguments
	other than the two-octet ones and "none" results in an error.
	Having pod2man interpret multi-octet sequences as two-character
	ones looks like a "pure" extension.

	Besides, that appears to contradict your own claim below that
	"pod2man [is not being run] with --quotes for a very long time."

 > (Not to mention that the whole question of dealing with non-ASCII
 > command-line arguments is largely unsolved on non-Win32 systems.)

	On POSIX systems, I'd expect non-ASCII command-line arguments to
	be passed as octet sequences, in the encoding specified by the
	LC_CTYPE category.

	It has worked for me so far, 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?

 > Because noone in a position to change it thinks it's a bug, or thinks
 > it's worth fixing?  We're talking about pod2man here; I doubt
 > anyone's run it with --quotes for a very long time.

	Which appears to make the compatibility concerns irrelevant.

-- 
FSF associate member #7257

[toc] | [prev] | [next] | [standalone]

#8528 — Re: issues with POD

>>>>> 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>:

[...]

 >> The HTML syntax /allows/ Unicode quotes.  Inside the payload, that
 >> is.  (Which the text of the NAME section certainly is.)

 > No, it isn't.  That's exactly my point.  The content of the NAME
 > section is syntax, and it needs to look like

 >     <title> - <abstract>

 > with an ASCII hyphen.  You may not like this, but that's the way it
 > is.

	I don't like, and it won't happen on my Pods.

	It's free software, though.  Anyone's free take the Pods and
	improve (or "improve") them as one sees fit.

[...]

 >> 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?

 > The former.  The assumption about NAME formatting is widespread, and
 > you don't know what types of systems people might be using your
 > module on or what sort of Pod-formatting tools they might have.
 > Portability is more important than typographical niceties.

	Well, let's see if there'd be any actual bug reports...

[...]

 >>> 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?

 > Are you serious?  Run 'perldoc Pod::Man' from your shell prompt.

$ perldoc Pod::Man 
You need to install the perl-doc package to use this program.
$ 

	So?

	But if you mean that perldoc is just a fancy way to extract the
	Pods out of the sources, convert them into executable roff code,
	interpret them with roff, and produce a kind of "extended" ASCII
	document, -- then I'd like to note that the intermediate roff
	code is already present on my system, and M-x woman in Emacs
	shows it without actually executing it with a roff interpreter.

 > More generally, providing HTML documentation means you *only* provide
 > HTML documentation.

	It doesn't.  Arguably, a profile of even the good old
	HTML 4.0 Strict that matches the expressiveness of Pod would be
	easier to convert into a variety of formats than Pod itself.

	However, I understand that it's a common misconception.
	Hopefully, I'd be able to prepare some counter-examples for the
	SFD this September.

 > Pod can be converted to a great many formats (that's the point).

	So can be DocBook.

[...]

 >>>> 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.)

 > Perl documentation distributed in any format other than Pod is
 > worthless, since perldoc can't find it.

	?  How does this relate to my suggestion to avoid PostScript?

 >>> (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.)

 > Because my printer speaks PostScript?  (Actually it doesn't, but
 > historically that was the reason for using it.)

	Nowadays, the majority of printers speak neither PostScript nor
	PDF.  It's the host the printer's attached to that does.  And
	I'd argue that the host speaks PDF more often than PostScript.

 >>>> 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.

 > Me either.  What makes you think the Turing-completeness of the
 > language used makes any difference to that, though?

	It doesn't.  Yet I fail to understand the purpose the software
	may embed some "hidden" non-code /creative/ work of its
	developer into the resulting document.

 > I very much doubt any such licences are enforceable, in any case;

	Perhaps; IANAL.

 > certainly not if you're just using the document as a document, and
 > not trying to pick it apart and use the bits to write your own
 > PostScript driver.

	If /I/ release the document in question under, say, CC BY-SA,
	how the recipient (licensee) is expected to know that some parts
	of the document's own digital representation are in fact under
	some other license, issued by a third party?

[...]

 >> To me, it looks much more like a very good reason to update the
 >> particular groff install.

 > That would be the FreeBSD base system.  The groff there is not going
 > to be updated, it's going to be replaced, because newer groffs are
 > GPLv3.

	I was unaware that the FreeBSD developers are opposing GPLv3.
	And why do they, BTW?  (It was always my impression that FreeBSD
	is more lax regarding the licenses than, say, Debian.)

	Anyway, isn't it possible to install an (additional) groff
	instance from the ports?

 >> (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.)

 > We're not going to do that.  We *like* Pod.

	Slightly tangential to the discussion is the question whether
	the "total manpower" of /we/ is currently rising or diminishing?

 > Personally, when I'm writing technical documentation, I would write
 > in Pod for choice.  I appreciate its lack of clutter.

	... And also predictability, structure, the ease to run
	structured searches against, etc.?

[...]

-- 
FSF associate member #7257

[toc] | [prev] | [next] | [standalone]

#8532 — Re: issues with POD

Quoth Ivan Shmakov <oneingray@gmail.com>:
> >>>>> Ben Morrow <ben@morrow.me.uk> writes:
> >>>>> Quoth Ivan Shmakov <oneingray@gmail.com>:
> 
>  >> "Command-line perldoc"?  What's it?
> 
>  > Are you serious?  Run 'perldoc Pod::Man' from your shell prompt.
> 
> $ perldoc Pod::Man 
> You need to install the perl-doc package to use this program.

Your perl install is broken; it has been mangled by over-zealous
packagers looking to save a few bytes. You need to find which magic
package to install to give you the whole thing.

> 	But if you mean that perldoc is just a fancy way to extract the
> 	Pods out of the sources, convert them into executable roff code,
> 	interpret them with roff, and produce a kind of "extended" ASCII
> 	document, -- then I'd like to note that the intermediate roff
> 	code is already present on my system, and M-x woman in Emacs
> 	shows it without actually executing it with a roff interpreter.

OK, if that works for you. A lot of Perl programmers use perldoc, and
rely on it working properly, so providing documentation perldoc can't
find is not helpful.

[PostScript]
>  >>
>  >> 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.)
> 
>  > Perl documentation distributed in any format other than Pod is
>  > worthless, since perldoc can't find it.
> 
> 	?  How does this relate to my suggestion to avoid PostScript?

Since Perl documentation is distributed in Pod format, the only reason
you would have it in PS is because you have generated it yourself,
presumably with tools you trust not to put anything malicious in the
output.

>  >> 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.
> 
>  > Me either.  What makes you think the Turing-completeness of the
>  > language used makes any difference to that, though?
> 
> 	It doesn't.  Yet I fail to understand the purpose the software
> 	may embed some "hidden" non-code /creative/ work of its
> 	developer into the resulting document.

Fonts? And they usually have quite restrictive licences, from a 'reusing
in other documents' point of view.

>  > I very much doubt any such licences are enforceable, in any case;
> 
> 	Perhaps; IANAL.
> 
>  > certainly not if you're just using the document as a document, and
>  > not trying to pick it apart and use the bits to write your own
>  > PostScript driver.
> 
> 	If /I/ release the document in question under, say, CC BY-SA,
> 	how the recipient (licensee) is expected to know that some parts
> 	of the document's own digital representation are in fact under
> 	some other license, issued by a third party?

By applying common sense. Your copyright and therefore your licence
applies to what you created, that is, to the content of the document. 

>  >> To me, it looks much more like a very good reason to update the
>  >> particular groff install.
> 
>  > That would be the FreeBSD base system.  The groff there is not going
>  > to be updated, it's going to be replaced, because newer groffs are
>  > GPLv3.
> 
> 	I was unaware that the FreeBSD developers are opposing GPLv3.
> 	And why do they, BTW?  (It was always my impression that FreeBSD
> 	is more lax regarding the licenses than, say, Debian.)

I don't know the details; all I know is the GPLv3 has been deemed too
restrictive for the base system. Unlike Debian, the ports collection
still contains software with all licences, open-source and commercial;
though of course the prebuilt packages are only available where the
licence allows it.

> 	Anyway, isn't it possible to install an (additional) groff
> 	instance from the ports?

Why would I want to do that? The only thing I use groff for is to read
manpages. Why would I want them as PDFs? (Or as PostScript, for that
matter; I was only using it as an example of a format I expected to get
the endashes right.)

>  >> (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.)
> 
>  > We're not going to do that.  We *like* Pod.
> 
> 	Slightly tangential to the discussion is the question whether
> 	the "total manpower" of /we/ is currently rising or diminishing?

If Perl is dying (which it isn't, by the way), it's not because we don't
use DocBook.

>  > Personally, when I'm writing technical documentation, I would write
>  > in Pod for choice.  I appreciate its lack of clutter.
> 
> 	... And also predictability, structure, the ease to run
> 	structured searches against, etc.?

No, mostly I appreciate its lack of clutter. Pod makes writing
documentation no harder than writing comments, which means I actually do
write documentation, even for code I don't think anyone else will ever
see. This is a Good Thing.

(Besides, what do I need structured searches for? I've got ack.)

Ben

[toc] | [prev] | [next] | [standalone]

#8533 — [OT] PostScript

>>>>> 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>:

[...]

 >>>> 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.

 >>> Me either.  What makes you think the Turing-completeness of the
 >>> language used makes any difference to that, though?

 >> It doesn't.  Yet I fail to understand the purpose the software may
 >> embed some "hidden" non-code /creative/ work of its developer into
 >> the resulting document.

 > Fonts?  And they usually have quite restrictive licences, from a
 > 'reusing in other documents' point of view.

	Indeed.  Though in practice, I fail to recall using any fonts
	that fail to meet DFSG for my documents recently.

[...]

 >>> certainly not if you're just using the document as a document, and
 >>> not trying to pick it apart and use the bits to write your own
 >>> PostScript driver.

 >> If /I/ release the document in question under, say, CC BY-SA, how
 >> the recipient (licensee) is expected to know that some parts of the
 >> document's own digital representation are in fact under some other
 >> license, issued by a third party?

 > By applying common sense.  Your copyright and therefore your licence
 > applies to what you created, that is, to the content of the document.

	And how the recipient is intended to know that?

	The same applies to the other kinds of works, though.  But for
	the images and such, I'd expect the copyrights to be properly
	stated in the /visible/ part of the document.  For the fonts, it
	may seem a bit excessive.  Still, for the embedded code parts,
	-- I wouldn't expect it to happen at all.

[...]

-- 
FSF associate member #7257

[toc] | [prev] | [next] | [standalone]

#8534 — Re: issues with POD

>>>>> 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>:

 >>>> "Command-line perldoc"?  What's it?

 >>> Are you serious?  Run 'perldoc Pod::Man' from your shell prompt.

 >> $ perldoc Pod::Man

 >> You need to install the perl-doc package to use this program.

 > Your perl install is broken;

	"It's not a bug."

 > it has been mangled by over-zealous packagers looking to save a few
 > bytes.  You need to find which magic package to install to give you
 > the whole thing.

	Fortunately, with the error message quoted above, the packagers
	already made that a trivial thing to do.

	JFTR: the purpose of such splits is to avoid the installation of
	the documentation on the hosts that merely /run/ existing code,
	and aren't used for the actual development.  The installs I use
	for Perl development are /ought/ to contain "perl-doc," but
	I forgot to do it for this particular one, and I'm not quite
	inclined to touch it in the foreseeable future.  In the
	meantime, I use http://search.cpan.org/perldoc? and
	http://perldoc.perl.org/.  (Besides, Lynx is almost as fancy as
	the Emacs' own WoMan browser.)

 >> But if you mean that perldoc is just a fancy way to extract the Pods
 >> out of the sources, convert them into executable roff code,
 >> interpret them with roff, and produce a kind of "extended" ASCII
 >> document, -- then I'd like to note that the intermediate roff code
 >> is already present on my system, and M-x woman in Emacs shows it
 >> without actually executing it with a roff interpreter.

 > OK, if that works for you.  A lot of Perl programmers use perldoc,
 > and rely on it working properly, so providing documentation perldoc
 > can't find is not helpful.

	Nowhere have I opposed the use of perldoc.  What I contest is
	the use of perldoc as the ultimate judge of the documentation
	format.

	To put it another way: if perldoc can't find the documentation,
	-- it's clearly a bug.  But it's not necessarily a bug in the
	/documentation/ itself.

	That being said, I'm (obviously) not familiar with perldoc.
	Thus, I'm curious if there's any compelling reason for perldoc
	/not/ to support, say, DocBook (or DITA, HTML, TEI, etc.)?

[...]

 >> Anyway, isn't it possible to install an (additional) groff instance
 >> from the ports?

 > Why would I want to do that?  The only thing I use groff for is to
 > read manpages.

	ACK.  Although I've found some other uses for groff on
	occasions, as I've stated before, I don't usually use it for
	reading the manpages, either.

[...]

 >>>> (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.)

 >>> We're not going to do that.  We *like* Pod.

 >> Slightly tangential to the discussion is the question whether the
 >> "total manpower" of /we/ is currently rising or diminishing?

 > If Perl is dying (which it isn't, by the way), it's not because we
 > don't use DocBook.

	I didn't assert either of that.  (Even though there're several
	definitions of "dying," I guess I understand what you mean.)

	My point is that I know of no reason for a programmer looking
	for a new language to learn to choose Perl, and I'm not actually
	seeing a lot of newcomers to join this group lately, either.
	(As compared to, say, news:comp.lang.javascript and
	news:comp.lang.python...  Why, should they get a Perl course on
	Coursera, wouldn't it be rightful to call it "The glorious, and
	overly long, history of the Perl programming language", or
	something like that?)

	The other point to note is that even though I'm using Perl for
	almost decade and a half now (on and off), I still can't make
	head or tail of it at times.  On the contrary, while I have put
	virtually no effort to learn Python whatsoever, I seem to
	understand the code written in it quite well.

	So, there're two reasons for me to stick to Perl.  First of all,
	it has a rich set of (quality) libraries (although Go, and
	perhaps Python, Racket, etc. may surpass it in the near future,
	if not already have), which appear to cover my demands well.

	The other reason is that Perl isn't of the "one size fits all"
	type.  Contrast it with Python ("one indentation fits all"), or
	Racket ("one package format fits all"), or Go ("one
	documentation format fits all")...

	... Or is it?

[...]

-- 
FSF associate member #7257

[toc] | [prev] | [next] | [standalone]

#8543 — Re: issues with POD

In <877ghe786a.fsf@violet.siamics.net>, on 06/28/2013
   at 12:04 PM, Ivan Shmakov <oneingray@gmail.com> said:

>	That being said, I'm (obviously) not familiar with perldoc.
>	Thus, I'm curious if there's any compelling reason for perldoc
>	/not/ to support, say, DocBook (or DITA, HTML, TEI, etc.)?

Is there any compelling reason for DecBook et al to not support
perldoc? I'd be happy if the Perl community magically switched to
DocBook, but as a practical matter the cost of converting everything
would be to high. A mixture of two different documentation formats
could get very ugly very quickly.

>	My point is that I know of no reason for a programmer looking
>	for a new language to learn to choose Perl,

CPAN

>	The other point to note is that even though I'm using Perl for
>	almost decade and a half now (on and off), I still can't make
>	head or tail of it at times.  On the contrary, while I have put
>	virtually no effort to learn Python whatsoever, I seem to
>	understand the code written in it quite well.

The most arcane part of Perl is the Regex sybtax; Python and Ruby are
in the same tradition. I'd really prefer something more in the
tradition of Icon, SNOBOL and Wylbur.

>	The other reason is that Perl isn't of the "one size fits all"
>	type.  Contrast it with Python ("one indentation fits all"),

"We hates it, precious, we hates the nasty thing." I'll take
semicolons and a prettyprinter, TYVM.

-- 
Shmuel (Seymour J.) Metz, SysProg and JOAT  <http://patriot.net/~shmuel>

Unsolicited bulk E-mail subject to legal action.  I reserve the
right to publicly post or ridicule any abusive E-mail.  Reply to
domain Patriot dot net user shmuel+news to contact me.  Do not
reply to spamtrap@library.lspace.org

[toc] | [prev] | [next] | [standalone]

#8544 — Re: issues with POD

>>>>> Shmuel (Seymour J ) Metz <spamtrap@library.lspace.org.invalid> writes:
>>>>> Ivan Shmakov <oneingray@gmail.com> said:

 >> That being said, I'm (obviously) not familiar with perldoc.  Thus,
 >> I'm curious if there's any compelling reason for perldoc /not/ to
 >> support, say, DocBook (or DITA, HTML, TEI, etc.)?

 > Is there any compelling reason for DecBook et al to not support
 > perldoc?  I'd be happy if the Perl community magically switched to
 > DocBook, but as a practical matter the cost of converting everything
 > would be to high.

	Yes.

 > A mixture of two different documentation formats could get very ugly
 > very quickly.

	Why?

	To note is that there already /is/ a mixture, assuming that one
	uses an operating system which isn't written entirely in Perl.

	So, we have pure-roff; roff generated from a variety of sources
	(including both DocBook and Pod); AsciiDoc; Markdown; plain text
	(mainly READMEs; in ASCII, UTF-8, and, occasionally, other
	encodings); Texinfo; and what not.  And all of that appears to
	work reasonably well in practice.

 >> My point is that I know of no reason for a programmer looking for a
 >> new language to learn to choose Perl,

 > CPAN

	... Which I've actually mentioned (kind of.)  But then, take a
	look at, say, [1, 2].

	... But it may be a reason worth considering.  We're currently
	preparing for the local SFD event, and I guess we may invest
	some time in writing a dozen or so of blog entries on free
	software (and digital freedom in general.)  Hopefully, I'd be
	able to write something reasonably decent on Perl.  Naturally,
	CPAN would be the first feature to mention.

[1] http://pypi.python.org/pypi
[2] http://code.google.com/p/go-wiki/wiki/Projects

 >> The other point to note is that even though I'm using Perl for
 >> almost decade and a half now (on and off), I still can't make head
 >> or tail of it at times.  On the contrary, while I have put virtually
 >> no effort to learn Python whatsoever, I seem to understand the code
 >> written in it quite well.

 > The most arcane part of Perl is the Regex sybtax;

	To me, the most arcane part of Perl is that it behaves as if it
	actually /is parsed/ with a bunch of REs.

--cut: https://en.wikipedia.org/wiki/Perl --
    [...] One consequence of this is that Perl is not a tidy language.
    It includes many features, tolerates exceptions to its rules, and
    employs heuristics to resolve syntactical ambiguities.  [...]
--cut: https://en.wikipedia.org/wiki/Perl --

	The "dualvar" scalars I've recently discovered also do not look
	like a particularly clever concept.

 > Python and Ruby are in the same tradition.  I'd really prefer
 > something more in the tradition of Icon, SNOBOL and Wylbur.

	Could you please show some example, comparing the approaches?

 >> The other reason is that Perl isn't of the "one size fits all" type.
 >> Contrast it with Python ("one indentation fits all"),

 > "We hates it, precious, we hates the nasty thing."  I'll take
 > semicolons and a prettyprinter, TYVM.

	So will I.

	And the same for Go, which allows for:

   foo = (42 +
          bar +
          hello);

	but not (my preference):

   foo = (42
          + bar
          + hello);

	(Precisely because a newline after a non-operator is taken for
	an "implied semicolon".)

-- 
FSF associate member #7257

[toc] | [prev] | [next] | [standalone]

#8560 — Re: issues with POD

In <87li5r4h33.fsf@violet.siamics.net>, on 06/30/2013
   at 05:57 PM, Ivan Shmakov <oneingray@gmail.com> said:

> > A mixture of two different documentation formats could get very
> > ugly very quickly.

>	Why?

Tool sets.

>	To note is that there already /is/ a mixture,

Not within CPAN.

> > Python and Ruby are in the same tradition.  I'd really prefer
> > something more in the tradition of Icon, SNOBOL and Wylbur.
>	Could you please show some example, comparing the approaches?

As an example, in Perl I would concisely write [aeiou] while in Icon I
would write the more verbose any('aeiou'). In general, the Perl syntax
for a regex relies heavily on special characters while the other
languages I mentioned rely more heavily on words used as, e.g.,
function names. Icon in particular is nice because it has a cset[1]
(character set) data type and because patterns can be eaily built from
procedures.

[1] I vaguely recall that Perl 6 may have something similar.


-- 
Shmuel (Seymour J.) Metz, SysProg and JOAT  <http://patriot.net/~shmuel>

Unsolicited bulk E-mail subject to legal action.  I reserve the
right to publicly post or ridicule any abusive E-mail.  Reply to
domain Patriot dot net user shmuel+news to contact me.  Do not
reply to spamtrap@library.lspace.org

[toc] | [prev] | [next] | [standalone]

#8545 — Re: issues with POD

Ivan Shmakov <oneingray@gmail.com> writes:

[...]

>> it has been mangled by over-zealous packagers looking to save a few
>> bytes.  You need to find which magic package to install to give you
>> the whole thing.
>
> 	Fortunately, with the error message quoted above, the packagers
> 	already made that a trivial thing to do.
>
> 	JFTR: the purpose of such splits is to avoid the installation of
> 	the documentation on the hosts that merely /run/ existing code,
> 	and aren't used for the actual development.

In order to accomplish what? According to dpkg --print-avail, the size
of perl-doc is about 6.9M. Except rare special cases, the
inconvenience of not having the documentation at hand in some 'strange
situation' by far outweighs the possible 'space saving' here except
that some people presumably feel that 'documentation' is dead weight
because they would never read it, anyway[*].

[*] Nice little anecdote about that: A former colleague of mine used
to boast that 'only newbies read documentation' ("Nur Anfaenger lesen
Dokumentation"). Once upon a time, he and my boss went to China in
order to perform some demos there for some prospective 'large
customers'. By this time, the server part of the then-product was
usually installed on SuSE Linux systems because that was what said
former colleague always used. Consequently, he went to China with a
brand new 'free SuSE CD'. Nobody ever bothered to test this new
version together with our software and since no 'newbies' where
involved here, nobody bothered to read through the release notes for
incompatible changes, either. The end result of that was that I was
woken by an "It doesn't work and we don't know what to do" phone call
around 3am, had to go the the office and read the documentation for
him in order to determine what the problem was (MySQL default date
output format changed) and to change the software to be able to deal
with that (of course, this guy still makes more money than I do ...).

[...]

> 	My point is that I know of no reason for a programmer looking
> 	for a new language to learn to choose Perl,

It is a highly useful programming language whose 'crudely implemented
Lisp subset' is fairly complete -- you'll even get run-time modifiable
symbol tables and symbols (called globs) -- with support for automatic
management of all kinds of resources and more than decent
performance. Eg, I use OO-Perl to make real-time WWW content-filtering
descisions and the latency of that is in the order of at most about a
dozebn 0.0001s --- that's something Java developers don't even dream
of (OTOH, it is presumably possible to force perl down to
JBoss/Hibernate/SEAM levels by adding enough 'CPAN frameworks' to it).

[toc] | [prev] | [next] | [standalone]

#8535 — Re: issues with POD

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>:
>> 
>>  >> "Command-line perldoc"?  What's it?
>> 
>>  > Are you serious?  Run 'perldoc Pod::Man' from your shell prompt.
>> 
>> $ perldoc Pod::Man 
>> You need to install the perl-doc package to use this program.
>
> Your perl install is broken; it has been mangled by over-zealous
> packagers looking to save a few bytes. You need to find which magic
> package to install to give you the whole thing.

"Please note that whatever precisely constitutes 'the whole thing'
might be subject to change with little or no advance warning based on
what 'certain developers' presently do or don't consider fashionable",
possibly based on outright irrational reasons (or intentionally
disingenious mock arguments. It is not always possible to distinguish
which is which) such as

	I find no small irony in a few posts asking whether there's
	any reason to use Moose or Mouse or Moo when you can write
	your own object accessors by hand (I wrote my own templating
	system by hand too. No more.)

Side remark: I should be noted that the suspicion that what was
supposed to be the be-all and end-all of YARFPOO has already again
'logically' splintered into three different semi-compatible
implementations with mutually exclusive design goals is correct. More
to follow as time goes by and old non-solutions to non-problem are
abandoned because their non-maintainers get bored with them and people
discover more aspects in which all of the existing YARFPOOs are deficient
in this or that way and hence, set forth to - once and for all this
time! - nail the jello to the tree in the perfect way 'from scratch'
all over again. Structual similarities to daily soap opera
installments are unintentional but very like not accidental.

I wonder if somebody ever really asked a so thoroughly stupid question
when considering the scope of the moose mouse that mooed versus
'writing accessors'. This looks suspiciously like strawman. 'writing
accessors' is not a particularly sensible activity in its own right:
Objects should provide behaviour and not hierarchically structured
storage. If a particular 'behaviour' can sensibly be abstracted away
from a specific way of handling state information, it shouldn't be
tied to one: The implementation should be capable of working with all
kinds of objects providing a compatible interface and not be part of
any of them. Comparing 'writing accessors' to 'writing a template
system' is again totally bogus: The tasks are of vastly differing
technical complexity.

As a rule of thumb, people resort to sophisms when marketing their
opinions when they can't think of any better way to further their
causes. This may be because they themselves know that they are wrong
or - considering that 'web development' is what the guy who runs the
advertising agency dabbles in - because they're really marketing
specialists to whom all this 'programming stuff' is part of the cost
of displaying advertisements they'd rather (and totally rationally
in this case) want to get rid of.

The problem with this is that computers do more (and much more
sophisticated) things than "being your plastic pal who's fun to be
with" and what minimizes the per-case workload of the guy who decides
on the colour said 'plastic pal' should have today (and hence, helps
him to maximize his income for a given time period) might not be the
most sensible way to construct 24x7 autonomously operating software
system people rely on in order to get some (not inherently
computer-related) job done.

[toc] | [prev] | [next] | [standalone]

Page 1 of 3  [1] 2 3  Next page →

Back to top | Article view | comp.lang.perl.misc

csiph-web