Re^4: Embedding pod in C

John M. Dlugosz said

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!

I can't be much less comprehensive than I have been up to now. This seems as good a place as any to start the thread. Yes, I expect to use a preprocessor (of my own, nothing to do with C's) to extract the pod. Suppose we assume input of the form

    #ifdef pod
    (plain old pod here)
    #endif /* pod */
[download]

    /* pod first line of pod
    (plain old pod here)
    pod */
[download]

The latter has the advantage over #ifdef of allowing the first line of pod to share the line with the "pod opener", but I'm less pleased with the way it terminates the block. I'd like to hear opinions. In either case, we can easily identify the start and end of the pod. Suppose we take everything in between and eliminate all leading white space. This leaves something the pod processors will like. This leaves the problem of preserving leading white space when a verbatim paragraph is desired. We could accommodate that by adding a bit of "faux pod" (a term I should copyright) like

    =v  leave
    =v  this stuff
    =v  alone
[download]

where we could preprocess out the =v (and a single space, so we don't run afoul of some real pod directive?), and leave everything that follows untouched. No need for a final =cut, we could supply it automatically when we hit the pod terminator, or just omit it altogether, since the preprocessor is only gathering pod, so there's no need to drop "in and out".

Thread begun. Comments?

Comment on Re^4: Embedding pod in C Select or Download Code

Replies are listed 'Best First'.
Re^5: Embedding pod in C by John M. Dlugosz (Monsignor) on May 18, 2011 at 18:49 UTC
A better place might have been another top-level thread. But it's here now, so fine. Maybe start a new top-level thread once you have a design, asking for serious review, to attract fresh blood. A utility to strip a certain amount of whitespace from each line is a completely generic thing and could be written as a pipe. If each block might be indented differently, the preprocessor needs to identify them first and decide on the settings. So it might as well strip the leading space while extracting. I'm worried about distinguishing verbatim blocks based on a different indent. It might be too easy to get things wrong, and get a bunch of stuff treated as verbatim when it should not be, or truncate or refuse to recognize stuff that's not indented enough. So, for everything other than verbatim paragraphs, you should ignore whatever whitespace exists, whatever it may be. Once you indicate a POD region, shift everything left as far as it can go. But then you need another way to indicate verbatim, other than a different indent! Do you expect much verbatim stuff within the file? Your synopsis and examples can be in other files, and only documentation for these specific functions go with those functions in the same file. So maybe it is rare enough that you don't mind a little more decoration. To throw something out there, I'd suggest using `=code`, and then noting the position of that tag on the line, and removing the same amount of space from the start of subsequent lines. A line indented less than that amount, for any purpose, indicates that the verbatim section has ended. Allow blank lines within the verbatim, without worrying about matching the whitespace on such an "empty" line. Your example of putting a decoration at the start of every line, I think would get tiring to do. I like the idea of combining a flag with the #ifdef, so you don't need a separate =pod line, and you can check just the flagged blocks and not the whole file or all conditioned-out code. `#ifdef POD Plain flowing paragraph assumed if no directive found within this + block. Indent doesn't matter at all since the paragraph flows anyway! #endif // no =cut needed` [download] Basically, the implicit plain paragraph and the implicit cut are both automatic fallout from the idea of copying the special blocks. Whatever was copied is treated normally, and that means a plain paragraph. You don't need =end to go back to code, since the preprocessor has its own rules to decide what to take. Just be sure to add a blank line between each copied block in the output, and it will all work out. Write your code as a module. Write the simple .pl that uses the module to take input and output file parameters OR easily act as a filter, OR take file names as command arguments and writing to standard output: that will allow you to use a pipe-file notation as the file name with existing tools to process POD files! You said you worried about a false #endif in the middle of the POD. In a plain paragraph, just don't do that! Wrap it so # is not at the start of a line, and I.A.C. it would probably have C<…> wrapped around it anyway. To handle a verbatim paragraph, allow a leading ~# to be transformed into # on output. That's all I can think of. Best of luck! –John	[reply] [d/l]

Replies are listed 'Best First'.

Re^5: Embedding pod in C
by John M. Dlugosz (Monsignor) on May 18, 2011 at 18:49 UTC

A utility to strip a certain amount of whitespace from each line is a completely generic thing and could be written as a pipe.

If each block might be indented differently, the preprocessor needs to identify them first and decide on the settings. So it might as well strip the leading space while extracting.

I'm worried about distinguishing verbatim blocks based on a different indent. It might be too easy to get things wrong, and get a bunch of stuff treated as verbatim when it should not be, or truncate or refuse to recognize stuff that's not indented enough.

So, for everything other than verbatim paragraphs, you should ignore whatever whitespace exists, whatever it may be. Once you indicate a POD region, shift everything left as far as it can go.

But then you need another way to indicate verbatim, other than a different indent! Do you expect much verbatim stuff within the file? Your synopsis and examples can be in other files, and only documentation for these specific functions go with those functions in the same file. So maybe it is rare enough that you don't mind a little more decoration.

To throw something out there, I'd suggest using =code, and then noting the position of that tag on the line, and removing the same amount of space from the start of subsequent lines. A line indented less than that amount, for any purpose, indicates that the verbatim section has ended. Allow blank lines within the verbatim, without worrying about matching the whitespace on such an "empty" line.

Your example of putting a decoration at the start of every line, I think would get tiring to do.

I like the idea of combining a flag with the #ifdef, so you don't need a separate =pod line, and you can check just the flagged blocks and not the whole file or all conditioned-out code.

     #ifdef POD
     Plain flowing paragraph assumed if no directive found within this
+ block.
             Indent doesn't
    matter at all
      since the paragraph flows anyway!
     #endif  // no =cut needed
[download]

Just be sure to add a blank line between each copied block in the output, and it will all work out.

Write your code as a module. Write the simple .pl that uses the module to take input and output file parameters OR easily act as a filter, OR take file names as command arguments and writing to standard output: that will allow you to use a pipe-file notation as the file name with existing tools to process POD files!

You said you worried about a false #endif in the middle of the POD. In a plain paragraph, just don't do that! Wrap it so # is not at the start of a line, and I.A.C. it would probably have C<…> wrapped around it anyway.

To handle a verbatim paragraph, allow a leading ~# to be transformed into # on output.

That's all I can think of. Best of luck!

–John

[reply]
[d/l]