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

Groups > comp.lang.perl.misc > #8528

Re: issues with POD

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

[...]

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

Back to comp.lang.perl.misc | Previous | Next — Previous in thread | Next in thread | Find similar

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