I use Pod to write manuals for my program. And I ran into a problem. Please tell me how to solve it.
I have the following code:
#include <myhead.h>
I<void> myfunc (I<int arg1>, I<int arg2>);
I would like the text to be written from the next line after the word 'void'. Moreover, it is with the next line, and not through one.
Pod is "plain ol' documentation" and doesn't have fancy features. It sounds like you want the text after void to be on the next line. In that case, you have to put that text on the next line and make it verbatim text so it retains the formatting:
=pod
#include <myhead.h>
I<void>
myfunc (I<int arg1>, I<int arg2>);
=cut
If you need something else, improve your questions by showing exactly what you expect.
But, I expect that you probably want to write your own Pod formatter. Then you can do exactly what you want. Fo what it's worth, I write all of my books in Pod and use several custom formatters to get them into their end states.
Pod has paragraph breaks and preformatted text, but no line breaks.
If you are targeting a particular output format, you can do, for example:
=begin html
One line
Another line
=end html
Or you could do some kind of post-processing on the file.
Related
I have this POD file:
=head1 Create professional slideshows with Mojolicious::Plugin::RevealJS
=head2 Install and run a Mojolicious server
Santa's elf had a problem. He had to write very fast a presentation and show it to a bunch of new elf's.
The email assigning this to him was sent by Santa himself.
The elf started to look on Metacpan and found this module: L<Mojolicious::Plugin::RevealJS|https://metacpan.org/pod/Mojolicious::Plugin::RevealJS>
He quickly typed the following commands:
C<cpanm Mojolicius Mojolicious::Plugin::RevealJS>
Now he could generate an mojo lite app using:
C<mojo generate lite-app slide_show>
Because the elf was trained in the ancient arts of the elders
he cloud open new file with vim and paste this code in:
=begin perl
use Mojolicious::Lite -signatures;
app->static->paths(['.']);
plugin 'RevealJS';
any '/' => { template => 'presentation', layout => 'revealjs' };
app->start;
=end perl
When I run perldoc t.pod, the code between '=begin perl' and '=end perl' is not visible. I don't understand what I'm doing wrong.
The perlpod documentation says ...
For, begin, and end will let you have regions of text/code/data that are not generally interpreted as normal Pod text, but are passed directly to particular formatters, or are otherwise special. A formatter that can use that format will use the region, otherwise it will be completely ignored.
The formatter in this case is the thing that perldoc uses to render your POD into text. I suspect it doesn't know what to do with the format perl, so it ignores it.
A formatter that produces HTML might know what to do with the perl format, and might replace this with a code block that has syntax highlighting.
If you want your code examples in the POD to always show up as code, use a verbatim paragraph instead. This is done by adding indentation at the front.
=head2 frobnicate($foo)
This function frobnicates the C<$foo>.
my $bar = frobnicate($foo)
=cut
sub frobnicate { ... }
The description of a =begin <format>/=end <format> in perlpod starts by saying this:
=begin formatname
=end formatname
=for formatname text...
For, begin, and end will let you have regions of text/code/data that are not generally interpreted as normal Pod text, but are passed directly to particular formatters, or are otherwise special. A formatter that can use that format will use the region, otherwise it will be completely ignored.
Anything between =begin perl and =end perl is ignored by the standard Pod formatter and will only be processed by a specialised "perl" formatter (and no such formatter exists in the standard Perl toolset - you'd need to write your own).
You don't say what you expect this syntax to achieve, but it seems likely that you're looking for a verbatim paragraph.
Verbatim Paragraph
Verbatim paragraphs are usually used for presenting a codeblock or other text which does not require any special parsing or formatting, and which shouldn't be wrapped.
A verbatim paragraph is distinguished by having its first character be a space or a tab. (And commonly, all its lines begin with spaces and/or tabs.) It should be reproduced exactly, with tabs assumed to be on 8-column boundaries. There are no special formatting codes, so you can't italicize or anything like that. A \ means \, and nothing else.
I am using Scribble to write assignments and would like to have the ability to include common text snippets somewhere in the document. For example:
#lang scribble/manual
#section{Some section}
#include-file["common-pretext.scrbl"] #; my imaginary command
Some additional text after the pretext
#section{Next section}
More text...
I would like #include-file to include the contents of common-pretext.scrbl just as if I had copy/pasted its contents at the specified position. That is, I would like its contents to be part of Some section and also properly handle Scribble commands occurring in common-pretext.scrbl.
I know that Scribble has #include-section, which is similar to what I want. However, #include-section always starts a new section and text following it until the next section is silently dropped (I am not sure why this happens, but presumably because of how the document is constructed). I also tried Racket's #include, but then the contents are not shown at all. Lastly, I tried building a macro that does what I want, but failed to make it work (if a macro is the way to go, then I am happy to share my attempts so far).
Is there such a command already and if not how can I build one?
This question is pretty old, but if you are still looking, this package does what you want:
https://docs.racket-lang.org/scribble-include-text/index.html
I have noticed that a lot of Pod has blank lines between the lines such as
code
=head1 DESCRIPTION
text
Are these blank lines strictly needed, do specific parsers get upset if it is missing.
The description for cut in perlpod helps a little but I was wondering about other constructs :
To end a Pod block, use a blank line,
then a line beginning with
"=cut", and a blank line after it. This lets Perl (and the Pod
formatter) know that this is where Perl code is resuming. (The
blank line before the "=cut" is not technically necessary,
but many
older Pod processors require it.)
perldoc perlpod says that "every command needs the blank line after it, to end its paragraph" and "Many older Pod translators require the lines before every Pod command and after every Pod command (including "=cut"!) to be a blank line".
Paragraphs are delineated by blank lines, so I find it difficult to imagine starting a command paragraph without a blank line immediately preceding it. Maybe at the start of a file?
Note that in Perl 6, Pod is redefined so that blank lines around commands (before and after) are no longer necessary.
From POD::Parser
Please note that POD has the notion of "paragraphs": this is something starting after a blank (read: empty) line, with the single exception of the file start, which is also starting a paragraph. That means that especially a command (e.g. =head1 ) must be preceded with a blank line; END is not a blank line.
see perlpodspec also, you will
find the reason why blank lines
needed.
This RFC mentions
Unlike many programming languages Perl does not currently implement true multiline comments. This, and the workarounds that are in common use can be problematic. This could be solved by adding a new syntax to allow for comments to span more than one line, like the variation on here-documentation cited below.
What are the common workarounds?
Two techniques I found here are
if (0) {
<comment>
}
and
=pod
<comment>
=cut
Are these safe to use? Are there others that work better?
The downside of the "if" solution is that the commented out code still has to be compiled (and therefore still has to be syntax checked).
The downside of your pod solution is that your comments will appear in any documentation generated from the pod.
I use a version of the pod solution that doesn't have that problem. Pod supports =begin format ... =end format paragraphs that are handled by specific formatters. I just invent a "comment" format that isn't handled by any of the formatters I use.
#!/usr/bin/perl
print "This line is executed\n";
=begin comment
print "This line isn't\n";
=end comment
=cut
print "This line is\n";
The Perl documentation tells you how to do it in perlfaq7. It's plenty safe, and since we can do it with Pod, we don't need additional syntax to do it:
How can I comment out a large block of perl code?
You can use embedded POD to discard it. Enclose the blocks you want to
comment out in POD markers. The =begin directive marks a section for
a specific formatter. Use the "comment" format, which no formatter
should claim to understand (by policy). Mark the end of the block with
=end.
# program is here
=begin comment
all of this stuff
here will be ignored
by everyone
=end comment
=cut
# program continues
The pod directives cannot go just anywhere. You must put a pod
directive where the parser is expecting a new statement, not just in
the middle of an expression or some other arbitrary grammar production.
See perlpod for more details.
Although it's non-standard, I just use
=ignore
sub blah { ... }
my $commented_out_var = 3.14;
=cut
It works just as well, and reminds me that it is not POD.
Aside: It is an interesting thing that POD gives us a flexible framework for including various regions that should not regarded as code, specifying what that region means. Clearly we "comment things out" because comments work this way. Yet, it is clear from the term that comments are meant to be words, not instructions; documentation not alterations.
An editor with a "Comment Region" function.
For example, Komodo Edit. I'm pretty sure Eclipse and JEdit do it as well, but I don't have them handy to check.
The feature usually inserts a "Comment this line" symbol at the start of every line in the selected region. It has the benefit of not conflicting with existing comments (which is a risk if you wrap an area containing a multi-line comment in most languages)
My favorite multi-line comment device is __END__.
print "Hello world\n";
__END__
The script has ended. Perl does not treat this part of the file as code.
I can put whatever I want down here. Very handy.
This works too:
q^
This is another way to
add multi-line comments
to your code
^ if 0;
In addition to the
=begin comment
multi-paragraph comments here
=end comment
=cut
form in other answers, you can also do this:
=for comment
this is a single pod paragraph comment do
not put extra blank lines after =for. the
comment ends after the first blank line and
regular pod continues until =cut
Hello! C<Yay!>
=cut
the comment paragraph will not appear in the pod output, but the Hello "Yay!" will.
One special use-case is commenting out several lines of code. But if you use a version control system, you can just delete unwanted code rather than commenting it out, and if you ever need it back, just fetch the old revision.
Something like works too:
q{
my comment
};
THis is an expression I guess evaluated while running Perl.
This even simpler construct worked for me
=comment
It was hard in the Moonta Mines that year
For the miners, down in the pit,
It wasn’t a place for a weak man, but
The Cornish Miners had grit,
They burrowed deeper with every day
Extracting the copper ore,
And the skimps grew high in the heaps that piled
Not far from the Moonta shore.
=cut
I use that way and works for me
=head
"your code to comment
monkey
banana"
=cut
Yet another helpful way!
=begin GHOSTCODE
whatever you want to uncomment
=end GHOSTCODE
=cut
This isn't a Perl syntactical way to do it, but in most editors (like Notepad++) you can highlight code you want to be commented out, and then press CTRL+K. To remove the comments you can highlight them and press CTRL+Shift+K.
substr($obj_strptime,index($strptime,"sub")+6,0) = <<'ESQ';
shift; # package
....
....
ESQ
What is this ESQ and what is it doing here? Please help me understand these statements.
It marks the end of a here-doc section.
EOF is more traditional than ESQ though.
This construct is known as a here-doc (because you're getting standard input from a document here rather than an external document on the file system somewhere).
It basically reads everything from the next line up to but excluding an end marker line, and uses that as standard input to the program or command that you're running. The end marker line is controlled by the text following the <<.
As an example, in bash (which I'm more familiar with than Perl), the command:
cat <<EOF
hello
goodbye
EOF
will run cat and then send two lines to its standard input (the hello and goodbye lines). Perl also has this feature though the syntax is slightly different (as you would expect, given it's a different language). Still, it's close enough for the explanation to still hold.
Wikipedia has an entry for this which you probably would have found had you known it was called a here-doc, but otherwise it would be rather hard to figure it out.
You can basically use any suitable marker. For example, if one of your input lines was EOF, you couldn't really use that as a marker since the standard input would be terminated prematurely:
cat <<EOF
This section contains the line ...
EOF
but then has more stuff
and this line following is the real ...
EOF
In that case, you could use DONE (or anything else that doesn't appear in the text on its own line).
There are other options such as using quotes around the marker (so the indentation can look better) and the use of single or double quotes to control variable substitution.
If you go to the perlop page and search for <<EOF, it will hopefully all become clear.