Re: POD formatter version comments
On 2024-03-15 14:38, Russ Allbery wrote: If you would be happy with a PR to remove that bullet point, we're just vigorously agreeing. Otherwise, I'm not sure what you're asking for instead. I guess I wasn't clear. I was talking about making the requirement an option for the formatters. When the user runs a formatter, they can specify an option to include the info in their output. In other words, move it from a requirement to an optional implementation for a formatter. -- 푆풉풂풘풏 퐻 퐶풐풓풆풚
Re: POD formatter version comments
On 2024-03-15 12:44, Russ Allbery wrote: Shawn H Corey writes: I think it should be an option. Sometimes it is necessary to know that a change in appearance is caused by changes to a module and not to the generating document. Do we need to explicitly state that it's an option, or would removing the requirement to always do it still be okay? The way I was thinking of it is that what formatters put into comments is generally up to them; by default, they *can* include anything they want. Removing the requirement thus just leaves the decision unconstrained. I'm not sure what you're saying. If it's an option, then it is automatically not a requirement. Unless you mean what information to include is the requirement. In which case, having a standard would be nice. -- 푆풉풂풘풏 퐻 퐶풐풓풆풚
Re: POD formatter version comments
On 2024-03-15 11:43, Russ Allbery wrote: perlpodspec currently contains the following note on POD processor implementations: I think it should be an option. Sometimes it is necessary to know that a change in appearance is caused by changes to a module and not to the generating document. BTW, information of this type is called a colophon and is placed at the end of the document. -- 푆풉풂풘풏 퐻 퐶풐풓풆풚
Re: [feature] Add =image to perl pod #18169
On 2020-10-04 4:01 p.m., Dmitry Karasik wrote: Indeed, either don't use ":" in "something", or use the full syntax, or we may extend the syntax so that "\:" and "\\" expand to the unquoted symbols. Use the POD escape sequence instead: E<0x3A> and E<0x20> Also think about this: =for image src:C:\Somewhere On My Disk\image.png
Re: [feature] Add =image to perl pod #18169
On 2020-10-04 3:23 p.m., Patrice Dumas wrote: Are spaces ignored between :? Should there be a separator to simplify parsing, like =for image src:file.png, text:something Yes, there will be problems with separators since the separator can appear in the "something". =for image src:file.png text:do no use colons ":" in your text.
Re: [feature] Add =image to perl pod #18169
On 2020-10-04 11:11 a.m., Dmitry Karasik wrote: =for image src:file.png =for image src:file.png [fallback text] There should be an option for fallback text.
Re: What to do about L and L<"Foo Bar">
On Tue, 29 May 2018 09:40:08 -0700
Russ Allbery wrote:
> So I'm tentatively on the side of just leaving things alone, but I
> don't maintain any of the code that tries to generate links and cares
> about the places where this ambiguity might cause problems.
Leave the code alone (for now) but update the documentation to best
practice.
If necessary, put documentation for the old style in
`perlpoddeprecated`.
--
Don't stop where the ink does.
Shawn H Corey
Re: Looking for another pod tip
On Wed, 9 May 2018 20:54:57 -0600 Karl Williamson <pub...@khwilliamson.com> wrote: > I have an item text list. Not all the items have content besides the > text, and so the pod would collapse them together into adjacent > lines, whereas I want them separated. I did this by adding a NBSP, > but then I get an extra line that I'd rather not have. Try using the Z<> specification. =over =item one =item two The 2 above items are together =item three Z<> =item four This item is separate from item three =back -- Don't stop where the ink does. Shawn H Corey
Re: =item * foo bar
On Wed, 9 May 2018 09:44:32 -0600 Karl Williamson <pub...@khwilliamson.com> wrote: > which of course is legal, but the * would be output as a star and not > translated into a bullet, and that is what happens here. > A way to get a bullet and text is: =item E text Of course, that only does one level. > If I had known about this earlier, I would have used it in pods to > make it look better. So maybe the spec could be changed to > specifically allow this. Or are there commonly used implementations > that don't support it? The POD for Perl 5.6 and early would allow both. Sometime during 5.8 it was changed so bullets needed a single * and nothing else. `perldoc perlpod` still isn't clear on this. `perldoc perlpodspec` makes this clear. `perldoc perlpod` should be consider deprecated. -- Don't stop where the ink does. Shawn H Corey
Re: pod embedded in pod
On Thu, 13 Apr 2017 11:36:23 + RAPPAZ Francois via pod-people <pod-people@perl.org> wrote: > How can I embed pod directives in a pod directive so that they are > displayed as plain text ? I have tried =begin pod or =begin text > without success. Should I use E<61> instead of = ? > > Thanks > > François > Usually embedded POD is done in a verbatim paragraph since these will be rendered in a monospace font. =head1 Embedding POD in a POD =head1 This is not a heading. This is a verbatim paragraph. This will be displayed in a monospace font. This is a regular paragraph. =cut -- Don't stop where the ink does. Shawn H Corey
Re: Pod::Simple - August PR Challenge Assignment
On Tue, 18 Aug 2015 07:58:01 -0700 (PDT) Sean Zellmer s...@lejeunerenard.com wrote: Hey all, I was assigned Pod::Simple as my August module for the PR Challenge and was wondering if anything jumps to mind as a project for my PR. Any ideas are welcome. :) Peace, Sean Well, I do have a wish list :) https://github.com/shawnhcorey/perl5/blob/master/wishlist.pod -- Don't stop where the ink does. Shawn
Re: Allow Whitespace in L URLs?
On Thu, 8 Jan 2015 10:42:10 -0800 David E. Wheeler da...@justatheory.com wrote: I think that is probably sane, but maybe there are other opinions? Should we allow whitespace in L URLs? URLs use + or %20 for spaces. There is no need for whitespace in a URL. -- Don't stop where the ink does. Shawn
Re: pod::simple::text
On Thu, 26 Jun 2014 15:40:14 +1200
Grant McLean gr...@mclean.net.nz wrote:
On Wed, 2014-06-25 at 18:05 +, John E Guillory wrote:
Hello,
I thought I wasn’t this new to perl but …
How does one use pod::simple::text to print out a section of POD,
say the DESCRIPTION section?
Pod::Simple provides some core POD parsing functionality which is
shared by a number of formatter classes. There isn't any sort of
query API that would allow you to specify which sections of the POD
you want.
If you do want to produce formatted plain-text output of just the
DESCRIPTION section, then probably the easiest way is to slurp in all
the POD source; use a regex to extract the section you want; and then
pass that to a formatter:
my($pod_source) =
read_file($source_file) =~
m{^(=head1\s+DESCRIPTION.*?)(?:^=head1.*)?\z}ms;
my $parser = Pod::Simple::Text-new();
$parser-parse_string_document($pod_source);
The parser(/formatter) will write its output to STDOUT unless you call
$parser-output_fh with an alternative filehandle.
An alternative approach would be to subclass Pod::Simple::Text and
maintain a flag indicating when the parser is 'in' the DESCRIPTION
section and suppress all output when the flag is not set.
Unfortunately the suppress all output bit is tricky since all the
methods that produce formatted output write directly to the output
filehandle.
Regards
Grant
Pod::Usage can extract sections for a POD. It come with perl.
#!/usr/bin/perl
use Pod::Usage;
# Documentation levels
my $DOC_USAGE = 0;
my $DOC_HELP = 1;
my $DOC_VER = 2;
my $DOC_MAN = 3;
# --
# Subroutines
# --
# Name: print_documentation
# Usage: print_documentation( $documentation_level );
#Purpose: Print the usage, help, or man documentation.
#Returns: Does not return.
# Parameters: $documentation_level -- how much documentation to display.
# 0 == usage
# 1 == help
# 2 == version
# other == man
#
sub print_documentation {
my $level = shift @_ || $DOC_USAGE;
my @doc_options = (
# DOC_USAGE
{
-exitval = 2,
-verbose = 99,
-sections = 'USAGE',
},
# DOC_HELP
{
-exitval = 2,
-verbose = 99,
-sections = 'NAME|VERSION|USAGE|REQUIRED ARGUMENTS|OPTIONS',
},
# DOC_VER
{
-exitval = 2,
-verbose = 99,
-sections = 'NAME|VERSION',
},
# DOC_MAN
{
-exitval = 2,
-verbose = 2,
},
);
# validate level
$level =~ tr [0-9] []cds;
$level ||= $DOC_USAGE;
$level = $DOC_USAGE if $level = @doc_options;
# print the documentation
pod2usage( $doc_options[$level] );
}
--
Don't stop where the ink does.
Shawn
Re: Tables in PODs
On Fri, 20 Sep 2013 15:43:00 +0100 Nicholas Clark n...@ccl4.org wrote: There is a perl 6 specification for tables. See https://raw.github.com/perl6/specs/master/S26-documentation.pod Interesting. But some problems with it. 1. It breaks old parsers. 2. Does not allow for full POD specifications in cells. That is, you cannot put a verbatim paragraph or a `=over/=item/=back` list in a cell. (You also can't nest tables but we may not want to go there.) -- Don't stop where the ink does. Shawn
Contiguous Specification
I might as well throw this one out there too. This is only for parsers that create multiple pages. Those which don't can skip it. And, of course, older parsers will ignore it. =begin :contiguous =end :contiguous Items within a contiguous section will be render on the same page, if possible. If not, they will be render on a few pages as possible. Single, regular paragraphs can be contiguous with: =for :contiguous paragraph Note that older parsers will ignore these paragraphs too. To ensure that they are render by older parsers, use the `=begin/=end` specification instead. -- Don't stop where the ink does. Shawn
Tables in PODs
Is there any specification for tables in PODs? I haven't been able to find any. Isn't it about time tables were added? I have attached a specification for them for your review. -- Don't stop where the ink does. Shawn tables.pod Description: Binary data
Re: The Encoding Warning (Again) - some data
On Tue, 28 Aug 2012 22:16:20 -0600 Sean M. Burke sbu...@cpan.org wrote: But I think we should also hold pod parsers to a high standard of keeping quiet when simple heuristics are unproblematically applied. I'm not sure about that. One of the reason why there's so much trashy HTML out there is because browsers accept it without complaint. I mean, look at the problems of parsing this: =item 1. An Example When they really meant: =item 1. BAn Example As the old saying goes: it's the squeaky wheel that gets fixed. -- Just my 0.0002 million dollars worth, Shawn Programming is as much about organization and communication as it is about coding. _Perl links_ official site : http://www.perl.org/ beginners' help : http://learn.perl.org/faq/beginners.html advance help: http://perlmonks.org/ documentation : http://perldoc.perl.org/ news: http://perlsphere.net/ repository : http://www.cpan.org/ blog: http://blogs.perl.org/ regional groups : http://www.pm.org/
Re: Possible patch to Test::Pod
On 12-06-06 11:50 AM, David E. Wheeler wrote: End users don’t necessarily know if a test failure is important or not. All tests are important, otherwise they wouldn't be included in the distribution. Therefore, all test failures are important. -- Just my 0.0002 million dollars worth, Shawn Programming is as much about organization and communication as it is about coding. _Perl links_ official site : http://www.perl.org/ beginners' help : http://learn.perl.org/faq/beginners.html advance help: http://perlmonks.org/ documentation : http://perldoc.perl.org/ news: http://perlsphere.net/ repository : http://www.cpan.org/ blog: http://blogs.perl.org/ regional groups : http://www.pm.org/
Re: Strange perldoc perldoc
On 12-04-30 01:30 PM, Russ Allbery wrote: Indeed, and it shouldn't have any special treatment. You're experiencing some sort of bug, I think. I just don't know where. This works: /usr/bin/perldoc perldoc $ which perldoc /home/shawn/perl5/perlbrew/perls/perl-5.14.2/bin/perldoc $ /usr/bin/perldoc -V Perldoc v3.15_02, under perl v5.012004 for linux $ perldoc -V Perldoc v3.17, under perl v5.014002 for linux $ /usr/bin/perl -v This is perl 5, version 12, subversion 4 (v5.12.4) built for x86_64-linux-gnu-thread-multi (with 45 registered patches, see perl -V for more detail) ... $ perl -v This is perl 5, version 14, subversion 2 (v5.14.2) built for x86_64-linux-gnu-thread-multi ... $ -- Just my 0.0002 million dollars worth, Shawn Programming is as much about organization and communication as it is about coding. [updated for today's programmers] Show me your code and conceal your interfaces, and I shall continue to be mystified. Show me your interfaces, and I won't usually need your code; it'll be obvious. -- Fred Brooks Don't be clever; being great is good enough.
Re: =item 1. Error
On 12-04-26 11:57 AM, Russ Allbery wrote: 1. If the =item tags are numeric, ignore the value of the numbers and just renumber them. This is similar to what other markup languages do, but it has the significant problem of making it a bit more annoying to document, say, a list of exit status returns, where several numbers are skipped. =over =item Z42 The answer to the Ultimate Question. =back -- Just my 0.0002 million dollars worth, Shawn Programming is as much about organization and communication as it is about coding. [updated for today's programmers] Show me your code and conceal your interfaces, and I shall continue to be mystified. Show me your interfaces, and I won't usually need your code; it'll be obvious. -- Fred Brooks Don't be clever; being great is good enough.
Re: pod2html in perl-5.15.9 recognizes POD markup in verbatim sections
On 12-04-24 11:48 PM, David E. Wheeler wrote: On Apr 24, 2012, at 2:46 PM, chromatic wrote: Any objections? Yes; I use this feature. Better to make it an option in pod2html to turn it off. Or perhaps it turns it off by default, and you need an option to turn it on. I agree. It's best to have it conform to the behaviour of the rest and have an option of changing that behaviour. Which leads to the question: do any of the rest have this option and, if not, should they? -- Just my 0.0002 million dollars worth, Shawn Programming is as much about organization and communication as it is about coding. [updated for today's programmers] Show me your code and conceal your interfaces, and I shall continue to be mystified. Show me your interfaces, and I won't usually need your code; it'll be obvious. -- Fred Brooks Don't be clever; being great is good enough.
Re: pod2html in perl-5.15.9 recognizes POD markup in verbatim sections
On 12-04-25 11:22 AM, Russ Allbery wrote: I think a better approach would have been to add a new command (=formatted or something) that had these semantics rather than changing the interpretation of existing verbatim paragraphs. It would be better if it used the =begin/=for/=end syntax: =begin verbatim ... =end verbatim =for verbatim ... -- Just my 0.0002 million dollars worth, Shawn Programming is as much about organization and communication as it is about coding. [updated for today's programmers] Show me your code and conceal your interfaces, and I shall continue to be mystified. Show me your interfaces, and I won't usually need your code; it'll be obvious. -- Fred Brooks Don't be clever; being great is good enough.
Re: an 'anchor' command is missing from Pod
On 12-01-27 11:14 PM, Ricardo Signes wrote: You're thinking of X -- Z should always be empty, and is a zero-effect code. Xopen is used to help indexing. It isn't how perldoc -f works, though. No, I've encountered unempty Z in some PODs. -- Just my 0.0002 million dollars worth, Shawn Programming is as much about organization and communication as it is about coding. Strength is not a measure of the body. It's a measure of the heart.
Re: an 'anchor' command is missing from Pod
On 12-01-27 06:36 PM, Patrice Dumas wrote: It could be along =anchor open if it is a Command Paragraph, or Aopen if it is a formatting command. I thought they were using the Z code for it: =item open FILEHANDLE,EXPR =item open FILEHANDLE,MODE,EXPR =item open FILEHANDLE,MODE,EXPR,LIST Zopen -- Just my 0.0002 million dollars worth, Shawn Programming is as much about organization and communication as it is about coding. Strength is not a measure of the body. It's a measure of the heart.
Re: Removal of specific Pod::Checker warnings
On 11/08/11 11:45 AM, Marc Green wrote: I agree that a POD checker should report *all* errors/warnings, but is having an argumentless =item really a warning? By Pod::Checker's defintion, a warning indicates bad style, so that would mean that having an argumentless =item is bad style. Personally, I don't think it is; I find it a convenient shorthand. Do you disagree? You're correct. Under Pod Commands, =item is listed as a bare item. I don't know why there is a note for being forgiving for a valid structure, but it's confusing. And, of course, if it's valid, it can't be bad style. -- Just my 0.0002 million dollars worth, Shawn Confusion is the first step of understanding. Programming is as much about organization and communication as it is about coding. The secret to great software: Fail early often. Eliminate software piracy: use only FLOSS. Make something worthwhile. -- Dear Hunter
Re: Removal of specific Pod::Checker warnings
On 11/08/11 12:17 PM, David E. Wheeler wrote: what if I want my block quote to contain a list, just nest them? Yup. -- Just my 0.0002 million dollars worth, Shawn Confusion is the first step of understanding. Programming is as much about organization and communication as it is about coding. The secret to great software: Fail early often. Eliminate software piracy: use only FLOSS. Make something worthwhile. -- Dear Hunter
Re: [perl #95784] [PATCH] Let X within anchorifiable paragraphs be additional anchors.
On 11-08-04 09:55 PM, Rocco Caputo wrote: For example, this looks great in the HTML TOC outline. It's reminiscent of traditional man pages where usage summaries are listed at the top. But it's terrible to link to this section: =head3 select_read FILE_HANDLE [, EVENT_NAME [, ADDITIONAL_PARAMETERS] ] I thought the Z code was being use for named anchors: =head3 select_read FILE_HANDLE [, EVENT_NAME [, ADDITIONAL_PARAMETERS] ] Zselect_read_main and later: Lselect read|select_read_main I think the Pod::Simple https://metacpan.org/module/Pod::Simple does this. -- Just my 0.0002 million dollars worth, Shawn Confusion is the first step of understanding. Programming is as much about organization and communication as it is about coding. The secret to great software: Fail early often. Eliminate software piracy: use only FLOSS. Make something worthwhile. -- Dear Hunter
Re: Handling nested =open directives
On 11-06-25 04:19 PM, Marc Green wrote: From ext/Pod-Html/t/htmlview.pod: =over 4 =item foo The foo item. =item bar *The bar item.* =over 4 *This is a list within a list * This paragraph should not be here. There should be nothing between the =over and the first =item. Is it in the original? =item * The wiz item. =item * The waz item. =back =item baz The baz item. =back -- Just my 0.0002 million dollars worth, Shawn Confusion is the first step of understanding. Programming is as much about organization and communication as it is about coding. The secret to great software: Fail early often. Eliminate software piracy: use only FLOSS.
How to report a documentation error
I noticed some errors in the documentation of Pod::Simple::HTMLBatch. Here's one: % mkdir out_html % perl -MPod::Simple::HTMLBatch -e Pod::Simple::HTMLBatch::go @INC out_html (to convert the pod from Perl's @INC files under the directory ../htmlversion) Shouldn't ../htmlversion be ./out_html ? What's the best way to report this? -- Just my 0.0002 million dollars worth, Shawn Confusion is the first step of understanding. Programming is as much about organization and communication as it is about coding. The secret to great software: Fail early often. Eliminate software piracy: use only FLOSS.
Using UTF-8
Does Pod::Simple understand UTF-8? I have a POD with '½' in it but when I run it through Pod::Simple::SimpleTree, I get '½'. The UTF-8 code is C2 BD which corresponds to  and ½ in ISO-8859-1. How do I turn on UTF-8? -- Just my 0.0002 million dollars worth, Shawn Confusion is the first step of understanding. Programming is as much about organization and communication as it is about coding. The secret to great software: Fail early often. Eliminate software piracy: use only FLOSS.
Re: How can one put a table into a pod
On 11-05-04 03:16 PM, Ronald J Kimball wrote: =cell Jcenter Jspan 2 This is a wide, centered cell! What if you want a cell to span two columns and two rows at the same time? =cell Jcenter Jmiddle Jrowspan 2 jcolspan 2 paragraph -- Just my 0.0002 million dollars worth, Shawn Confusion is the first step of understanding. Programming is as much about organization and communication as it is about coding. The secret to great software: Fail early often. Eliminate software piracy: use only FLOSS.
Re: Bad `=for` spec (WAS: How can one put a table into a pod)
On 11-04-26 01:06 PM, Allison Randal wrote: It's kind of fundamental to the nature of subclassing that you can override any behavior you want.:) The nicest thing about standards is that everyone can make their own. -- Just my 0.0002 million dollars worth, Shawn Confusion is the first step of understanding. Programming is as much about organization and communication as it is about coding. The secret to great software: Fail early often. Eliminate software piracy: use only FLOSS.
Re: Bad `=for` spec (WAS: How can one put a table into a pod)
On 11-04-23 08:23 PM, Allison Randal wrote: The table formatting it uses is demonstrated in: http://search.cpan.org/~arandal/Pod-PseudoPod-0.16/lib/Pod/PseudoPod/Tutorial.pod#Tables I have just taken a look at this. They totally screwed up `=for`. A `=for` paragraph does not need a `=end for`. Example: =head1 TEST =for ignore This should not be seen. This should. =cut -- Just my 0.0002 million dollars worth, Shawn Confusion is the first step of understanding. Programming is as much about organization and communication as it is about coding. The secret to great software: Fail early often. Eliminate software piracy: use only FLOSS.
