Beefy Boxes and Bandwidth Generously Provided by pair Networks
Welcome to the Monastery

Embedding pod in C

by jpl (Monk)
on May 18, 2011 at 15:03 UTC ( #905489=perlquestion: print w/replies, xml ) Need Help??
jpl has asked for the wisdom of the Perl Monks concerning the following question:

Having just told relientmark not to worry about efficiency (Doing perl efficiently), I confess to resorting to embedding C code when performance really matters. I'd like to document the code with pod, but separating the pod from the code in a separate file is a recipe for having them drift out of sync. So I'd like to keep the pod as C comments, and run a script to split them out to generate pure pod. I thought there might be some common commenting convention that has already been adopted, but searches here and in CPAN and on google didn't turn anything up.

I could write plain old pod up against the left margin within a comment (and do something to prevent */ within it from terminating the comment), but not being able to indent the comments at the same level as the code is visually disruptive (aka ugly). I can invent my own conventions for introducing and terminating blocks of pod, but I'd prefer to use a "standard", if such a thing exists. Does it?

Replies are listed 'Best First'.
Re: Embedding pod in C
by John M. Dlugosz (Monsignor) on May 18, 2011 at 15:12 UTC
    Why separate it out? The POD tools should have no trouble finding =pod ... =end blocks within any kind of text file.

    To hide it from C, use #if 0 / #endif, not comments. Then you don't have to worry about any stray */ characters or C comments within the documentation.

    I understand your concern about indenting. Why are your functions indented in the file? Or do you mean you are putting POD within functions?

    Having a pre-indent for everything makes it harder to ensure that normal paragraphs are at the right level as distinct from verbatim paragraphs which are indented more than that pre-set. I think you are asking for trouble, unless you come up with a more comprehensive approach.

    If nobody has such a thing already, I suppose you will be designing it. I look forward to that thread!

      The #ifdef/#endif idea has some merit (although I vaguely recall some compilers grousing about stuff they found between the two, and it replaces the issue of being careful about */ with being careful about #endif). More to the point, pod is only recognized at the very start of a line. If I run pod2text on the following
      #ifdef pod =head2 title blah, blah, blah =cut #endif /* pod */
      I get nothing. And I don't want everything to have to start in column 0.
        And I don't want everything to have to start in column 0.
        Yeah, and I don't want POD to start with ^=. But no such luck. POD derivatives are defined to start at column 0. Period. Unless you write a preprocessor, and only after preprocessing your source you give it to a POD parser, there's no way around it. Surely, you don't want:
        .... some deeply indented, long line ending in: variable =function; /* Unlucky wrap */
        to be interpreted as POD, do you?
Re: Embedding pod in C
by LanX (Bishop) on May 18, 2011 at 15:39 UTC
    I'm not very proficient in C, but AFAIK it's common to use a preprocessor.

    Like this you can filter all POD out, which basically means cutting out paragraphs between lines starting with a "=". (Probably you can even delegate this to an existing Perl module)

    POD-Interpreters themselves normally don't care what kind of code you weave in.

    Cheers Rolf

      The C preprocessor can't be instructed to do anything of the sort. It uses lines starting with # and does a few simple things only.

        I hoped it's at least possible to define macros which translate =POD_COMMANDS to the start and end of multi-line comments.

        Cheers Rolf

Re: Embedding pod in C
by wazoox (Prior) on May 19, 2011 at 21:50 UTC
    Alternative: use ROBOdoc and generate pod using the included (may need customisation...) ROBOdoc2pod. ROBOdoc has the advantage of being more compact than POD, and doesn't bark when indented.

Log In?

What's my password?
Create A New User
Node Status?
node history
Node Type: perlquestion [id://905489]
Approved by Corion
Front-paged by Corion
and all is quiet...

How do I use this? | Other CB clients
Other Users?
Others scrutinizing the Monastery: (6)
As of 2018-06-23 02:48 GMT
Find Nodes?
    Voting Booth?
    Should cpanminus be part of the standard Perl release?

    Results (125 votes). Check out past polls.