Re: Pod::Simple output as POD

[John SJ Anderson]

> On May 7, 2018, at 21:52, Karl Williamson  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.

Re: Pod::Simple output as POD

[Karl Williamson]

On 05/08/2018 07:05 PM, David E. Wheeler wrote:

On May 8, 2018, at 18:48, John SJ Anderson  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.


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 
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 
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.

Re: Pod::Simple output as POD

[David E. Wheeler]

On May 8, 2018, at 18:48, John SJ Anderson  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



signature.asc
Description: Message signed with OpenPGP

Re: Pod::Simple output as POD

[Karl Williamson]

On 05/13/2016 12:24 PM, David E. Wheeler wrote:

On May 13, 2016, at 11:03 AM, Karl Williamson  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?

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

Re: Pod::Simple output as POD

[David E. Wheeler]

On May 13, 2016, at 7:00 PM, Ron Savage  wrote:

> So make it -J JustPod, or is that parameter list sacrosanct?
> 
> Perhaps leave -M, and add -J, which defaults to a value of JustPod.

You pass the name of the formatting module to -M. I see no reason to change it.

D

smime.p7s
Description: S/MIME cryptographic signature

Re: Pod::Simple output as POD

[Ron Savage]

Hi David

On 12/05/16 10:39, David E. Wheeler wrote:

On May 11, 2016, at 5:29 PM, Karl Williamson  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

Which also seems a little weird. Maybe Pod::Simple::PodFormat?


So make it -J JustPod, or is that parameter list sacrosanct?

Perhaps leave -M, and add -J, which defaults to a value of JustPod.

--
Ron Savage - savage.net.au

Re: Pod::Simple output as POD

[David E. Wheeler]

On May 13, 2016, at 11:03 AM, Karl Williamson  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?

D



smime.p7s
Description: S/MIME cryptographic signature

Re: Pod::Simple output as POD

[Karl Williamson]

On 05/11/2016 07:38 PM, John SJ Anderson wrote:



On May 11, 2016, at 17:52, Ron Savage  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.


With only a _tiny_ bit of my tongue in my cheek, I’ll throw out 
Pod::Simple::PlainOldPOD ...

8^)

j.



I'm leaning towards Pod::Simple::JustPod.  I think that captures the 
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.

Re: Pod::Simple output as POD

[Ron Savage]

Hi

On 12/05/16 10:39, David E. Wheeler wrote:

On May 11, 2016, at 5:29 PM, Karl Williamson  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

Re: Pod::Simple output as POD

[David E. Wheeler]

On May 11, 2016, at 5:29 PM, Karl Williamson  wrote:

>> 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.)

Probably should have been Pod::Simple::Format::*. :-(

>> 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^)
> 
> It's more a matter of what is the least worst name to help people at a 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.

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

Which also seems a little weird. Maybe Pod::Simple::PodFormat?

Anyway, I’ve no strong opinions.

Best,

David



smime.p7s
Description: S/MIME cryptographic signature