Re: issues with POD

From	Ivan Shmakov <oneingray@gmail.com>
Newsgroups	comp.lang.perl.misc
Subject	Re: issues with POD
Date	2013-06-28 12:04 +0000
Organization	Aioe.org NNTP Server
Message-ID	<877ghe786a.fsf@violet.siamics.net> (permalink)
References	<87y5a8es4l.fsf@violet.siamics.net> <8761wz90sq.fsf@violet.siamics.net> <5ost9a-4fc2.ln1@anubis.morrow.me.uk> <87obar7ezk.fsf@violet.siamics.net> <pvmu9a-t9f2.ln1@anubis.morrow.me.uk>

Show all headers | View raw

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

Thread

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