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.
I came across this command in a project I am working on:
sed -i '/regex/,$d' file
I don't understand how the ,$d part works. If I omit any part of ,$d I get errors. In my tests it looks like it replaces the matching line and anything after it with nothing. Example:
File with contents:
first line
second line regex
third line
fourth line
Comes out as after running that command:
first line
I couldn't find any documentation in the man page that explains this, though I could have easily missed it. The man page is hard for me to parse...
This is example was tested with GNU Sed v 4.2.2.
This is not a replacement command; the sed substitute or replace command looks like s/from/to/.
The general form of a sed script is a sequence of commands - typically a single letter, but some of them take arguments, like the s command above - with an optional address expression before each. You are looking at a d (delete line) command preceded by the address expression /regex/,$
The address range specifies lines from the first regex match through to the end of the file ($ in this context specifies the last line) and the action d deletes the specified lines.
Although many people only ever encounter simple sed scripts which use just the s command, this behavior will be described in any basic introduction to sed, as well as in the man page.
I have some PowerShell cmdlets for which I've created in-code documentation. All works fine except for one thing. If I have a long description for any of the documentation sections I'm splitting it into multiple lines so that it can be easily read from code. However I've noticed that those new line characters are then also represented as new lines in the PowerShell system.
As an example, here's part of the documentation
.PARAMETER MyParam
This parameter has a long documentation that does not fit into single line,
so I'm breaking it down to several lines.
Now once I run Get-Help on a cmdlet that contains this sort of comments I'll get something like.
-MyParam [<SwitchParameter>]
This parameter has a long documentation that does not fit
into single line,
so I'm breaking it down to several lines.
Required? true
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
Notice that the first line gets wrapped correctly, but then the second line (starting with the word so) also starts on a new line.
I could overcome this problem by putting my whole documentation block in one line but that wouldn't be too good for readability point of view.
Is there a way to treat the whole documentation block as it was part of the same text block but have the comments organized into multiple lines at the same time? Any way that I could tell in the documentation that I don't intend to make a new paragraph and I want to continue previous one?
I don't think this is possible apart from preprocessing help strings with external script.
Use word-wrap in your editor and keep everything on the one line. Keep a hotkey accessible for WW so you can quickly switch from one line to block of text when you need to edit it. Some editors (such as vim) are extremely good in navigating wrapped text (basically the same as it is not wrapped).
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.