Embedding pod in C

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

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!	[reply] [d/l]
Re^2: Embedding pod in C by jpl (Monk) on May 18, 2011 at 15:27 UTC
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 */` [download] I get nothing. And I don't want everything to have to start in column 0.	[reply] [d/l] [select]
Re^3: Embedding pod in C by JavaFan (Canon) on May 18, 2011 at 16:20 UTC
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 */` [download] to be interpreted as POD, do you?	[reply] [d/l] [select]
Re^4: Embedding pod in C by jpl (Monk) on May 18, 2011 at 17:13 UTC
Re^5: Embedding pod in C by John M. Dlugosz (Monsignor) on May 18, 2011 at 18:49 UTC
Re^4: Embedding pod in C by jpl (Monk) on May 18, 2011 at 17:25 UTC
Re: Embedding pod in C by LanX (Saint) 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	[reply]
Re^2: Embedding pod in C by John M. Dlugosz (Monsignor) on May 18, 2011 at 18:55 UTC
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.	[reply]
Re^3: Embedding pod in C by LanX (Saint) on May 18, 2011 at 20:03 UTC
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	[reply] [d/l]
Re^4: Embedding pod in C by John M. Dlugosz (Monsignor) on May 18, 2011 at 20:45 UTC
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.	[reply]


Perl-Sensitive Sunglasses
	PerlMonks