Re: Tables in PODs
On Fri, Sep 20, 2013 at 10:30:13AM -0400, Shawn H Corey wrote: Is there any specification for tables in PODs? I haven't been able to find any. Isn't it about time tables were added? I have attached a specification for them for your review. There is a perl 6 specification for tables. See https://raw.github.com/perl6/specs/master/S26-documentation.pod and an implementation for Perl 5, at least for HTML: https://metacpan.org/module/Perl6::Pod However, the big question I don't know the answer to is if anyone has implemented code to output tables to man pages. man can do tables (very nicely), but I know approximately zero roff, so I don't know how easy it is (or isn't) Or how good plain text output for tables is. Nicholas Clark
Re: How do I get Pod::Simple to extract pod from its containing file?
On Tue, Jan 29, 2013 at 11:52:43AM -0700, Karl Williamson wrote: On 01/26/2013 08:37 PM, Karl Williamson wrote: On 01/26/2013 07:44 PM, Russ Allbery wrote: Karl Williamson pub...@khwilliamson.com writes: On 01/26/2013 02:23 PM, Russ Allbery wrote: Karl Williamson pub...@khwilliamson.com writes: With Pod::Parser, you just do parse_from_file($in_fh, $out_fh) and it outputs the pod to $out_fh. Pod::Simple has a method of the same name which is supposed to emulate the Pod::Parser method, but when I run it, nothing is output. Oh! I misunderstood, sorry. parse_from_file() does indeed invoke the parser with the appropriate actions, but what you meant was that Pod::Parser's null parser, when not subclassed, just printed the POD back out again, so you could use it as a way to extract the POD from a file. I believe Pod::Simple's null parser does nothing at all, so you get an empty file. Yes. I think that's an incompatibility. If I turn on DEBUGing, it's doing a lot. Is there some trivial way to extract the pod? So no one thinks there is a trivial way to get this extraction. Would someone make a suggestion as to the easiest way to do so using modules that will continue to ship with the Perl 5 core (unlike Pod::Parser)? No-one answered this, did they? Is it possible to extract the pod by subclassing Pod::Simple, and the subclass being a null parser that prints out the Pod that it was given? Nicholas Clark
Re: Version comments in POD output
On Thu, Dec 27, 2012 at 09:42:34AM -0500, Ricardo Signes wrote: * Russ Allbery r...@stanford.edu [2012-12-26T17:47:41] Do people feel this comment line provides much real utility in Pod::Man output? I could add a flag to suppress it, but I'm tempted to just drop it entirely, since I'm not sure that it's really doing anyone any good. I have often found such lines *in other programs* useful for sorting out bugs. I've never tried debugging the podlators, thankfully! :) My inclination would be to add the flag for such packagers to use, but I'm not particularly invested in the problem. Me too. In that my experience and situation parallels Ricardo's. A flag for people who know what they are doing to disable the generation of comments feels like the best compromise, as such people likely also know how to debug their toolchain if they get a problem. (Rather than asking upstream, at which point the generated by comments are useful to upstream.) Nicholas Clark
Re: please test perl5.git's Pod-Html
On Wed, Feb 22, 2012 at 11:53:04AM -0500, Ricardo Signes wrote: I've already asked for some testing on p5p, but oh ye devoted pod people: If you have the time, install perl from git, commit ac2b477 or later, and play around with pod2html and let us know what is broken. If you don't have git installed, you can get a snapshot from HTTP. Current snapshots are linked on http://perl5.git.perl.org/perl.git as snapshot. The specific version Ricardo mentions is this one: http://perl5.git.perl.org/perl.git/snapshot/ac2b477c8b4b647797d42877de5b1a1d34c94073.tar.gz Nicholas Clark
Re: no deprecation warning for Lsection
On Sat, Apr 30, 2011 at 05:31:00PM +0100, Michael Stevens wrote: On Fri, Apr 29, 2011 at 08:58:37AM -0600, Karl Williamson wrote: People on this list might be interested in the extensions to Pod::Checker, some of which might be considered for pulling back into Pod::Checker. Attached is the current pod for podcheck.t I have things I'd like to change in Pod::Checker, but it seems to be considered untouchable until the move to Pod::Simple. It somewhat is, as a side effect of the attempt at having a consistent policy on what is upstream. Pod::Checker is part of the Pod-Parser distribution. The core's who owns what file, Porting/Maintainers.pl, says that Pod-Parser isn't maintained in core, and that upstream is MAREKR. MAREKR says that is (well), effectively dead. So the core policy works out as send patches to MAREKR and MAREKR's policy works out as no thanks. Which isn't exactly ideal. At which point, the two obvious routes forward to resolve this are either a: move to maintaining Pod-Parser as part of the core or b: more to eliminating the need for Pod-Parser and the consensus seems to be that (b) is far less insane. I think that what's then gone wrong is that no-one wants to start on it, but given that it is the future, everyone thinks that doing anything in the direction of (a) is a waste of effort. Which stalls. Nicholas Clark
Re: `=item 1. Text` Doesn't Produce Ordered List Item
On Tue, Jul 20, 2010 at 05:00:43PM -0400, Ricardo Signes wrote: * David E. Wheeler da...@kineticode.com [2010-07-20T16:40:18] perlpodspec says that the former is an unordered list and the latter is a description list. I think pod2html is wrong here. If so, my next question would be: how dependent are people on this? Is it something we want to consider adding to the spec? Or should pod2html be changed to remove this interpretation? I would like to see pod2html (as a Pod::Html-based thing) be replaced with Pod::Simple, which should fix this. Noncompliant documents should be fixed. I would love to see Pod::Html (and Pod::Checker) replaced with Pod::Simple based equivalents. But I don't have the time to do this. http://news.perlfoundation.org/2010/07/2010q3-call-for-grant-proposal.html might be useful for others, if time == money (or they can define an exchange rate between the two) Nicholas Clark
Re: Why does Pod::Checker deprecate section numbers in links to man pages?
On Tue, Jun 01, 2010 at 08:52:28PM +0200, Marek Rouchal wrote: Guys, I am awfully sorry, but I am not able to follow up on all this. Pod::Parser is declared stable, i.e. dead since quite a while. The sensible solution would be to rewrite I wasn't aware of that. Thanks for the confirmation. Pod::Checker, Pod::Usage and friends with Pod::Simple, as suggested by Sean M. Burke long ago, and leave Pod::Parser alone. Any volunteers for that? Excellent. Sadly I don't have time to volunteer to do this, but if someone is able to do this in the next 6 months or so, we can set things in train to remove Pod::Parser from the core for 5.16 Nicholas Clark
Re: Why does Pod::Checker deprecate section numbers in links to man pages?
On Fri, May 28, 2010 at 10:33:13PM -0600, karl williamson wrote: And in fact, recommends not using L to anything other than another pod. This seems like a useful feature, which is supported at least in html. I've searched the archives but not found anything. git blame on the lines in question in blead from cpan/Pod-Parser/lib/Pod/Checker.pm points to commit 92e3d63aacb66085fea74c3f951f09e136337b97 Update to Pod::Parser 1.17, from Brad Appleton. Some grovelling in CPAN reveals that the code was added in release 1.091 of Pod-Parser: http://search.cpan.org/diff?from=PodParser-1.09to=PodParser-1.091w=1 commented out in release 1.093 of Pod-Parser: http://search.cpan.org/diff?from=PodParser-1.092to=PodParser-1.093w=1 uncommented in release 1.14 of Pod-Parser: http://search.cpan.org/diff?from=PodParser-1.13to=PodParser-1.14w=1 and documented in release 1.15 of Pod-Parser: http://search.cpan.org/diff?from=PodParser-1.14to=PodParser-1.15w=1 No idea whether Brad Appleton, Marek Rouchal, or someone else initiated these changes On Sat, May 29, 2010 at 01:01:35PM -0700, Russ Allbery wrote: karl williamson pub...@khwilliamson.com writes: And in fact, recommends not using L to anything other than another pod. This seems like a useful feature, which is supported at least in html. Yes, I disagree with this as well and have POD conversion software that relies on being able to use L for man pages, URLs, and several other things that aren't POD. If you have tools available to create real links for man pages, you want to allow specifying man pages in L, since otherwise you have to make guesses at whether something(1) is a man page reference or something else. So this is a bad thing to deprecate. Agree. As I loathe heuristics, because they mean that you can't predict how your document will be parsed, and effectively mean that you can't write some totally legitimate code examples without it mistakenly being treated as a link. Nicholas Clark
Re: deprecating LSection
On Tue, Dec 01, 2009 at 10:52:51AM -0800, David E. Wheeler wrote: On Dec 1, 2009, at 10:46 AM, Nicholas Clark wrote: Gosh, I didn't know Pod-Simple included those. I'd much prefer it be core, to keep the reference separate from an implementation. (I wouldn't object to Pod-Spec, but I don't think we want to give core one more thing to sync up.) Core doesn't mind, as long as there's an answer. (The revised layout of ext, dist and cpan makes this a lot easier. Whilst said files *are* currently under pod/ they don't have to stay there. I believe that I can patch it so that the core's build automatically grabs them from the appropriate dist dropped into cpan/, and which point it's just as easy to keep canonical as every other directory in cpan/) So are you saying that it should remain in the Pod::Simple distribution? No, I'm saying that giving core one more thing to sync up is not an issue that should affect the decision making. I don't have an opinion on where the right place *is*. I'm perfectly happy for it to be in distributions on CPAN, if that's the right place. Although I note (without investigating) http://perl5.git.perl.org/perl.git/blob/HEAD:/Porting/Maintainers.pl#l1295 # XXX these two files correspond to similar ones in blead under # pod/, but the blead ones have newer changes, and also seem to # have been in blead a long time. I'm going to assume then that # the blead versions of these two files are authoritative - DAPM 'EXCLUDED' = [ qw( lib/perlpod.pod lib/perlpodspec.pod ) ], so where ever it *does* end up, it looks like there are forks to heal, to get back to one true document. Nicholas Clark
Re: podlators/Pod::Simple backwards compatibility (was: Re: [PATCH] 5.8.8: Debian patches)
On Sun, Feb 19, 2006 at 10:09:24PM -0800, Yitzchak Scott-Thoennes wrote:
I poked at this a little more; here are some Pod::Simple changes that
fix a few differences from what Pod::Parser did: allow any kind of
object that has a getline() method, prevent output filenames beginning
,, from being special, preserve special STDERR handling. Also
specify INSTALLDIRS=perl in Makefile.PL when appropriate.
There remain a few Pod::Parser oddities not supported:
parse_from_file and parse_from_filehandle used to take an optional
initial hashref specifying options; the only one I actually saw code
for was {-cutting=0} which would make the parser assume the file
starts with pod, not with perl code.
There was code to allow parse_from_file/filehandle to be recursively
called from a handler that would make the parser continue with the new
file and then switch back to the original file, but preserve the same
output file unless a new output file were specified. I can't offhand
think of any use at all for this, much less one relevant to podlators.
Pod::Parser would close the input or output file if it opened it itself
rather than being passed a handle.
Did anything come of this?
I was wondering what subtle but known differences exist between the behaviour
of the POD modules in 5.8.8, and those in blead.
Nicholas Clark
Re: Pod::Webserver 3.04 pre-release
On Thu, Feb 02, 2006 at 05:46:50PM +, Nicholas Clark wrote: I wasn't sure if Mock::* was the best name to use. Also, the patch as supplied was intended to give the minimum changes to the POD part of the code whilst keeping everything working, more as a proof of concept than a final version. If the chosen path is to drop the use of HTTP:Daemon and associated modules, then I believe that it's possible to clean the code still further by simplifying the API between the two halves. What I feel is particularly hacky is the package Pod::Webserver::Response. HTTP::Response had proper getter/setter methods, but Pod::Webserver only needed to use the setter methods. So for maximum laziness I used AUTOLOAD to emulate the setters, and the other HTTP::* emulation code pokes around directly in the object, rather than using methods. To me this feels unclean. Although keeping things this way means that the rest of Pod::Webserver can go back to using HTTP::* proper if it wants. I'm not sure if that's really needed. Nicholas Clark
Re: Perldoc and backporting
On Fri, Jul 25, 2003 at 08:56:30AM -0800, Sean M. Burke wrote: So I got to thinking -- I could easily backport this, i.e., easily change this code to run under older Perls, so that the decent number of people still labouring with 5.005 installs of perl could at least have a nice modern perldoc if they wanted it. Can anyone see any reason not to do this? If it's easy for you to do, and you're up for it, go for it. I think that it would be a good idea. Nicholas Clark
Re: C vs C vs C x
On Sat, Jan 26, 2002 at 06:52:19PM -0700, Sean M. Burke wrote: And now I'm beginning to wonder about two problems that occur when a C code is empty (corresponding to an XML C/C). Notably, those problems are: How should C tokenize? And: How should C tokenize? [latter tokenization being:] * a C start-code (consisting of the C and all the subsequent whitespace) * a literal I'm tempted to just stipulate that codes with the syntax like C ... must not be empty, which pretty much allows the latter tokenziation in both cases. First, there's the completely obvious argument that C ... codes were devised specifically to handle the cases where the intended content contained a literal , as on C $foo-bar , so using them with no-content is daffy. I think I'd be quite happy with C being illegal if it contains only whitespace. If someone wants to write C or C then they can use single , surely? Nicholas Clark -- ENOCHOCOLATE http://www.ccl4.org/~nick/CV.html
