http://www.perlmonks.org?node_id=904787

John M. Dlugosz has asked for the wisdom of the Perl Monks concerning the following question:

I found the problem, but I'm posing this anyway in case anyone else wants to commiserate.

I ran ./Build html, and found the html file it produced. From the .tmp files it left behind, I see it must be calling pod2html.

One of my =head1 sections is missing! I made sure it was not empty. I added a =cut and #comment to separate it from the following. I tried changing the name. Whatever I try, it just won't show up.

The boilerplate ones at the bottom of the file still show up. The one I created before this one looks fine. If I add another one before the one that is showing now, it shows up.

Why would some of my docs be AWOL? I looked at pod2html and there's nothing about looking only for certain headers to include. In any case, one I created (not part of the boiler plate) is showing.

The solution:

I had some spaces on the line before the =head1 in question.

Should pod2html and other tools be more forgiving? Should an apparently blank line be meaningful in an ACME::Bleach kind of way?

Replies are listed 'Best First'.
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)

    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.

      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

      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

Re: POD troubles
by Anonymous Monk on May 14, 2011 at 08:48 UTC
      Actually neither Test::Pod (calling all_pod_files_ok) nor Test::Pod::Coverage gave a peep about it.