Beefy Boxes and Bandwidth Generously Provided by pair Networks
Keep It Simple, Stupid
 
PerlMonks  

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?

Comment on Embedding pod in C
Select or Download Code
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 (Canon) 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.
        OK.

        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?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: perlquestion [id://905489]
Approved by Corion
Front-paged by Corion
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others cooling their heels in the Monastery: (4)
As of 2014-12-20 11:52 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    Is guessing a good strategy for surviving in the IT business?





    Results (95 votes), past polls