Beefy Boxes and Bandwidth Generously Provided by pair Networks
"be consistent"
 
PerlMonks  

Re: POD troubles

by LanX (Canon)
on May 14, 2011 at 08:21 UTC ( #904790=note: print w/ replies, xml ) Need Help??


in reply to POD troubles

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)

Cheers Rolf

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.


Comment on Re: POD troubles
Download Code
Re^2: POD troubles
by John M. Dlugosz (Monsignor) on May 14, 2011 at 09:56 UTC
    Something like:
    …
        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)?

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

      Cheers Rolf

        “EmacsW32 has the goal to make it easier for an MS Windows user to get used to Emacs ”

        Sounds like what I was looking for. thanks!

        Re Komodo: The free editor version was very disappointing. I'm not looking to spend what they are charging for the commercial IDE.

Re^2: POD troubles
by John M. Dlugosz (Monsignor) on May 14, 2011 at 10:26 UTC
    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?

      > but the first example that is implied to work on current translators shows =head paragraphs immediately after "plain" paragraph text, 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.

      could you please post this "wrong" example, I can't find it.

      Cheers Rolf

        OK, it states:


        • Many older Pod translators require the lines before every Pod command and after every Pod command (including "=cut"!) to be a blank line. Having something like this:
            # - - - - - - - - - - - -
            =item $firecracker->boom()
            This noisily detonates the firecracker object.
            =cut
            sub boom {
            ...
        
        ...will make such Pod translators completely fail to see the Pod block at all.


        So, "many older translators" don't like that, but current ones do? Otherwise why bother mentioning it?

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://904790]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others studying the Monastery: (6)
As of 2014-07-13 11:06 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    When choosing user names for websites, I prefer to use:








    Results (249 votes), past polls