FW: getopt
Dear fellow pod-people, I would like to share this feedback with you, since the humble Pod-Usage that Eric is referring to would not exist without Pod-Simple and Pod-Text, so it is only fair to give credits to the entire community! Enjoy, and thanks also from my side, Marek mar...@cpan.org Von: Eric Demerling Gesendet: Montag, 2. März 2015 14:23 An: Brad Appleton; Marek Rouchal Betreff: Fwd: getopt Brad and Marek your Pod programme is worth it weight in unobtainium (if you are a Avatar fan). I am using it in ALL my current programmes and any I maintain. I am writing a Perl script to take my older programs comment lists of changes select and convert them also. POD so useful I can not get by without saying THANK YOU a million for the very useful and well thought out contribution to the Perl community!!! Eric
AW: Pod::Simple can treat binary as pod due to liberal/inconsistent regexp patterns
Right. Now I remember old threads where people would argue that POD parsers
should do exactly the same as the Perl parser - and IIRC the conclusion was
that using something like PPI to handle pathological cases like multiline
strings or here docs would be an overkill, so POD is what starts with a (valid)
POD directive. The only thing that perhaps could be changed is to skip a
__DATA__ section (but keep parsing since there may be POD behind __END__ !)
I see a potential way of resolving this, but it looks like quite a big effort:
the Perl parser could store all text it skips as POD in a similar structure
like __DATA__ so that POD parsing utilities could use a pseudo-filehandle like
this (reading POD for the current script):
while (main::__POD__) {
...
}
and for other files there could be a special open() discipline to return only
POD using the same parser. What do you think?
-Marek
Von meinem Samsung Galaxy Smartphone gesendet.
Ursprüngliche Nachricht
Von: Randy Stauner rwstau...@cpan.org
Datum:08.01.2015 19:26 (GMT+01:00)
An: David E. Wheeler da...@justatheory.com
Cc: Marek Rouchal ma...@rouchal.net, Karl Williamson
pub...@khwilliamson.com, pod-people@perl.org
Betreff: Re: Pod::Simple can treat binary as pod due to liberal/inconsistent
regexp patterns
Re: Pod::Simple can treat binary as pod due to liberal/inconsistent regexp patterns
IIRC the first liberal rx is to detect start of POD just like the Perl (language) parser does, i.e. it pauses parsing for instructions until the next =cut I think POD parsers should do the same. If the matched pod-start sequence does not match any of the known commands, it's an error condition, and we should discuss what to do then, like - throw exception - print error and/or call error callback - warn and treat the content as a plain text paragraph -Marek Von meinem Samsung Galaxy Smartphone gesendet. Ursprüngliche Nachricht Von: David E. Wheeler da...@justatheory.com Datum:08.01.2015 06:39 (GMT+01:00) An: Karl Williamson pub...@khwilliamson.com Cc: Randy Stauner rwstau...@cpan.org, pod-people@perl.org Betreff: Re: Pod::Simple can treat binary as pod due to liberal/inconsistent regexp patterns
AW: On verbatim paragraphs immediately following an =item command; and Pod::Simple
I feel that the content's of an =item should be contained within that =item's item-bullet event, instead of partially in, partially out. +1 -Marek Von: Marc Green [mailto:pongu...@gmail.com] Gesendet: Sonntag, 19. Februar 2012 06:33 An: pod-people@perl.org Betreff: On verbatim paragraphs immediately following an =item command; and Pod::Simple Hello Pod People, A simple (yet lengthy) question on verbatim paragraphs that immediately follow an =item command, and how Pod::Simple treats them: Given the following POD, =over =item * verbatim code snippet =back Should the =item be considered empty, followed by a verbatim paragraph, or should the =item's contents include the verbatim paragraph? I think the general understanding is that the content of an =item extends until the next =item command. (I found nothing in perlpodspec stating this, but I have always known it to be this way.) This supports the latter interpretation. What brought this technicality to my attention is that Pod::Simple interprets it as the former (emphasis added): $ perl -MPod::Simple::DumpAsText -E'exit Pod::Simple::DumpAsText-filter(shift)-any_errata_seen' test_verb.pod ++Document \ start_line = 1 ++over-bullet \ indent = 4 \ start_line = 1 ++item-bullet \ start_line = 3 --item-bullet ++VerbatimFormatted \ xml:space = preserve \ start_line = 5 * verbatim code snippet --VerbatimFormatted --over-bullet --Document It can be seen that the item-bullet was empty, followed by a verbatim paragraph. Contrast that with a *non-verbatim* paragraph immediately following an =item command (emphasis added): $ perl -MPod::Simple::DumpAsText -E'exit Pod::Simple::DumpAsText-filter(shift)-any_errata_seen' test_verb.pod ++Document \ start_line = 1 ++over-bullet \ indent = 4 \ start_line = 1 ++item-bullet \ start_line = 3 * a non-verbatim paragraph --item-bullet --over-bullet --Document Note that the a non-verbatim paragraph text is present within the item-bullet, unlike the previous example. The Pod::Simple::Subclassing documentation states: When an =over ... =back block is parsed where the items are a bulleted list, it will produce this event structure: over-bullet indent=4 start_line=543 item-bullet start_line=545 ...Stuff... /item-bullet ...more item-bullets... /over-bullet fake-closer=1 Note that it states there should only be item-bullet events, and nothing else in between, before, or after. This is a contradiction, and I am not sure which should be correct: the code or the docs. Experimenting more, it looks like Pod::Simple only considers the *first* normal paragraph as the item's contents, with following paragraphs remaining outside the item-bullet event (emphasis added): $ perl -MPod::Simple::DumpAsText -E'exit Pod::Simple::DumpAsText-filter(shift)-any_errata_seen' test_verb.pod ++Document \ start_line = 1 ++over-bullet \ indent = 4 \ start_line = 1 ++item-bullet \ start_line = 3 * first paragraph --item-bullet ++Para \ start_line = 7 * second paragraph --Para --over-bullet --Document Thoughts on this behavior? I feel that the content's of an =item should be contained within that =item's item-bullet event, instead of partially in, partially out. Thank you, Marc
AW: pod checker that finds missing internal links?
The main reason why I dislike an additional A is that since the existence of POD nobody really needed it - since anchors for L are created by =head and =item. And as Perl stands for simplicity and efficiency, you certainly don't want to force people to rewrite all their POD to add A markup WITH THE SAME CONTENT as the =head/=item near it. Back to the issue with the short anchor for e.g. =item open FILEHANDLE I checked Perl 5.10.x's pod directory (the one with all the perlfunc.pod, perlrun.pod etc.) - and found 30 *.pod files which use Lperlfunc/name links, where name is e.g. open, pack, binmode etc. - the short name. Who is going to rewrite these (let alone all the others) if short anchors are not created/allowed by Pod::Parser/::Checker/::Simple? The (perhaps) good news is that perlfunc.pod contains for (as far as I saw) all functions the following content, e.g.: =item vec EXPR,OFFSET,BITS Xvec Xbit Xbit vector that is, there is always Xname there... so if we accepted to treat X as an anchor, the short names could be IMHO deprecated (at the slight risk that perlfunc and perlvar, and may be a few others may need to be reviewed for completeness regarding this). Honestly, I do not see much difference in arguing whether an index entry should be an anchor or an anchor should be an index entry. I am trying to think practical, and that is: we have X and L, and all the PODs using these around. And we can add value by specifying that X creates _also_ an anchor for potential Ls to link against it. Then we would not break any existing POD and give guidance to existing or new renderers. And I think we heard enough voices saying that we need index entries, and I understand that as don't change the semantics of X being an index entry - which IMHO does not prevent us from _extending_ its meaning. -Marek -Ursprüngliche Nachricht- Von: 'Patrice Dumas' [mailto:pertu...@free.fr] Gesendet: Sonntag, 29. Januar 2012 18:46 An: pod-people@perl.org Betreff: Re: pod checker that finds missing internal links? On Sun, Jan 29, 2012 at 04:29:32PM +0100, Marek Rouchal wrote: It is nice that you are sharing your thoughts with us - but frankly speaking I do not see any concrete point. L and =head/=item may not be the perfect solution, but it is all that's been there for years, and changing this (by introducing a new anchor syntax) would require basically to rewrite all POD. Or to provide a semi-perfect Certainly not. The new anchor would be an addition. In case it was not clear, the rant about =head/=item possible inconsitencies was a side note, maybe trying to convey my ideas on a suboptimal design of the language that I think should not be carried on in further changes in the language. And I think that the L semantics is powerful enough to do any kind of link. and the same way you dislike X being an anchor, others may actually like the idea; and hey - you are not forced to link against them from elsewhere, are you? I do not disagree on X being rendered as an anchor, but it should be an index entry anchor, not a label anchor. So perhaps the concepts of POD are not perfect, but they have been practical for a long time. But maybe there is room for improvement? So show a patch that corrects things along the lines that you wrote, which might be more convincing. I am ready to do some patches, but that's not the point here. There are design issues too, on the language itself. -- Pat
AW: an 'anchor' command is missing from Pod
AFAIK Z never has any content, and is used only to put something into a place where some content is expected but without actually putting any readable content there... something like: Z I want to start a line with whitespace but it should not be interpreted as a verbatim block Xkeyword is, as correctly stated before, a meta-content used for indexing - but does not show in the rendered text. So the following line: =head2 XfoobarThe foo and bar something-or-other ... has to be interpreted like this: 1. The heading is rendered as: The foo and bar something-or-other 2. This POD document is referenced from any index under the foobar keyword, and in case the index is hyperlinked, the link would point to this heading 3. The heading can be referenced by the link LThe foo and bar something-or-other 4. (I am not sure whether this is generally true:) Some formatters also allow links against these index entries, i.e. the index keyword serves as a named anchor: Lsee also the foobar heading|/foobar Cheers, Marek PS. perldoc -f looks for the corresponding =item in perlfunc.pod -Ursprüngliche Nachricht- Von: Ricardo Signes [mailto:perl@rjbs.manxome.org] Gesendet: Samstag, 28. Januar 2012 05:14 An: pod-people@perl.org Betreff: Re: an 'anchor' command is missing from Pod * Shawn H Corey shawnhco...@gmail.com [2012-01-27T19:51:50] I thought they were using the Z code for it: =item open FILEHANDLE,EXPR =item open FILEHANDLE,MODE,EXPR =item open FILEHANDLE,MODE,EXPR,LIST Zopen You're thinking of X -- Z should always be empty, and is a zero-effect code. Xopen is used to help indexing. It isn't how perldoc -f works, though. -- rjbs
AW: pod checker that finds missing internal links?
podchecker _does_ detect wrong internal links. If you put any of the following links in the POD you quoted below, podchecker (as of Pod-Parser-1.38 and higher) will flag it as an error: L/open FILEHANDLE,MODE,EXPRESSION Lopen FILEHANDLE,MODE,EXPRESSION L/open FILEHANDLE,MODE,EXPRESSION It is true that L/open will work OK, because perlfunc (at least at the time when I wrote podchecker) contained many L/function although the actual item was =item function ARGUMENTS and I did not want to flag dozens of errors for those. In other words: if the =item text matches /(\S+)\s+\S/ Then $1 is also regarded as a valid reference for L... If you think that there should be something changed in podchecker, then please provide a complete POD example, the podchecker output and a statement on what should be changed and why. -Marek -Ursprüngliche Nachricht- Von: Patrice Dumas [mailto:pertu...@free.fr] Gesendet: Samstag, 28. Januar 2012 00:15 An: pod-people@perl.org Betreff: pod checker that finds missing internal links? Hello, I have searched for a pod checker that finds missing internal links, but I haven't found one. More precisely, podchecker coming with perl 5.10 gets it wrong, it finds multiple defined labels because it takes only into account the beginning of an =item, for example =item open FILEHANDLE,EXPR =item open FILEHANDLE,MODE,EXPR is the same for this podchecker (and I guess it is 'open'). The pod simple checker do not check for multiple labels. podlint do not find these either. Maybe podlinkcheck does it, but it also do much more. Did I miss something? Maybe this would be an interesting addition to Pod::Simple? The perl-5.14.2 documentation, maybe because there is no warning emitted by any of the pod formatters used to process it, has missing labels, in perlfunc.pod, perlapi.pod and perltoc.pod. -- Pat
Re: Deprecation of alternate text in hyperlinks
Well guys, if this is the case, then it will be up to me again to remove this error detection from Pod::Parser and release a 1.51. Would be nice if this was the final verdict on this matter... Stay tuned... -Marek Original-Nachricht Datum: Mon, 23 Jan 2012 11:27:54 -0700 Von: Karl Williamson pub...@khwilliamson.com An: David E. Wheeler da...@justatheory.com CC: pod-people@perl.org, Perl5 Porters perl5-port...@perl.org, marek.rouc...@gmx.net Betreff: Re: Deprecation of alternate text in hyperlinks On 01/23/2012 11:03 AM, David E. Wheeler wrote: On Jan 23, 2012, at 9:26 AM, Karl Williamson wrote: So, you're saying I believe the text in perlpodspec that was the motivation for these changes should be removed, and that Pod::Parser should revert to its old behavior of not checking for this. Is that so? I can’t parse that sentence, but if you’re asking if this bit should be removed: Authors wanting to link to a particular (absolute) URL, must do so only with LEltscheme:... codes (like LElthttp://www.perl.org), and must not attempt LEltSome Site Name|scheme:... codes. This restriction avoids many problems in parsing and rendering LElt... codes. Then the answer is “yes.” And Pod::Parser should be modified to allow or support Ltext|scheme:. Best, David Sorry for the confusing text. You did parse it correctly, and blead now has the text from perlpodspec removed. -- Empfehlen Sie GMX DSL Ihren Freunden und Bekannten und wir belohnen Sie mit bis zu 50,- Euro! https://freundschaftswerbung.gmx.de
AW: GSoC Status Update
For the record: I won't object at all if one of the next Perl core releases will not contain Pod-Parser any more. Like Sean Burke put it - time to give it a Viking funeral J However, Pod::Checker (including the podchecker script) should then be rewritten to use Pod::Simple, and I believe Pod::Usage is also an important module which needs to be refactored then; it is often used in conjunction with Getopt::Long. Keep up the good work! Cheers, Marek Von: Marc Green [mailto:pongu...@gmail.com] Gesendet: Dienstag, 12. Juli 2011 04:13 An: pod-people@perl.org; tpf-gsoc-stude...@googlegroups.com Betreff: GSoC Status Update Hi everyone, I have been focusing on the finer details of getting Pod::Html released this week, and I was able to look into Pod::Checker a little bit too. With the help of my mentors, essentially all of the test cases for Pod::Html pass (including the porting/ tests, which were more work than I expected due to a naming error on my part). I say essentially because one of them is still failing. However, we have determined it is not the fault of Pod::Html, but of Pod::Simple. Because of this, I am moving the test case over to Pod::Simple and will fix it before its next release. Before I can smoke (and release the module), however, a few final things must be finished. In particular, - I need to complete the aforementioned move of the failing test case, - I am going to ensure a usable version of pod2html is installed when perl is installed (via a perlbrew install of my perl branch), and - The newest version of Module::Build needs to be released and merged into the core (this version includes updates for Pod::Html). As for Pod::Checker, I am dismayed to conclude that using Pod::Simple::Checker will not suffice as a substitute; it is too featureless. Instead, I am thinking about subclassing Pod::Simple myself to create an identical (feature-wise) version of Pod::Checker. But again, this is only a thought that I need to research more into, so don't hold me to it. Another issue that comes up with Pod::Checker is the fact that it is a subclass of Pod::Parser. My mentors and I are relieved that this is an implementation detail and is not documented, so it is free to be changed. Also, the fact that its home is under cpan/Pod-Parser/Pod will provide some trouble when removing Pod-Parser. rjbs said he will look into that. For next week, I want to *finally* finish Pod::Html. What a momentous occasion that will be! In addition, I am going to continue my investigation of Pod::Checker. Thanks, Marc
AW: Handling nested =open directives
I agree, too and would like to add that any formatter should flag that as an error, especially podchecker. -Marek -Ursprüngliche Nachricht- Von: David E. Wheeler [mailto:da...@kineticode.com] Gesendet: Sonntag, 26. Juni 2011 06:19 An: Marc Green Cc: pod-people@perl.org Betreff: Re: Handling nested =open directives On Jun 25, 2011, at 1:19 PM, Marc Green wrote: Given the following erroneous POD, should the formatter interpret the bold line as the start of a text paragraph and indent it (and therefore each line afterwards would also be treated as a text paragraph), or should the formatter keep the bold line at the same indent level as the prior italicized line, and treat the =item * as a bulleted list instead of a text paragraph? I believe that it should treat it as the former because the bold line is after the nested =open, but the test case for htmlview.pod disagrees -- it treats it as the latter. I agree with you. Best, David
AW: Z in =item
Right - some POD formatters use heuristics like /^\d+/ on what follows =item to detect whether this is a numbered list. In the specific case of HTML output, you have 2 choices: 1. always use the full text behind =item and generate a definition list (dl,dt,dd), except with =item * which should result in a ul 2. or check for ^=item\s+(\d+)\.?$, verify that $1 equals 1,2,3... in sequence, and if so, generate a ol. If not, fall back to dl. Note that li allows a value=... attribute, which is however deprecated. See http://www.w3.org/TR/html4/struct/lists.html#edef-OL To keep things simple, my personal vote goes to 1. HTH, Marek -Ursprüngliche Nachricht- Von: Karl Williamson [mailto:pub...@khwilliamson.com] Gesendet: Sonntag, 26. Juni 2011 05:53 An: pod-people@perl.org Betreff: Z in =item In perldiag.pod, there is a line like this =item Z500 Server error All the other items form a definition list. My guess is that this is to make sure that the 500 isn't mistaken for a numbered =item in the list. However, with html, anyway, I don't see any difference in the output with and without the Z, and podchecker ignores the Z and says that the list has mismatched item types. Can someone explain?
AW: Pod::Html's cross referencing of C links
Hi Marc, IIRC C stands for code, which means for renderers to set the included ext in a fixed-width font (courier-like). It is by no means a hyperlink. I know that some POD tools tried to apply some artificial intelligence to check whether text in B or C or I could be a reference to a manpage, a =headn section or an =item, but the results are often awkward. Therefore, if I may throw in my 2c, I suggest to stick with the perlpodspec definition: hyperlink destinations are the texts of =headn and =item (stripping all potentially included markup like C B I), and the only way to reference these is L/text or Lpage/text. Examples: Cgrep /string/ - this is just highlighting the text in typewriter font =item grep /string/ ð This is a hyperlink destination (and a list item, of course) =item Bgrep I/string ð This is basically the same hyperlink destination (same text content) L/grep /string/ - this is the hyperlink to the above item -Marek Von: Marc Green [mailto:pongu...@gmail.com] Gesendet: Samstag, 21. Mai 2011 19:55 An: Karl Williamson Cc: pod-people@perl.org; tchr...@perl.com Betreff: Re: Pod::Html's cross referencing of C links On Sat, May 21, 2011 at 10:54 AM, Karl Williamson pub...@khwilliamson.com wrote: Perhaps what is meant in the comments is that you can't use L to link to most =item's. If you need to refer to one, perhaps you should use C markup to distinguish it from regular text. But the C would be a verbal reference and not a clickable link. Ah, I think you are right. Thanks for clarifying. I don't know when the specification changed, but after another read of the current perlpodspec http://perldoc.perl.org/perlpodspec.html#About-L%3C...%3E-Codes , I have an answer: Previous versions of perlpod distinguished Lname/section links from Lname/item links (and their targets). These have been merged syntactically and semantically in the current specification, and section can refer either to a =headn Heading Content command or to a =item Item Content command. Well, it is not an answer to my original question, but it helps me make the executive decision to consider C links as L links. Thanks for the help, Marc
AW: Why does Pod::Checker deprecate section numbers in links to man pages?
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 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? That said, I might consider a new release, if anyone would dare to condense this thread into either a patch, or a concise spec of what precisely is expected to be result of an update. Thanks a lot, Marek -Ursprüngliche Nachricht- Von: karl williamson [mailto:pub...@khwilliamson.com] Gesendet: Dienstag, 1. Juni 2010 20:34 An: karl williamson; Russ Allbery; pod-people@perl.org Betreff: Re: Why does Pod::Checker deprecate section numbers in links to man pages? Nicholas Clark wrote: 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 FWIW, I submitted a bug report for this module on an unrelated issue a month ago, and about the same time sent an email directly to Marek about a p5p discussion, and have gotten no responses.
AW: allowing Ltext|href
My 2c: allow Ltext|URL in future POD. Rendering depends on the Output formatter, there are IMHO two options: 1. (preferred) render as clickable hyperlink to URL, showing text (only) 2. render as text (URL) for text outputs. Can URI be used to safely detect whether URL is an absolute URL? HTH, Marek -Ursprüngliche Nachricht- Von: David E. Wheeler [mailto:da...@kineticode.com] Gesendet: Montag, 28. Dezember 2009 02:09 An: pod-people@perl.org Betreff: Re: allowing Ltext|href Anyone else got any opinions on this? I'd love to see a new version of Test::Pod with this update Thanks, David
AW: Clarification of markup within a link
Dear all, when writing Marek::Pod::HTML I saw any combinations of markup in =headN and =item, and also any kind of markup in L... (with and without |, i.e. alternative text). This made me implement the link-resolving part of the formatter like this: Both on the source and the destination side, strip all markup and reduce the link relationship to pure text (this includes expanding E... to Latin-1) - then most of the hyperlinks can be established correctly. I see no point in making a difference between L/Bsome section and L/some section, for example - especially when linking to other POD files - you never know if that document's author will not change the formatting... -Marek -Ursprüngliche Nachricht- Von: Sean M. Burke [mailto:[EMAIL PROTECTED] Gesendet: Freitag, 30. Mai 2003 23:00 An: Ronald J Kimball; [EMAIL PROTECTED] Betreff: Re: Clarification of markup within a link At 11:34 AM 2003-05-30 -0400, Ronald J Kimball quoted Perlpodspec: For L... codes without a name| part, only E... and Z codes may occur -- no other formatting codes. That is, authors should not use LBFoo::Bar. Yes, I wrote this too narrowly -- I said For L... codes without a name| part but I meant For Lurl codes and LSome::Module codes (without a name| part) That note is basically a reaction to Pod::Tree's bad idea that LCFoo::Bar should mean LCFoo::Bar|Foo::Bar. (Is LBFoo::Bar legal if it's a link to =head1 BFoo::Bar?) Now that you meantion it, yes it is; I hadn't been considering the Lsection name syntax (instead of L/section name or L/section name or Lsection name). -- Sean M. Burkehttp://search.cpan.org/~sburke/
RE: Not OK 18224 (Was: Changes of lib/Pod/*.pm in perl-5.8.0)
Dear all, it is correct that Pod::Text should be used whenever there is Pod to be converted to ASCII/Latin-1/... :-) However Pod::PlainText is part of the Pod::Parser distribution right from the start (AFAIK), so I'd hesitate to drop it. On the other hand it is true that it is used for the tests of Pod::Parser, as Pod::Text is NOT part of the Pod::Parser distribution. Within the Perl core, there is both Pod::Parser and Pod::Text, so it would be possible to test Pod::Parser together with Pod::Text - maybe by dropping the test of Pod::Parser with Pod::Plaintext and ONLY testing Pod::Text with the tests that come with the podlators distribution. WDYT? -Marek -Original Message- From: Russ Allbery [mailto:[EMAIL PROTECTED]] Brad Appleton [EMAIL PROTECTED] writes: Pod::PlainText can go away to my knowledge. It was created long ago *before* Pod::Text had been converted to use Pod::Parser (and Pod::Usage needed to use Pod::PlainText). Now that Pod::Text uses Pod::Parser, as long as Pod::Usage still works correctly, Pod::PlainText would now be redundant (at least I think so) Pod::Text should work correctly with Pod::Usage; I tested that a while back. I'd convert the tests to use Pod::Text (which may require a bit of fiddling with the expected output, since Pod::Text has gone through more tuning).
RE: Changes of lib/Pod/*.pm in perl-5.8.0
Hello Hugo,
please find answers in the text below.
Cheers,
Marek
-Original Message-
From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED]]
I had a go at integrating this into the core, but ran across some
test failures.
First, the core version of t/pod/find.t is substantially different
from the one in the distribution. That's kinda understandable, since
the one in the distribution thinks it knows all the files it should
find in ../lib, but the core version is also doing some strange
things; I don't understand this comment or code at all:
# The ../../../../../lib is for finding lib/utf8.pm
# when running under all-utf8 settings (pod/find.t)
# does not directly require lib/utf8.pm but regular
# expressions will need that.
@INC = qw(../lib ../../../../../lib);
I think in an ideal world the test in the distribution would work
a bit better in isolation (perhaps by generating its own test files,
or something), and if necessary check whether it is running as part
of the core or standalone by checking $ENV{PERL_CORE}. However the
current core version still passes all tests even with the latest code,
and we could just leave it there for now if this isn't an easy fix.
Hmmm, never saw that one. Do I get it right that this is for
TESTING Pod/* WITHIN the Perl core? If so, the setting above
in the *.t test script seems ok for me. The *.pm shouldn't
contain such code.
For the next update I can include sth. like
if($ENV{PERL_CORE}) {
@INC = (@INC, qw(../lib ../../../../../lib);
}
to t/pod/find.t - would that be ok? Are there other things that
should be included in the distribution t/pod/find.t? I don't
mind encapsulating all of them in if-PERL_CORE clauses.
Maybe will have a look at the Perl core myself, if time permits.
The other test failures are in lib/Pod/t/*:
crypt.org% ( cd t ; ./perl harness ../lib/Pod/t/{latex,utils}.t )
../lib/Pod/t/latexNOK 76# Test 76 got: 'Standard link:
\emph{Pod::LaTeX}.
' (../lib/Pod/t/latex.t at line 63 fail #73)
#Expected: 'Standard link: the \emph{Pod::LaTeX} manpage.
'
# ../lib/Pod/t/latex.t line 63 is: ok($output$i, $reference$i);
../lib/Pod/t/latexNOK 80# Test 80 got: 'Now refer to an
external section: \textsf{sec} in \emph{Pod::LaTeX}
' (../lib/Pod/t/latex.t at line 63 fail #77)
#Expected: 'Now refer to an external section: the section
on \textsf{sec} in the \emph{Pod::LaTeX} manpage
'
../lib/Pod/t/latexFAILED tests 76, 80
Failed 2/154 tests, 98.70% okay
../lib/Pod/t/utils# Test 2 got: 'Pname'
(../lib/Pod/t/utils.t at line 46)
# Expected: 'the Pname manpage'
# ../lib/Pod/t/utils.t line 46 is: ok($link-markup, $results$i);
# Test 3 got: 'Qident in Pname' (../lib/Pod/t/utils.t at
line 46 fail #2)
# Expected: 'the Qident entry in the Pname manpage'
# Test 4 got: 'Qsec in Pname' (../lib/Pod/t/utils.t at
line 46 fail #3)
# Expected: 'the section on Qsec in the Pname manpage'
# Test 5 got: 'Qsec' (../lib/Pod/t/utils.t at line 46 fail #4)
# Expected: 'the section on Qsec elsewhere in this document'
# Test 6 got: 'Qsec' (../lib/Pod/t/utils.t at line 46 fail #5)
# Expected: 'the section on Qsec elsewhere in this document'
../lib/Pod/t/utilsFAILED tests 2-6
Failed 5/22 tests, 77.27% okay
Failed Test Stat Wstat Total Fail Failed List of Failed
--
-
../lib/Pod/t/latex.t 1542 1.30% 76 80
../lib/Pod/t/utils.t 225 22.73% 2-6
Failed 2/2 test scripts, 0.00% okay. 7/176 subtests failed,
96.02% okay.
crypt.org%
.. and I'm not sure whether we should just change the tests,
or whether
they have a right to expect the text they did.
All of these are ok - the test references should be updated accordingly.
This is because of the new perlpodspec: POD links like
LPod::Find/SYNOPSIS should be expanded to
SYNOPSIS in Pod::Find
as in is quite understandable in many (western) languages. The
prior expansion adds too much english text.
Cheers,
Marek
RE: pod2ps
My Marek::Pod::HTML has also a ps output option, which - you guessed it - uses HTML::FormatPS -Marek -Original Message- From: Sean M. Burke [mailto:[EMAIL PROTECTED]] Sent: Wednesday, November 20, 2002 10:02 AM To: [EMAIL PROTECTED] Subject: pod2ps Does anyone have a favorite Pod-to-Postscript formatter?
RE: PodParser patch for prehistoric perl
Hi Ed, I tried getting the latest File::Spec on CPAN, but it didn't have the necessary methods. IIRC. It looks like newer File::Specs are bundled with perl but not available on CPAN. thanks for pointing this out. I filed a request to update File::Spec on CPAN, see https://rt.cpan.org/NoAuth/Bug.html?id=1799 IMHO, this illness should be cured, not the symptoms ;-) Cheers, Marek
Changes of lib/Pod/*.pm in perl-5.8.0
Dear Perl gurus, I noticed that some changes have been done to e.g. lib/Pod/Checker.pm in the perl-5.8.0 distribution, relative to PodParser-1.18 on CPAN. Who did these changes? There is one that seems to me rather arbitrary and IMHO requires a clarification: collapsing newlines to blanks in L: This was a warning and was removed - IMHO it is not good style to have L... span more than one line. What do you think? My goal is to merge these changes (and some additional minor ones) into a PodParser-1.20 package on CPAN, which then can be included in the next perl-X.Y.Z core distribution as well. Ok? Best regards, Marek
Re: a pod2xml as canonical pod parser
Hello Sean and *,
you may want to hava a look at Pod::Compiler. It basically does what you
have in mind, altough the tree it creates is not XML but a set of Pod::*
objects defined in Pod::objects. But this could be changed quite easily
(...if I had enough time for that, sorry to say so). But perhaps someone
could pick up what I started there? Or at least reuse some of the code by
cutpaste.
I have some doubts whether the approach I have taken (i.e. to have a
separate object type for each possible Pod construct) was the most
appropriate. I can very well imagine to have a uniform type of container
object (i.e. a XML tag), and define the actions dependent on the tag
type. Not much of a difference in fact. The idea why I chose the other way
was to have the ability to write
$obj-some_method();
any time and have the OO mechanism chose the right code rather than
if($obj-type() eq '...') {
$obj-some_method();
}
But that's mainly cosmetics.
The next major issue however is to decide whether this compiler/tree
builder should use Pod::Parser or have its own Pod parsing frontend for
performance reasons. I don't know.
Cheers,
Marek
SMBThe solution that most appeals to me currently, is to make this
SMBhypothetical module take Pod as input, and spit out XML as output, which
SMBthe author of a Pod processor would then direct to whatever Pod parser he
SMBprefers. This obviates most of the above-mentioned problems.
Re: Pod::InputObjects / Pod::ParseTree
I'm finally starting to implement this in Pod::Man and Pod::Text, and here are the nits that I've found so far in perlpodspec. Note that EEltnumber Imust not be interpreted as simply codepoint Inumber in the current/native character set. It always means only the character represented by codepoint Inumber in Unicode. (This is identical to the semantics of #Inumber; in XML.) This will likely require many formatters to have tables mapping from treatable Unicode codepoints (such as the \xE9 for the e-acute character) to the escape sequences or codes necessary for conveying such sequences in the target output format. A converter to *roff would, for example know that \xE9 (whether conveyed literally, or via a EElt... sequence) is to be conveyed as e\\*'. \\*' is an escape defined by the prelude created by Pod::Man; it's not a general nroff thing. It is defined as: ..ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h|\\n:u and the accent is dropped in nroff mode. Less than ideal. With groff, it's probably okay to just leave the literal ISO 8859-1 character, but that isn't portable and will cause some nroff implementations to segfault. =head1 About LElt...Egt Codes As you can tell from a glance at Lperlpod|perlpod, the LElt... code is the most complex of the Pod formatting codes. The points below will hopefully clarify what it means and how processors should deal with it. It would be good to include more of the technical syntax in here. For example, how should the following be parsed? LParsing and/or Formatting LParsing/Formatting LFun Times/Summer Vacation L Time::HiRes L perlfunc / $. L perlfunc / $. L perlpodspec / About LElt...Egt Codes What I'm currently implementing retains the behavior of stripping off surrounding double-quotes from the section, as well as leading or trailing whitespace inside or outside the double-quotes. It also interprets L entries that are fully contained in double-quotes as links to sections for backward compatibility, not just looking at internal whitespace. I'm implementing a parser that breaks down link text into the five items described here and will include it in the next release of podlators. (Called Pod::ParseLink.) Pod processors must now treat text|-less links as follows: Lname = Lname|name L/section = Lsection|/section Lname/section = Lsection in name|name/section This and some of the other text there outlaws rendering: Lhttp://www.eyrie.org/~eagle/ as: http://www.eyrie.org/~eagle/ but instead requires that there be nothing distinguishing the URL from the surrounding text for output formats that can't do hypertext or don't want to use a different font. Was that intentional? I think I'd rather surround it with angle brackets for Pod::Text and Pod::Man. Authors wanting to link to a particular (absolute) URL, must do so only with LEltscheme:... codes (like LElthttp://www.perl.org), and must not attempt LEltSome Site Name|scheme:... codes. This restriction avoids many problems in parsing and rendering LElt... codes. This is rather unfortunate, and I don't recall the reason for it. Can't we just say that no unescaped | is permitted in L and then allow anchor text to be specified for regular URLs? It would be a bit trickier to deal with this for text renderings, but something like: LAnchor Text|http://www.perl.com/ = Anchor Text http://www.perl.com/ for formats that don't support hyperlinks might work. Previous versions of perlpod allowed for a CLEltsectionEgt syntax (as in CLEltObject AttributesEgt), which was not easily distinguishable from CLEltnameEgt syntax. This syntax is no longer in the specification, and has been replaced by the CLEltsectionEgt syntax (where the quotes were formerly optional). Pod parsers should tolerate the CLEltsectionEgt syntax, for a while at least. The suggested heuristic for distinguishing CLEltsectionEgt from CLEltnameEgt is that if it contains any whitespace, it's a Isection. Pod processors may warn about this being deprecated syntax. This is where to say something about LParsing/Formatting if we want to. Authors of Pod formatters are reminded that =over ... =back may map to several different constructs in your output format. For example, in converting Pod to (X)HTML, it can map to any of ul.../ul, ol.../ol, dl.../dl, or blockquote.../blockquote. Hm. The blockquote stuff is new, but makes sense. *time passes* Wow, that was a mess to implement in *roff. Gah. Pod formatters Imust tolerate arbitrarily large amounts of text in the =item Itext... paragraph. I think this is the wrong approach. Why? But they may be arbitrarily long: =item For transporting us beyond seas to be tried for pretended offenses =item He is at this time transporting large armies of foreign mercenaries to complete the works of death, desolation and tyranny, already begun with circumstances
Re: pod2xml/xml2pod (Pod::PXML)
Sean, I like the idea. However it seems to me that we both did up to 70% of the same work - i.e. parsing POD and turning it into a more structured representation. See Pod::Compiler for what I did on this subject. Attaching a XML backend to it should be a matter of one day max. I guess that you first build up an internal object-based XML representation and then write the code. Is the module suited for just reading POD and returning the internal representation? Then I can just throw away Pod::Compiler after checking whether there is something to be merged into Pod::PXML. Do you print any errors in the POD syntax? Checking whether internal L's are valid? Cheers, Marek On Tue, 17 Apr 2001, Sean M. Burke wrote: SMBI've been working like a madman for the past few days, coming up with SMBa pod2xml and matching xml2pod. (Why? Because it's not there.) SMB SMBThe idea of these xml2pod/pod2xml (both wrapped up in a not-yet-released SMBPod::PXML) is to freely go between a conventional POD document and an XML SMBrepresentation of it -- write in whichever you want, convert to whichever SMByou need. SMBI came up with a DTD for the XML doctype I had in mind, and then wrote SMBthe pod2xml and xml2pod to work for that doctype. SMB SMB(This whole endeavor, BTW, is unrelated to Matt Sergeant's Pod::XML SMBmodule.) SMB SMBThe pod2xml and xml2pod that I've come up with seem to work. SMBI'm as surprised as anyone else. SMB SMBI've been testing them on various POD files to be found in the Perl dist SMBand elsewhere. I convert each POD document to XML, check it the XML the SMBDTD I wrote, convert that XML to POD, and then diff that against the SMBoriginal POD. So far the XML validates, and diffing the original pod SMBagainst the round-tripped pod is showing only representational SMBdifferences, like between these two: SMB SMB C (?...) SMB C(?Egt...) SMB SMBwhich both equally well represent the text "(?...)" in code style. SMB SMBI've attached the DTD below, and I'd be happy to hear your reactions, SMBbefore I go releasing Pod::PXML in a few days. SMBAnd after the DTD, I've included a sample file, the result of SMBfeeding strict.pm thru my pod2xml. SMB SMB SMBOne point on which I'm a bit unsure is whether I'm right in forbidding SMB"head1"..."head4" elements as children of "list" elements. I've found SMBa cases of head1 under list elements, but all but one or two of them SMBare pretty clearly typos. SMB SMBAlso, the treatment of L... elements is a bit strange, basically SMBbecause the interpretation of bar in Lfoo|bar is a mess, itself. SMBI've tried to make the XML representation no crazier than the Perl SMBrepresentation, and to allow for flawless roundtripping. SMB SMB SMB=== SMB SMBDRAFT EXPERIMENTAL DTD: SMB SMB!-- It so happens that all the content-models came out SMB as either (#PCDATA), (#PCDATA | foo | bar)*, or SMB (foo | bar)*. That makes validation simple. SMB-- SMB SMB!ELEMENT pod (head1|head2|head3|head4|p|pre|list|for|cmd)* SMB!ATTLIST pod SMB xmlns CDATA #FIXED 'http://www.perl.com/CPAN/authors/id/S/SB/SBURKE/pxml_0.01.dtd' SMB SMB SMB!ENTITY % Style " b | i | c | x | f | s | link " SMB SMB!-- BLOCK-LEVEL ELEMENTS -- SMB SMB!ELEMENT head1 (#PCDATA | %Style; )* SMB!ELEMENT head2 (#PCDATA | %Style; )* SMB!ELEMENT head3 (#PCDATA | %Style; )* SMB!ELEMENT head4 (#PCDATA | %Style; )* SMB!ELEMENT p (#PCDATA | %Style; )* !-- a normal paragraph -- SMB SMB!ELEMENT pre (#PCDATA) !-- a verbatim/preformatted paragraph -- SMB!ATTLIST pre xml:space (preserve) #FIXED 'preserve' SMB SMB!ELEMENT list (item|p|pre|list|for|cmd)* !-- "=over ...stuff... =back" -- SMB!ATTLIST list indent CDATA #IMPLIED !-- where you put the 8 in "over 8" -- SMB!-- sound advice: have at least one p, pre, or item per list -- SMB!-- sane advice: if the first thing in the list in a p, don't have items -- SMB SMB!ELEMENT item (#PCDATA | %Style;)* !-- "=item ...label..." -- SMB SMB!ELEMENT for (#PCDATA) !-- I guess? -- SMB!ATTLIST for target CDATA #IMPLIED SMB !-- where you put the thing in "=begin thing" -- SMB SMB!-- Hm, maybe I should delete this element... -- SMB!ELEMENT cmd (#PCDATA) !-- I guess? -- SMB!ATTLIST cmd cname CDATA #IMPLIED SMB !-- where you put the thing in "=thing" -- SMB SMB!-- STYLE ELEMENTS -- SMB SMB!ELEMENT link (#PCDATA | %Style;)* SMB!ATTLIST link SMB xrefCDATA #REQUIRED SMB!-- SMB Yes, every link element MUST have an xref attribute. SMB xref="HTML::Tree" SMB xref="HTML::Tree/That Item" SMB xref="HTML::Tree/quot;That Sectionfquot;" SMB xref="chmod(3)/That Item" SMB xref="/quot;That Section In This Documentquot;" SMB See perlpod for an explanation of these designators. SMB Note that what perlpod says goes before the | in an L...|designator SMB actually is, in PXML, the content of the link element, not an attribute. SMB So this is quite wrong: link xref="foo|bar".../link SMB Instead have:
Re: questions about pod2html
Hello, you may want to give the extenstion MarekPodHtml-0.43.tar.gz a try. It is more robust than the "old" pod2html. Be sure to specify all files to convert on the command line (see the manpage), otherwise the links are not active. Cheers, Marek On Tue, 3 Apr 2001 [EMAIL PROTECTED] wrote: I am using "pod2html" to generate the html documentation directly from the perl scripts. And I'd like to link the html files together, but I couldn't succeed. Here is the commands that I used in Unix: pod2html --htmlroot=/data/html --infile=a.pm --outfile=/data/html/a.html pod2html --htmlroot=/data/html --infile=b.pm --outfile=/data/html/b.html pod2html --htmlroot=/data/html --infile=c.pm --outfile=/data/html/c.html I tried to use "Lb" or "Lc" tags in the a.pm in order to generate a link to b.html or c.html, but failed. Does that indicate "L" tags are only used for cross reference to manpages? If so, is there anyway to cross referece to other html files in POD section? And when I used the above commands, besides the html files that were generated, there are two other files: "pod2htmd.x~~ and "pod2htmi.x~~ generated as well. What are those files for? Thanks in advance, Joan Huang
Pod-Compiler-0.10
Dear all, after fiddling with details for a long time, I'm now confident enough to upload Pod-Compiler-0.10.tar.gz to CPAN. Should reach your favorite mirror soon. What is it? This package, based on Pod::Parser and Tree::DAG_Node compiles a POD document into an object tree, printing (or not) many diagnostic messages in case the input is malformed. There are many convenient methods to handle the result, for example for converting it to different output formats. There are even some *::collection objects that define useful methods for a bunch of e.g. Pod nodes (=hyperlink destinations) and entire documents. There is an interface to Storable to conveniently store and retrieve the object tree. See the POD in Pod::Compiler for more details. There is a sample application included, podlint. As its name suggests, it beautifies existing POD documents and cleans up most errors (hopefully). My next plans are to bugfix this package and in parallel build a Pod-FrameMaker converter. My existing Marek::Pod::HTML will be updated to use this package as well. I know that Pod::Tree is very similar to this one, but I believe that reusing Pod::Parser and Tree::DAG_Node is a major advantage over the standalone Pod::Tree. Feel free to testdrive the package (I've tested it only on Solaris/Sparc and Linux, with Perl 5.005.03 and 5.6.0 so far) and send comments. Hope you'll find it useful! All the best, Marek
Re: http:// in L
On Fri, 1 Sep 2000, Tom Christiansen wrote: TCYou should write your pod as close to plain text as you possible TCcan, with as few explicit markups as you can get away with. It TCis up to the individual conversion to decide how things in your TCtext should be represented. That means letting the translator TCfigure out how to create paired quotes, how to fill and adjust TCtext, how to find a smaller font for words in all capitals, TCetc. Since these were written to process Perl documentation, TCmost translatorsfootnoteIf you're designing a general-purpose TCpod translator, not one for Perl code, your criteria may TCvary./footnote should also recognize unadorned items like TCthese and render them appropriately: I'd like to add my 2c: IMHO POD translators should be capable of translating all kinds of POD, perhaps having an option to turn Perl specific features (e.g. highlighting $_) on/off. Concerning auto-detection of special constructs: When converting Perl documentation, @ preceded by non-word- and followed by word-characters (or $ and word characters ;-) is very likely an array; it might be something different in another context. I agree that Perl will be the context of POD documents in 90%+ of all cases, but anyway I find it extremely annoying if a converter tries to use "artificial intelligence" to figure out proper highlighting/markup - and fails! I'd prefer to have the documentation's author provide a very small amount of markup to disambiguate e.g. an URL: Let him say Lhttp://www.perl.org and it is crystal-clear what is meant. Yes, I propose a corresponding extension of perlpod. In other words: I'm against too much black magic in POD; if there is supposed to be any, it should be well described in perlpod, e.g. that "sleep(1)" is a link to a manpage and not an example of usage of a Perl built-in command. -Marek
Re: [p5pod] [ANNOUNCE] Pod::StdParser, Pod::Tests proof of concept
On Tue, 5 Sep 2000, Barrie Slaymaker wrote:
BSBrad Appleton wrote:
BS
BS Marek has been doing similar work on an experimental
BS Pod::Compiler module that sounds suspiciously like your
BS Pod::StdParser. Definitely make sure you look at each
BS other's code before going too much further.
BS
BSI haven't seen it published anywhere, but his previous description sounds very much
BSDOMish. This isn't DOMish: it doesn't build a tree of objects, it is a lot like
BSPod::Parser in that it generates events during parsing and provides an OO
scaffolding
BSfor handling those events (by overloading at this time, perhaps by callback later).
I see your point, but if you think of complex converters like HTML,
FrameMaker (MIF) or LaTeX, then it is *extremely* handy to have a tree of
objects, so you always have the full information about nesting, sisters
etc easily accessible. And for hyperlinking you need two passes anyway,
and thanks to Storable you can conveniently store the whole tree and run
the second pass over it as soon as all hyperlink destinations have been
computed. I don't want to go into the details, but I have certainly a lot
of pros for an OO approach.
I haven't coded Pod::Compiler into my Marek::Pod::HTML yet, but I expect a
dramatic increase in performance when converting e.g. the whole Perl
distribution PODs.
There are two differing requirements here: On the one hand, we need a
fast! parser for online viewing, on the other a base framework for complex
converters to avoid coding the same all over again.
BSIf Marek will point me to his code, I'll gladly peruse it.
I've included my 0.01 of Pod::Compiler and a sample script (sorry, no
module package) for you to have a look at. Yes, there are a lot of
TODOs.
BSDo you have any feedback on Pod::StdParser Pod::Tests in the meanwhile?
I've had a brief look: Yes, it is a sensible extension of Pod::Parser, but
it uses callbacks rather than creating a tree. The functionality of
Pod::StdParser could quite easily be included in Pod::Compiler, IMHO.
The big question is: Could the tree-approach satisfy all requirements or
do we need separate, highly optimized converters for every single output
format?
-Marek
#!/opt/perl_5.6.0/bin/perl -w
use strict;
use Marek::Pod::Compiler qw(pod_compile);
my $root = pod_compile(shift @ARGV, \*STDOUT);
$root-walk_down({ callback = \_disp, _depth = 0 });
my $file = "/tmp/pod$$";
print "storing to $file\n";
$root-store($file);
print "retrieving $file\n";
my $newroot = Pod::root-read($file);
print $newroot-as_pod,"\n";
print "\n\nNODES:\n";
my %nodes = $newroot-nodes();
foreach(keys %nodes) {
print " $_ $nodes{$_}\n";
}
sub _disp
{
my ($node,$href) = @_;
my $indent = ' ' x $href-{_depth};
print $indent,ref($node),"\n";
1;
}
# -*- perl -*-
#
# Pod/Compiler.pm -- compiles POD into an object tree
#
# Copyright (C) 2000 by Marek Rouchal. All rights reserved.
# This package is free software; you can redistribute it and/or modify
# it under the same terms as Perl itself.
#
package Marek::Pod::Compiler;
=head1 NAME
Marek::Pod::Compiler - compile POD into an object tree
=head1 SYNOPSIS
use Marek::Pod::Compiler;
=head1 DESCRIPTION
THIS IS PRELIMINARY SOFTWARE! The Marek:: namespace is strictly
preliminary until a regular place in CPAN is found.
=cut
use strict;
require Exporter;
require Pod::Parser;
require Tree::DAG_Node;
#$Tree::DAG_Node::Debug = 1;
require Storable;
$Marek::Pod::Compiler::VERSION = '0.01';
@Marek::Pod::Compiler::ISA = qw(Exporter Pod::Parser);
@Marek::Pod::Compiler::EXPORT = qw();
@Marek::Pod::Compiler::EXPORT_OK = qw(pod_compile);
##
sub pod_compile
{
my ($infile) = @_;
my $compiler = Marek::Pod::Compiler-new();
$compiler-parse_from_file($infile,\*STDOUT);
$compiler-root();
}
##---
## Method definitions begin here
##---
# set up a new object
sub new {
my $this = shift;
my $class = ref($this) || $this;
my %params = @_;
my $self = {%params};
bless $self, $class;
$self-initialize();
return $self;
}
# initalize, set defaults
sub initialize {
my $self = shift;
## Options
# the POD name
$self-{name} ||= '';
# no parser errors here, we've seen them in the first pass
$self-SUPER::errorsub(sub { return 1; });
}
=item name()
Set/retrieve the C-name property, i.e. the canonical Pod name
(e.g. CPod::HTML).
=cut
# set and/or retrieve canonical name of POD
sub name
{
return (@_ 1) ? ($_[0]-{name} = $_[1]) : $_[
Re: podlators 1.03 released
On 3 Sep 2000, Russ Allbery wrote: RA * lib/Pod/Text.pm: Add sol and verbar to the escapes. RA * lib/Pod/Man.pm: Likewise. RA * lib/Pod/Man.pm (cmd_item): Fix the regex for stripping bullets RA from index entries so that it doesn't strip a leading 'o'. Dear all, I'd like to abuse this opportunity for advertising a general Pod::Compiler. The items listed above are dealt with in my (new) Pod::HTML as well, which IMHO suggests that this should be done in a central place. I'll keep you up to date on my tries to come up with such a generic compiler that generates an object tree that can be conveniently processed into any output format. It will be based on the current Pod::Parser. All the best, Marek
Re: [p5pod] [RFC ??, v1] =also for|begin|end POD commands
On Thu, 3 Aug 2000, Brad Appleton wrote: BABesides, I think there is still need for a Pod::Translator BAof Pod::Compiler module that uses (or is subclassed from) BAPod::Parser to be the *real* base parser that people use (the BAone that actually knows the commands, just not necessarily BAthe output format). I think putting =also in this new module BAinstead would be a much needed first step to making a much BAmore useful Pod2Xxxx base module that safely assumes it is BAused exclusively for translating perlpod-compatible commands BAinto some output format (unlike Pod::Parser which simply parses BAinto commands and paragraphs and prase-trees without knowledge BAof the meaning of them). I'd like to assent to this idea. While coding a new POD to HTML converter (MarekPodHtml-0.41) and starting with POD to MIF (FrameMaker), I found that much of the code is reusable. An ideal Pod::Compiler would - very much like the existing Pod::Checker - extract node (=head, =item, X...) information from a given POD that serve as link destinations. A Pod::Translator would read a POD and build an object tree. By making use of Perl OO features the individual objects (Pod::head, Pod::list (with Pod::item kids), Pod::paragraph, Pod::verbatim etc.) would only need an appropriate "translate" method that would be filled with the guts of the destination format. Every object would also have an "as_pod" method for re-constructing POD format and an "as_text" method for rendering its contents in plain text (important for links, TOC, index). There is a Pod::Tree module out there that might serve as a basis for this. Coding this would also include rewriting the perlpod manpage. I certainly would like to volunteer for coding such modules, but I have no idea when there'll be time for this. My 2c... -Marek
POD to HTML
Dear all, today I've uploaded MarekPodHtml-0.41.tar.gz to CPAN. This is an update of 0.40 that fixes a bug that the conversion ran into when converting all of the Perl PODs locally installed as suggested by me earlier. What is this all about? I think the existing pod2html is broken. I wanted to come up with a mostly compatible, but much more strict and precise converter based on existing POD filters and HTML utility modules. I'd like to suggest this module as a replacement for the existing pod2html. Why the strange name? Andreas Koenig suggested that I should use a "private" namespace in order to not pollute the existing ones. As soon as agreement is reached to use this module, the Marek:: namespace would be dropped. So what? I'd like to ask you to have a look at this module, test it (try "make test_full" after "make test" and look in the generated html/ directory) and send me your comments. Please note the TODO file that probably already lists some suggestions that you may come up with. This module should be pretty portable (tested on Linux, Solaris and Win32) and stable. CPAN path: http://www.perl.com/CPAN-local//modules/by-authors/id/M/MA/MAREKR/ All the best, Marek
