Google Groups no longer supports new Usenet posts or subscriptions. Historical content remains viewable.
Dismiss
Pod::Simple output as POD
0 views
Skip to first unread message
James E Keenan
Aug 12, 2014, 10:06:40 AM8/12/14
to pod-p...@perl.org
I am writing concerning
https://rt.perl.org/Ticket/Display.html?id=116467. The objective of
this ticket is to revise t/porting/podcheck.t so that it no longer
depends on CPAN module Pod::Parser. The latter has been designated
"legacy code" but we cannot remove it from the core distribution until
podcheck.t no longer depends on it, either directly (calls to
parse_from_filehandle) or indirectly (via an older version of
Pod::Checker which depends on Pod::Parser rather than Pod::Simple).
While studying podcheck.t recently I noticed that we could get
substantially closer to our goal if we took the following subroutine
from podcheck.t:
#####
sub extract_pod { # Extracts just the pod from a file; returns undef
if file
# doesn't exist
my $filename = shift;
my @pod;
# Arrange for the output of Pod::Parser to be collected in an array
we can
# look at instead of being printed
tie *ALREADY_FH, 'Tie_Array_to_FH', \@pod;
if (open my $in_fh, '<:bytes', $filename) {
my $parser = Pod::Parser->new();
$parser->parse_from_filehandle($in_fh, *ALREADY_FH);
close $in_fh;
return join "", @pod
}
...
#####
... and could rewrite the 'if' block using a Pod::Simple-based call.
However, AFAICT there is nothing in the latest CPAN release of
Pod::Simple by which one could simple extract the POD from a file and
return it as a single string, POD-formatting intact and otherwise
unmodified.
Karl Williamson noted
(https://rt.perl.org/Ticket/Display.html?id=116467#txn-1304150) that
there have been some efforts in this direction, citing:
https://github.com/genehack/pod-simple/tree/add-pod-simple-pod. Could
you advise as to the current state of development of this fork and
whether it is likely to be of benefit to P5P in this instance?
Thank you very much.
Jim Keenan
https://rt.perl.org/Ticket/Display.html?id=116467. The objective of
this ticket is to revise t/porting/podcheck.t so that it no longer
depends on CPAN module Pod::Parser. The latter has been designated
"legacy code" but we cannot remove it from the core distribution until
podcheck.t no longer depends on it, either directly (calls to
parse_from_filehandle) or indirectly (via an older version of
Pod::Checker which depends on Pod::Parser rather than Pod::Simple).
While studying podcheck.t recently I noticed that we could get
substantially closer to our goal if we took the following subroutine
from podcheck.t:
#####
sub extract_pod { # Extracts just the pod from a file; returns undef
if file
# doesn't exist
my $filename = shift;
my @pod;
# Arrange for the output of Pod::Parser to be collected in an array
we can
# look at instead of being printed
tie *ALREADY_FH, 'Tie_Array_to_FH', \@pod;
if (open my $in_fh, '<:bytes', $filename) {
my $parser = Pod::Parser->new();
$parser->parse_from_filehandle($in_fh, *ALREADY_FH);
close $in_fh;
return join "", @pod
}
...
#####
... and could rewrite the 'if' block using a Pod::Simple-based call.
However, AFAICT there is nothing in the latest CPAN release of
Pod::Simple by which one could simple extract the POD from a file and
return it as a single string, POD-formatting intact and otherwise
unmodified.
Karl Williamson noted
(https://rt.perl.org/Ticket/Display.html?id=116467#txn-1304150) that
there have been some efforts in this direction, citing:
https://github.com/genehack/pod-simple/tree/add-pod-simple-pod. Could
you advise as to the current state of development of this fork and
whether it is likely to be of benefit to P5P in this instance?
Thank you very much.
Jim Keenan
John SJ Anderson
Aug 12, 2014, 4:25:59 PM8/12/14
to James E Keenan, pod-p...@perl.org
Jim -
The current state of that code is that I think it mostly works, but it
needs tests (or it needs the tests to be finished). It's been a while
since I touched it, I'm not sure when I'm going to be able to get back
to it, but I would be perfectly happy if somebody wanted to grab it
and wrap it up.
chrs,
john.
The current state of that code is that I think it mostly works, but it
needs tests (or it needs the tests to be finished). It's been a while
since I touched it, I'm not sure when I'm going to be able to get back
to it, but I would be perfectly happy if somebody wanted to grab it
and wrap it up.
chrs,
john.
Randy Stauner
Aug 12, 2014, 10:26:57 AM8/12/14
to James E Keenan, pod-p...@perl.org
According to genehack, on May 22, 2014:
> I did start on Pod::Simple::POD, but it's still a work in progress. What I've done so far is at https://github.com/genehack/pod-simple/tree/add-pod-simple-pod , should anybody want to pick it up and run with it.
> I think it was mainly a matter of writing tests, but honestly it has been a while since I looked at that code.
(quotes taken from https://github.com/CPAN-API/cpan-api/issues/269)
John SJ Anderson
May 10, 2016, 2:45:01 PM5/10/16
to Karl Williamson, James E Keenan, pod-p...@perl.org
> On May 8, 2016, at 21:04, Karl Williamson <pub...@khwilliamson.com> wrote:
>
> I have taken on the task of completing this, and am nearly done. I'm writing because I wonder what other use-cases there are for this module besides extracting pod from a file that also contains other things. I can't think of any. And if there are no significant ones, I wonder if the name should instead be Pod::Simple::ExtractPod, instead of Pod::Simple::Pod?
From what I recall, that was also my use case (IIRC, I was trying to automate producing a GitHub Pages-hosted version of the POD during a Dzil release process).
My only comment on ‘ExtractPod’ as a name would be that all the other modules in the Pod::Simple dist that do similar things are simply named ‘Pod::Simple::$FORMAT’, (e.g., Pod::Simple::HTML, Pod::Simple::RTF, etc.)
At the end of the day, you’ve done the work to get it out the door and as far as I’m concerned, you can call it whatever you like. 8^)
(Karl, sorry for the mostly duplicated response to your earlier message to me.)
thanks,
john.
Karl Williamson
May 11, 2016, 8:45:02 PM5/11/16
to John SJ Anderson, James E Keenan, pod-p...@perl.org
glance know what it does. I imagine that if it were named simply 'Pod'
that people would think. "I've already got Pod input, why would I want
Pod output", and either investigate, or blow it off. So that's why I
came up with ExtractPod, but I'd like to hear other opinions.
Ron Savage
May 11, 2016, 9:00:03 PM5/11/16
to pod-p...@perl.org
Hi
On 12/05/16 10:39, David E. Wheeler wrote:
> On May 11, 2016, at 5:29 PM, Karl Williamson <pub...@khwilliamson.com> wrote:
> Which also seems a little weird. Maybe Pod::Simple::PodFormat?
Pod::Simple::ExtractPod is good, but possible is Pod::Simple::JustPod.
--
Ron Savage - savage.net.au
On 12/05/16 10:39, David E. Wheeler wrote:
> On May 11, 2016, at 5:29 PM, Karl Williamson <pub...@khwilliamson.com> wrote:
> Which also seems a little weird. Maybe Pod::Simple::PodFormat?
Pod::Simple::ExtractPod is good, but possible is Pod::Simple::JustPod.
--
Ron Savage - savage.net.au
John SJ Anderson
May 12, 2016, 11:00:02 AM5/12/16
to pod-p...@perl.org
> On May 11, 2016, at 17:52, Ron Savage <r...@savage.net.au> wrote:
> On 12/05/16 10:39, David E. Wheeler wrote:
>
>> Which also seems a little weird. Maybe Pod::Simple::PodFormat?
>
> Pod::Simple::ExtractPod is good, but possible is Pod::Simple::JustPod.
8^)
j.
Karl Williamson
May 13, 2016, 2:15:02 PM5/13/16
to John SJ Anderson, pod-p...@perl.org
essence, and seems to me to fit the paradigm of the output format.
If we wanted to be cute, we could call it Pod::Simple::SimplyPod, with
you know, only one, natural, ingredient, and no harmful additives.
Ron Savage
May 13, 2016, 10:15:01 PM5/13/16
to pod-p...@perl.org
Hi David
On 12/05/16 10:39, David E. Wheeler wrote:
> Like John, I don’t much care. I agree that Pod::Simple::Pod lacks necessary information. ExtractPod seems fine to me. Uh, though there is this:
>
> perldoc [-h] [-D] [-t] [-u] [-m] [-l] [-F]
> [-i] [-V] [-T] [-r]
> [-d destination_file]
> [-o formatname]
> [-M FormatterClassName]
> [-w formatteroption:value]
> [-n nroff-replacement]
> [-X]
> [-L language_code]
> PageName|ModuleName|ProgramName|URL
>
> So the formatter arg to -M would be:
>
> perldoc -M ExtractPod
Perhaps leave -M, and add -J, which defaults to a value of JustPod.
On 12/05/16 10:39, David E. Wheeler wrote:
>
> perldoc [-h] [-D] [-t] [-u] [-m] [-l] [-F]
> [-i] [-V] [-T] [-r]
> [-d destination_file]
> [-o formatname]
> [-M FormatterClassName]
> [-w formatteroption:value]
> [-n nroff-replacement]
> [-X]
> [-L language_code]
> PageName|ModuleName|ProgramName|URL
>
> So the formatter arg to -M would be:
>
> perldoc -M ExtractPod
>
> Which also seems a little weird. Maybe Pod::Simple::PodFormat?
So make it -J JustPod, or is that parameter list sacrosanct?
> Which also seems a little weird. Maybe Pod::Simple::PodFormat?
Perhaps leave -M, and add -J, which defaults to a value of JustPod.
Karl Williamson
May 8, 2018, 1:00:02 AM5/8/18
to David E. Wheeler, John SJ Anderson, pod-p...@perl.org
On 05/13/2016 12:24 PM, David E. Wheeler wrote:
>
> D
>
The marketing term Biodynamic doesn't seem to have survived the test of
time, at least in my corner of Trumpistan.
So, I converted the name to JustPod, and am trying to finish that up.
I had to suspend work on it a couple of years ago, and am just now able
to get back to it.
Changes to BlackBox were needed.
I left it mostly working, and foolishly didn't leave notes to myself
about what else was needed, so now I'm working on test files in the
distribution to make sure that the pod extraction is working. We have a
bunch of files in the t/corpus directory, and I can see how well this
works on each of them.
One thing that might not ever be precise is retaining the file's white
space, as opposed to squeezing out unnecessary strings of multiple ones
to just one blank.
And I'm running into something that I know I had not previously gotten
as far as (which is encouraging), and I'm writing now for counsel.
What to do about input files that are encoded in some alien encoding,
like Japanese 2202? The Pod::Simple docs say it translates the pod into
perl's internal representation. But should the extracted pod also be in
perl's representation, or should it be translated back to the original
encoding? The second way would be a way to really extract the pod
portions of the original.
But I'm thinking it should be perl's, so that downstream modules can use
it as-is. But I'm open to other reasoned opinions
> On May 13, 2016, at 11:03 AM, Karl Williamson <pub...@khwilliamson.com> wrote:
>
>> If we wanted to be cute, we could call it Pod::Simple::SimplyPod, with you know, only one, natural, ingredient, and no harmful additives.
>
> But is it organic? Or Biodynamic?
>
>> If we wanted to be cute, we could call it Pod::Simple::SimplyPod, with you know, only one, natural, ingredient, and no harmful additives.
>
>
> D
>
The marketing term Biodynamic doesn't seem to have survived the test of
time, at least in my corner of Trumpistan.
So, I converted the name to JustPod, and am trying to finish that up.
I had to suspend work on it a couple of years ago, and am just now able
to get back to it.
Changes to BlackBox were needed.
I left it mostly working, and foolishly didn't leave notes to myself
about what else was needed, so now I'm working on test files in the
distribution to make sure that the pod extraction is working. We have a
bunch of files in the t/corpus directory, and I can see how well this
works on each of them.
One thing that might not ever be precise is retaining the file's white
space, as opposed to squeezing out unnecessary strings of multiple ones
to just one blank.
And I'm running into something that I know I had not previously gotten
as far as (which is encouraging), and I'm writing now for counsel.
What to do about input files that are encoded in some alien encoding,
like Japanese 2202? The Pod::Simple docs say it translates the pod into
perl's internal representation. But should the extracted pod also be in
perl's representation, or should it be translated back to the original
encoding? The second way would be a way to really extract the pod
portions of the original.
But I'm thinking it should be perl's, so that downstream modules can use
it as-is. But I'm open to other reasoned opinions
David E. Wheeler
May 8, 2018, 9:15:02 PM5/8/18
to John SJ Anderson, Karl Williamson, pod-p...@perl.org
On May 8, 2018, at 18:48, John SJ Anderson <jo...@genehack.org> wrote:
> I suspect the plea for counsel was more intended for David, but I’ll pipe up from the peanut gallery and say, “why not both?” It seems like the ideal thing to put under a feature flag.
I’m sorry, I’ve lost all context on this thread after two years. What’s it for again? Flag sounds okay, but better is to use =encoding.
> Of course, that just changes this decision into “which one should be the default and which one should need to be enabled?”, but perhaps thinking about it in those terms will make it more clear which has the higher utility value?
Yeah, whichever is going to be more valuable for your intended audience.
D
> I suspect the plea for counsel was more intended for David, but I’ll pipe up from the peanut gallery and say, “why not both?” It seems like the ideal thing to put under a feature flag.
I’m sorry, I’ve lost all context on this thread after two years. What’s it for again? Flag sounds okay, but better is to use =encoding.
> Of course, that just changes this decision into “which one should be the default and which one should need to be enabled?”, but perhaps thinking about it in those terms will make it more clear which has the higher utility value?
Yeah, whichever is going to be more valuable for your intended audience.
D
Karl Williamson
May 9, 2018, 11:30:02 PM5/9/18
to David E. Wheeler, John SJ Anderson, pod-p...@perl.org
On 05/08/2018 07:05 PM, David E. Wheeler wrote:
> On May 8, 2018, at 18:48, John SJ Anderson <jo...@genehack.org> wrote:
>
>> I suspect the plea for counsel was more intended for David, but I’ll pipe up from the peanut gallery and say, “why not both?” It seems like the ideal thing to put under a feature flag.
Actually, I wasn't thinking specifically of him.
> On May 8, 2018, at 18:48, John SJ Anderson <jo...@genehack.org> wrote:
>
>> I suspect the plea for counsel was more intended for David, but I’ll pipe up from the peanut gallery and say, “why not both?” It seems like the ideal thing to put under a feature flag.
>
> I’m sorry, I’ve lost all context on this thread after two years. What’s it for again? Flag sounds okay, but better is to use =encoding.
This is a new module started by John, to extract the pod portions from
> I’m sorry, I’ve lost all context on this thread after two years. What’s it for again? Flag sounds okay, but better is to use =encoding.
say a .pm. I think he said he thought he got about 80% of it done. Now
I'm completing it. It requires hooks in BlackBox and other .pm's to
enable it to really work.
>
>> Of course, that just changes this decision into “which one should be the default and which one should need to be enabled?”, but perhaps thinking about it in those terms will make it more clear which has the higher utility value?
>
> Yeah, whichever is going to be more valuable for your intended audience.
The intended audience is me initially. So I've decided to write it for
>> Of course, that just changes this decision into “which one should be the default and which one should need to be enabled?”, but perhaps thinking about it in those terms will make it more clear which has the higher utility value?
>
> Yeah, whichever is going to be more valuable for your intended audience.
my use, which wants the results in ASCII or UTF-8.
I think this is as much as I'm prepared to chew on for now, and if
someone else wishes to extend it in the future to have the option John
suggested, I agree it would be nice, and don't think it would be very hard.
John SJ Anderson
May 11, 2018, 7:15:03 PM5/11/18
to Karl Williamson, David E. Wheeler, pod-p...@perl.org
> On May 7, 2018, at 21:52, Karl Williamson <pub...@khwilliamson.com> wrote:
>
> And I'm running into something that I know I had not previously gotten as far as (which is encouraging), and I'm writing now for counsel.
>
> What to do about input files that are encoded in some alien encoding, like Japanese 2202? The Pod::Simple docs say it translates the pod into perl's internal representation. But should the extracted pod also be in perl's representation, or should it be translated back to the original encoding? The second way would be a way to really extract the pod portions of the original.
>
> But I'm thinking it should be perl's, so that downstream modules can use it as-is. But I'm open to other reasoned opinions
I suspect the plea for counsel was more intended for David, but I’ll pipe up from the peanut gallery and say, “why not both?” It seems like the ideal thing to put under a feature flag.
Of course, that just changes this decision into “which one should be the default and which one should need to be enabled?”, but perhaps thinking about it in those terms will make it more clear which has the higher utility value?
j.0 new messages