Re: POD troubles
by LanX (Saint) on May 14, 2011 at 08:21 UTC
|
I dont fully understand your description (an example would be fine)... but
> I had some spaces on the line before the =head1 in question.
please be aware that POD cares about indentation to distinguish paragraphs, in other words only completely empty lines separate them.
Thats especially helpful when having code-blocks with empty lines
print 1;
print 3;
since the second line is not empty this code belongs to one code paragraph!
BTW: The default setting of cperl-mode is very helpful, it shows trailing spaces as "_" in emacs. (I've set it up to be a whitespace again, but with grey background color, to avoid confusion with underscore)
UPDATE:
Some older Pod translators require paragraphs (including command paragraphs like "=head2 Functions") to be separated by completely empty lines. If you have an apparently empty line with some spaces on it, this might not count as a separator for those translators, and that could cause odd formatting.
Simply searching perlpod for the word "empty" will show you more detailed information and should answer your questions.
| [reply] [Watch: Dir/Any] [d/l] |
|
…
return $foo;
}
␢
␢
=head1
…
Because my lame editor insists on tracking the indenting of the previous line with actual content, I got blank lines with leading spaces. I corrected the extra space when I got to the =head1 line, but didn't notice them above.
Now it seems that the POD-coverage tester didn't notice anything amiss, though I turned it off after stubbing out the API because I didn't want it complaining about all the internal stuff. But I'm pretty sure the blanks would have been there from the getgo and not added later.
The test directory generated by module-simple includes Test::Pod, and it passes too. I would think this is exactly the kind of thing it should warn about‽
After reading the passage you reference, I conclude that I must have one of “those” older translators, and that the POD checkers are not using the same parser library.
Re emacs: I downloaded it for Windows, and gave it a spin, but it is far too alien to get started. Just selecting text or mousing the borders is all wrong, in the sense of not following the platform conventions or any modern GUI conventions. Is there a GUI-based version of emacs that might be more approachable (as opposed to just running classic mode in a window)?
| [reply] [Watch: Dir/Any] |
|
> Re emacs: I downloaded it for Windows, and gave it a spin, but it is far too alien to get started. Just selecting text or mousing the borders is all wrong, in the sense of not following the platform conventions or any modern GUI conventions. Is there a GUI-based version of emacs that might be more approachable (as opposed to just running classic mode in a window)?
I'm not advocating emacs, it's just the editor I know the best.
I don't know what "mousing the borders" mean and why you are running emacs in a console.
I would use EmacsW32 or an Xemacs (which cares more about mainstream conventions).
Keep in mind emacs is far older than Perl and has to care much more about backwards compatibility while allowing new fashions. OTOH many GUI conventions were invented for emacs.
But you can still "customize" many things per menu, like cut&past with C-x,C-v,C-z and context menue on right click and opening help screens in separate windows.
In general if you don't like emacs let it be. Komodo and Padre are already very mainstream.
| [reply] [Watch: Dir/Any] |
|
|
Simply searching perlpod for the word "empty" will show you more detailed information and should answer your questions.
Actually, no. The body of the doc indicates that pod paragraphs of all kinds are terminated by a blank line, but it doesn't say that you need a blank line before one in embedded POD. The end of the page does show the bit about "some older translators", but the first example that is implied to work on current translators shows =head paragraphs immediately after "plain" paragraph text (Correction: it's actually an =end, not a =head, but I meant to say "some command paragraph" and didn't recall which exactly), which contradicts the bulk of the documentation. Presumably the bulk of the document was not updated with new rules, when this example was tacked on to the end.
Other than passing reference in that appendix about apparently blank lines, it never states what a "blank line" is.
Searching through module versions and stuff on CPAN Search, it seems that pod2html is "core", so I don't know why I have "some old version". I don't know why the various POD checking doesn't report this as a problem.
It appears that I need an empty (not "blank"!) line in the host file before the embedded POD directive, and that a "command" paragraph (like =cut) cannot be run up against a "plain" paragraph. This is indicative of "some old parsers". But it's the one that matches the version of the documentation that makes that claim, isn't it?
| [reply] [Watch: Dir/Any] |
|
| [reply] [Watch: Dir/Any] |
|
|
|
Re: POD troubles
by Anonymous Monk on May 14, 2011 at 08:48 UTC
|
| [reply] [Watch: Dir/Any] |
|
Actually neither Test::Pod (calling all_pod_files_ok) nor Test::Pod::Coverage gave a peep about it.
| [reply] [Watch: Dir/Any] |
|
unless ( $ENV{AUTOMATED_TESTING} or $ENV{RELEASE_TESTING} ) {
plan( skip_all => "Author tests not required for installation" );
}
as per Test::XT - Best Practice for Author Tests | [reply] [Watch: Dir/Any] [d/l] [select] |
|