[Pdl-porters] Proposal on how to make PDL related doc available at matacpan.org

[kmx]

Hi,

most of you probably know about incorrectly displayed/parsed documentation
for many PDL modules (as well as PDL core) at https://metacpan.org/

The trouble is that metacpan.org is not able to parse *.pd files into
proper *.pod documentation and to be honest looking at documentation for
PDL related perl modules on metacpan.org or search.cpan.org definitely
distracts potential users. I know that there is some documentation
available at pdl.perl.org but people already using perl (like me) will very
likely first try to look at PDL documentation at metacpan.org and/or
search.cpan.org.

I have made a proof-of-concept experiment with PDL::LinearAlgebra (with
help of Chris):

*/ before experiment there was LinearAlgebra-0.08
- https://metacpan.org/release/CHM/PDL-LinearAlgebra-0.08
- http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08

*/ let's have a look at PDL::LinearAlgebra::Real
- metacpan.org is not able to show any documentation
- search.cpan.org show something but it is "ugly"
http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08/Real/real.pd

*/ after couple of attempts I have ended up with a hack like this
- https://metacpan.org/source/CHM/PDL-LinearAlgebra-0.08_03/Makefile.PL#L23
- In shot: during "make dist" phase it creates "GENERATED" subdirectory
with *.pm files corresponding to *.pd files (no changes in module code,
just one simple GENERATED subdir which is automatically generated)

*/ the final tarball going to CPAN has the following content
- https://metacpan.org/source/CHM/PDL-LinearAlgebra-0.08_03 (see GENERATED
subdir)

*/ with my workaround you can see nice documentation at both:
-
https://metacpan.org/pod/release/CHM/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm
- http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm

*/ The hack is is quite simple if your distribution contains just one *.pd
file like my module PDL::Finance::TA
- Makefile hack:
https://metacpan.org/source/KMX/PDL-Finance-TA-0.008/Makefile.PL#L72
- https://metacpan.org/pod/PDL::Finance::TA
- http://search.cpan.org/perldoc?PDL::Finance::TA
- in distributions with more *.pd files it gets a bit more complicated, but
still doable

My suggestion is to have a discussion whether this hack or something
similar (or maybe something completely different) is OK and declare it as a
"recommended way".

Then:
1/ we should patch PDL (core distribution) to have nice doc at metacpan.org
2/ maybe we can patch PDL/Core/Dev.pm (sub pdlpp_stdargs_int) to generate
proper dist => {PREOP=>'...'} automatically

Opinions?

--
kmx

[David Mertens]

Hey kmx,

In my attempt to solve this problem back in 2013, I added functionality to
PDL::PP that let you pass your documentation to the pp_def function. I
demonstrated the use in bad.pd, as can be seen here:
https://metacpan.org/source/CHM/PDL-2.007/Basic/Bad/bad.pd#L634.
search.cpan.org processes the .pd file and correctly renders the
documentation: http://search.cpan.org/~chm/PDL-2.007/Basic/Bad/bad.pd

bad.pd also illustrates the problem with generating documentation on the
release manager's machine. If you read the documentation on search.cpan.org,
hopefully it'll be clear. The actual code generated for PDL::Bad depends on
whether or not you compiled PDL with bad value support, so the
documentation you get will be different depending on your compilation.

The solution I advocated, before running out of steam on this issue, was to
use FullDocs for all pp_defs in the core, and to change the file extension
from .pd to .xs.PL, which is what it should be anyway.

I would not be opposed to generating documentation on the release manager's
machine as long as we are aware of the limitations.

David

Post by kmx
Hi,
most of you probably know about incorrectly displayed/parsed documentation
for many PDL modules (as well as PDL core) at https://metacpan.org/
The trouble is that metacpan.org is not able to parse *.pd files into
proper *.pod documentation and to be honest looking at documentation for
PDL related perl modules on metacpan.org or search.cpan.org definitely
distracts potential users. I know that there is some documentation
available at pdl.perl.org but people already using perl (like me) will
very likely first try to look at PDL documentation at metacpan.org and/or
search.cpan.org.
I have made a proof-of-concept experiment with PDL::LinearAlgebra (with
*/ before experiment there was LinearAlgebra-0.08
- https://metacpan.org/release/CHM/PDL-LinearAlgebra-0.08
- http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08
*/ let's have a look at PDL::LinearAlgebra::Real
- metacpan.org is not able to show any documentation
- search.cpan.org show something but it is "ugly"
http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08/Real/real.pd
*/ after couple of attempts I have ended up with a hack like this
-
https://metacpan.org/source/CHM/PDL-LinearAlgebra-0.08_03/Makefile.PL#L23
- In shot: during "make dist" phase it creates "GENERATED" subdirectory
with *.pm files corresponding to *.pd files (no changes in module code,
just one simple GENERATED subdir which is automatically generated)
*/ the final tarball going to CPAN has the following content
- https://metacpan.org/source/CHM/PDL-LinearAlgebra-0.08_03 (see
GENERATED subdir)
-
https://metacpan.org/pod/release/CHM/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm
- http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm
*/ The hack is is quite simple if your distribution contains just one *.pd
file like my module PDL::Finance::TA
https://metacpan.org/source/KMX/PDL-Finance-TA-0.008/Makefile.PL#L72
- https://metacpan.org/pod/PDL::Finance::TA
- http://search.cpan.org/perldoc?PDL::Finance::TA
- in distributions with more *.pd files it gets a bit more complicated,
but still doable
My suggestion is to have a discussion whether this hack or something
similar (or maybe something completely different) is OK and declare it as a
"recommended way".
1/ we should patch PDL (core distribution) to have nice doc at
metacpan.org
2/ maybe we can patch PDL/Core/Dev.pm (sub pdlpp_stdargs_int) to generate
proper dist => {PREOP=>'...'} automatically
Opinions?
--
kmx
_______________________________________________
PDL-porters mailing list
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters

[Chris Marshall]

What are FullDocs?

Post by David Mertens
Hey kmx,
In my attempt to solve this problem back in 2013, I added functionality to
PDL::PP that let you pass your documentation to the pp_def function. I
https://metacpan.org/source/CHM/PDL-2.007/Basic/Bad/bad.pd#L634.
search.cpan.org processes the .pd file and correctly renders the
documentation: http://search.cpan.org/~chm/PDL-2.007/Basic/Bad/bad.pd
bad.pd also illustrates the problem with generating documentation on the
release manager's machine. If you read the documentation on
search.cpan.org, hopefully it'll be clear. The actual code generated for
PDL::Bad depends on whether or not you compiled PDL with bad value support,
so the documentation you get will be different depending on your
compilation.
The solution I advocated, before running out of steam on this issue, was
to use FullDocs for all pp_defs in the core, and to change the file
extension from .pd to .xs.PL, which is what it should be anyway.
I would not be opposed to generating documentation on the release
manager's machine as long as we are aware of the limitations.
David

Post by kmx
Hi,
most of you probably know about incorrectly displayed/parsed
documentation for many PDL modules (as well as PDL core) at
https://metacpan.org/
The trouble is that metacpan.org is not able to parse *.pd files into
proper *.pod documentation and to be honest looking at documentation for
PDL related perl modules on metacpan.org or search.cpan.org definitely
distracts potential users. I know that there is some documentation
available at pdl.perl.org but people already using perl (like me) will
very likely first try to look at PDL documentation at metacpan.org
and/or search.cpan.org.
I have made a proof-of-concept experiment with PDL::LinearAlgebra (with
*/ before experiment there was LinearAlgebra-0.08
- https://metacpan.org/release/CHM/PDL-LinearAlgebra-0.08
- http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08
*/ let's have a look at PDL::LinearAlgebra::Real
- metacpan.org is not able to show any documentation
- search.cpan.org show something but it is "ugly"
http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08/Real/real.pd
*/ after couple of attempts I have ended up with a hack like this
-
https://metacpan.org/source/CHM/PDL-LinearAlgebra-0.08_03/Makefile.PL#L23
- In shot: during "make dist" phase it creates "GENERATED" subdirectory
with *.pm files corresponding to *.pd files (no changes in module code,
just one simple GENERATED subdir which is automatically generated)
*/ the final tarball going to CPAN has the following content
- https://metacpan.org/source/CHM/PDL-LinearAlgebra-0.08_03 (see
GENERATED subdir)
-
https://metacpan.org/pod/release/CHM/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm
- http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm
*/ The hack is is quite simple if your distribution contains just one
*.pd file like my module PDL::Finance::TA
https://metacpan.org/source/KMX/PDL-Finance-TA-0.008/Makefile.PL#L72
- https://metacpan.org/pod/PDL::Finance::TA
- http://search.cpan.org/perldoc?PDL::Finance::TA
- in distributions with more *.pd files it gets a bit more complicated,
but still doable
My suggestion is to have a discussion whether this hack or something
similar (or maybe something completely different) is OK and declare it as a
"recommended way".
1/ we should patch PDL (core distribution) to have nice doc at metacpan.org
2/ maybe we can patch PDL/Core/Dev.pm (sub pdlpp_stdargs_int) to generate
proper dist => {PREOP=>'...'} automatically
Opinions?
--
kmx
_______________________________________________
PDL-porters mailing list
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters

--
"Debugging is twice as hard as writing the code in the first place.
Therefore, if you write the code as cleverly as possible, you are,
by definition, not smart enough to debug it." -- Brian Kernighan
_______________________________________________
PDL-porters mailing list
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters

[David Mertens]

The FullDoc field is a way to specify all of the documentation for a given
PDL::PP-generated function, rather than having PDL::PP generate it for you.
It also supports extraction of Pars and OtherPars directly from said
documentation. You can specify this key explicitly or it is also detected
if there are multiple lines in the function's "name", i.e. the first
argument to pp_def. See
https://metacpan.org/source/CHM/PDL-2.007/Basic/Gen/PP.pm#L1119

You can have the machinery extract the Pars field from the FullDoc field (
https://metacpan.org/source/CHM/PDL-2.007/Basic/Gen/PP.pm#L2978), and also
have it extract the OtherPars field from the FullDoc field (
https://metacpan.org/source/CHM/PDL-2.007/Basic/Gen/PP.pm#L2982). It will
only perform those extractions if you have not provided those fields
yourself, i.e. you can override them in your call to pp_def.

These functionalities do not make FullDoc an immediate POD fixup. But, you
can sprinkle POD into the FullDoc text, and when it's scanned by the CPAN
indexers, it gets picked up as documentation.

David

Post by Chris Marshall
What are FullDocs?

Post by David Mertens
Hey kmx,
In my attempt to solve this problem back in 2013, I added functionality
to PDL::PP that let you pass your documentation to the pp_def function. I
https://metacpan.org/source/CHM/PDL-2.007/Basic/Bad/bad.pd#L634.
search.cpan.org processes the .pd file and correctly renders the
documentation: http://search.cpan.org/~chm/PDL-2.007/Basic/Bad/bad.pd
bad.pd also illustrates the problem with generating documentation on the
release manager's machine. If you read the documentation on
search.cpan.org, hopefully it'll be clear. The actual code generated for
PDL::Bad depends on whether or not you compiled PDL with bad value support,
so the documentation you get will be different depending on your
compilation.
The solution I advocated, before running out of steam on this issue, was
to use FullDocs for all pp_defs in the core, and to change the file
extension from .pd to .xs.PL, which is what it should be anyway.
I would not be opposed to generating documentation on the release
manager's machine as long as we are aware of the limitations.
David

Post by kmx
Hi,
most of you probably know about incorrectly displayed/parsed
documentation for many PDL modules (as well as PDL core) at
https://metacpan.org/
The trouble is that metacpan.org is not able to parse *.pd files into
proper *.pod documentation and to be honest looking at documentation for
PDL related perl modules on metacpan.org or search.cpan.org definitely
distracts potential users. I know that there is some documentation
available at pdl.perl.org but people already using perl (like me) will
very likely first try to look at PDL documentation at metacpan.org
and/or search.cpan.org.
I have made a proof-of-concept experiment with PDL::LinearAlgebra (with
*/ before experiment there was LinearAlgebra-0.08
- https://metacpan.org/release/CHM/PDL-LinearAlgebra-0.08
- http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08
*/ let's have a look at PDL::LinearAlgebra::Real
- metacpan.org is not able to show any documentation
- search.cpan.org show something but it is "ugly"
http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08/Real/real.pd
*/ after couple of attempts I have ended up with a hack like this
-
https://metacpan.org/source/CHM/PDL-LinearAlgebra-0.08_03/Makefile.PL#L23
- In shot: during "make dist" phase it creates "GENERATED" subdirectory
with *.pm files corresponding to *.pd files (no changes in module code,
just one simple GENERATED subdir which is automatically generated)
*/ the final tarball going to CPAN has the following content
- https://metacpan.org/source/CHM/PDL-LinearAlgebra-0.08_03 (see
GENERATED subdir)
-
https://metacpan.org/pod/release/CHM/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm
-
http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm
*/ The hack is is quite simple if your distribution contains just one
*.pd file like my module PDL::Finance::TA
https://metacpan.org/source/KMX/PDL-Finance-TA-0.008/Makefile.PL#L72
- https://metacpan.org/pod/PDL::Finance::TA
- http://search.cpan.org/perldoc?PDL::Finance::TA
- in distributions with more *.pd files it gets a bit more complicated,
but still doable
My suggestion is to have a discussion whether this hack or something
similar (or maybe something completely different) is OK and declare it as a
"recommended way".
1/ we should patch PDL (core distribution) to have nice doc at metacpan.org
2/ maybe we can patch PDL/Core/Dev.pm (sub pdlpp_stdargs_int) to
generate proper dist => {PREOP=>'...'} automatically
Opinions?
--
kmx
_______________________________________________
PDL-porters mailing list
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters

--
"Debugging is twice as hard as writing the code in the first place.
Therefore, if you write the code as cleverly as possible, you are,
by definition, not smart enough to debug it." -- Brian Kernighan
_______________________________________________
PDL-porters mailing list
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters

[David Mertens]

kmx,

I think that for 95% of use cases, your pre-generated documentation would
work just fine. However, how would you use this system to provide
documentation for bad.pd?

David

Post by David Mertens
The FullDoc field is a way to specify all of the documentation for a given
PDL::PP-generated function, rather than having PDL::PP generate it for you.
It also supports extraction of Pars and OtherPars directly from said
documentation. You can specify this key explicitly or it is also detected
if there are multiple lines in the function's "name", i.e. the first
argument to pp_def. See
https://metacpan.org/source/CHM/PDL-2.007/Basic/Gen/PP.pm#L1119
You can have the machinery extract the Pars field from the FullDoc field (
https://metacpan.org/source/CHM/PDL-2.007/Basic/Gen/PP.pm#L2978), and
also have it extract the OtherPars field from the FullDoc field (
https://metacpan.org/source/CHM/PDL-2.007/Basic/Gen/PP.pm#L2982). It will
only perform those extractions if you have not provided those fields
yourself, i.e. you can override them in your call to pp_def.
These functionalities do not make FullDoc an immediate POD fixup. But, you
can sprinkle POD into the FullDoc text, and when it's scanned by the CPAN
indexers, it gets picked up as documentation.
David

Post by Chris Marshall
What are FullDocs?

Post by David Mertens
Hey kmx,
In my attempt to solve this problem back in 2013, I added functionality
to PDL::PP that let you pass your documentation to the pp_def function. I
https://metacpan.org/source/CHM/PDL-2.007/Basic/Bad/bad.pd#L634.
search.cpan.org processes the .pd file and correctly renders the
documentation: http://search.cpan.org/~chm/PDL-2.007/Basic/Bad/bad.pd
bad.pd also illustrates the problem with generating documentation on the
release manager's machine. If you read the documentation on
search.cpan.org, hopefully it'll be clear. The actual code generated
for PDL::Bad depends on whether or not you compiled PDL with bad value
support, so the documentation you get will be different depending on your
compilation.
The solution I advocated, before running out of steam on this issue, was
to use FullDocs for all pp_defs in the core, and to change the file
extension from .pd to .xs.PL, which is what it should be anyway.
I would not be opposed to generating documentation on the release
manager's machine as long as we are aware of the limitations.
David

Post by kmx
Hi,
most of you probably know about incorrectly displayed/parsed
documentation for many PDL modules (as well as PDL core) at
https://metacpan.org/
The trouble is that metacpan.org is not able to parse *.pd files into
proper *.pod documentation and to be honest looking at documentation for
PDL related perl modules on metacpan.org or search.cpan.org definitely
distracts potential users. I know that there is some documentation
available at pdl.perl.org but people already using perl (like me) will
very likely first try to look at PDL documentation at metacpan.org
and/or search.cpan.org.
I have made a proof-of-concept experiment with PDL::LinearAlgebra (with
*/ before experiment there was LinearAlgebra-0.08
- https://metacpan.org/release/CHM/PDL-LinearAlgebra-0.08
- http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08
*/ let's have a look at PDL::LinearAlgebra::Real
- metacpan.org is not able to show any documentation
- search.cpan.org show something but it is "ugly"
http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08/Real/real.pd
*/ after couple of attempts I have ended up with a hack like this
-
https://metacpan.org/source/CHM/PDL-LinearAlgebra-0.08_03/Makefile.PL#L23
- In shot: during "make dist" phase it creates "GENERATED" subdirectory
with *.pm files corresponding to *.pd files (no changes in module code,
just one simple GENERATED subdir which is automatically generated)
*/ the final tarball going to CPAN has the following content
- https://metacpan.org/source/CHM/PDL-LinearAlgebra-0.08_03 (see
GENERATED subdir)
-
https://metacpan.org/pod/release/CHM/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm
-
http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm
*/ The hack is is quite simple if your distribution contains just one
*.pd file like my module PDL::Finance::TA
https://metacpan.org/source/KMX/PDL-Finance-TA-0.008/Makefile.PL#L72
- https://metacpan.org/pod/PDL::Finance::TA
- http://search.cpan.org/perldoc?PDL::Finance::TA
- in distributions with more *.pd files it gets a bit more complicated,
but still doable
My suggestion is to have a discussion whether this hack or something
similar (or maybe something completely different) is OK and declare it as a
"recommended way".
1/ we should patch PDL (core distribution) to have nice doc at metacpan.org
2/ maybe we can patch PDL/Core/Dev.pm (sub pdlpp_stdargs_int) to
generate proper dist => {PREOP=>'...'} automatically
Opinions?
--
kmx
_______________________________________________
PDL-porters mailing list
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters

--
"Debugging is twice as hard as writing the code in the first place.
Therefore, if you write the code as cleverly as possible, you are,
by definition, not smart enough to debug it." -- Brian Kernighan
_______________________________________________
PDL-porters mailing list
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters

--
"Debugging is twice as hard as writing the code in the first place.
Therefore, if you write the code as cleverly as possible, you are,
by definition, not smart enough to debug it." -- Brian Kernighan

[kmx]

David,

my latest version produces the following GENERATED/PDL/Bad.pm
https://gist.github.com/kmx/f24248b0c5dfe369b299

Of course if the documentation is different depending on build options (bad
value support or not) it is a problem. But it is a general problem, what do
we want to have as an on-line documentation in these cases?

My opinioun is that if we have a given module in a given version the user
shout get the same documentation regardless the source he uses (pdldoc,
perldoc, man, metacpan.org, search.cpan.org, pdl.perl.org). For example I
mostly use on-line metacpan.org instead of local perldoc - and many other
people will do the same (which is the reason why I would like to see nice
PDL doc on metacpan :)

--
kmx

Post by David Mertens
kmx,
I think that for 95% of use cases, your pre-generated documentation would
work just fine. However, how would you use this system to provide
documentation for bad.pd?
David
The FullDoc field is a way to specify all of the documentation for a
given PDL::PP-generated function, rather than having PDL::PP generate
it for you. It also supports extraction of Pars and OtherPars
directly from said documentation. You can specify this key explicitly
or it is also detected if there are multiple lines in the function's
"name", i.e. the first argument to pp_def. See
https://metacpan.org/source/CHM/PDL-2.007/Basic/Gen/PP.pm#L1119
You can have the machinery extract the Pars field from the FullDoc
field
(https://metacpan.org/source/CHM/PDL-2.007/Basic/Gen/PP.pm#L2978),
and also have it extract the OtherPars field from the FullDoc field
(https://metacpan.org/source/CHM/PDL-2.007/Basic/Gen/PP.pm#L2982). It
will only perform those extractions if you have not provided those
fields yourself, i.e. you can override them in your call to pp_def.
These functionalities do not make FullDoc an immediate POD fixup.
But, you can sprinkle POD into the FullDoc text, and when it's
scanned by the CPAN indexers, it gets picked up as documentation.
David
On Thu, Dec 18, 2014 at 9:22 AM, Chris Marshall
What are FullDocs?
On Thu, Dec 18, 2014 at 8:56 AM, David Mertens
Hey kmx,
In my attempt to solve this problem back in 2013, I added
functionality to PDL::PP that let you pass your documentation
to the pp_def function. I demonstrated the use in bad.pd, as
https://metacpan.org/source/CHM/PDL-2.007/Basic/Bad/bad.pd#L634.
search.cpan.org <http://search.cpan.org> processes the .pd
http://search.cpan.org/~chm/PDL-2.007/Basic/Bad/bad.pd
<http://search.cpan.org/%7Echm/PDL-2.007/Basic/Bad/bad.pd>
bad.pd also illustrates the problem with generating
documentation on the release manager's machine. If you read
the documentation on search.cpan.org
<http://search.cpan.org>, hopefully it'll be clear. The
actual code generated for PDL::Bad depends on whether or not
you compiled PDL with bad value support, so the documentation
you get will be different depending on your compilation.
The solution I advocated, before running out of steam on this
issue, was to use FullDocs for all pp_defs in the core, and
to change the file extension from .pd to .xs.PL, which is
what it should be anyway.
I would not be opposed to generating documentation on the
release manager's machine as long as we are aware of the
limitations.
David
Hi,
most of you probably know about incorrectly
displayed/parsed documentation for many PDL modules (as
well as PDL core) at https://metacpan.org/
The trouble is that metacpan.org <http://metacpan.org> is
not able to parse *.pd files into proper *.pod
documentation and to be honest looking at documentation
for PDL related perl modules on metacpan.org
<http://metacpan.org> or search.cpan.org
<http://search.cpan.org> definitely distracts potential
users. I know that there is some documentation available
at pdl.perl.org <http://pdl.perl.org> but people already
using perl (like me) will very likely first try to look
at PDL documentation at metacpan.org
<http://metacpan.org> and/or search.cpan.org
<http://search.cpan.org>.
I have made a proof-of-concept experiment with
*/ before experiment there was LinearAlgebra-0.08
- https://metacpan.org/release/CHM/PDL-LinearAlgebra-0.08
- http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08
<http://search.cpan.org/%7Echm/PDL-LinearAlgebra-0.08>
*/ let's have a look at PDL::LinearAlgebra::Real
- metacpan.org <http://metacpan.org> is not able to show
any documentation
- search.cpan.org <http://search.cpan.org> show something
but it is "ugly"
http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08/Real/real.pd
<http://search.cpan.org/%7Echm/PDL-LinearAlgebra-0.08/Real/real.pd>
*/ after couple of attempts I have ended up with a hack
like this
-
https://metacpan.org/source/CHM/PDL-LinearAlgebra-0.08_03/Makefile.PL#L23
- In shot: during "make dist" phase it creates
"GENERATED" subdirectory with *.pm files corresponding to
*.pd files (no changes in module code, just one simple
GENERATED subdir which is automatically generated)
*/ the final tarball going to CPAN has the following content
-
https://metacpan.org/source/CHM/PDL-LinearAlgebra-0.08_03
(see GENERATED subdir)
-
https://metacpan.org/pod/release/CHM/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm
-
http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm
<http://search.cpan.org/%7Echm/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm>
*/ The hack is is quite simple if your distribution
contains just one *.pd file like my module PDL::Finance::TA
https://metacpan.org/source/KMX/PDL-Finance-TA-0.008/Makefile.PL#L72
- https://metacpan.org/pod/PDL::Finance::TA
- http://search.cpan.org/perldoc?PDL::Finance::TA
- in distributions with more *.pd files it gets a bit
more complicated, but still doable
My suggestion is to have a discussion whether this hack
or something similar (or maybe something completely
different) is OK and declare it as a "recommended way".
1/ we should patch PDL (core distribution) to have nice
doc at metacpan.org <http://metacpan.org>
2/ maybe we can patch PDL/Core/Dev.pm (sub
pdlpp_stdargs_int) to generate proper dist =>
{PREOP=>'...'} automatically
Opinions?
--
kmx
_______________________________________________
PDL-porters mailing list
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters
--
"Debugging is twice as hard as writing the code in the first
place.
Therefore, if you write the code as cleverly as possible,
you are,
by definition, not smart enough to debug it." -- Brian Kernighan
_______________________________________________
PDL-porters mailing list
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters
--
"Debugging is twice as hard as writing the code in the first place.
Therefore, if you write the code as cleverly as possible, you are,
by definition, not smart enough to debug it." -- Brian Kernighan
--
"Debugging is twice as hard as writing the code in the first place.
Therefore, if you write the code as cleverly as possible, you are,
by definition, not smart enough to debug it." -- Brian Kernighan

[David Mertens]

At the moment, search.cpan.org (which does render the pod in .pd files) has
documentation for *both* possibilities:

http://search.cpan.org/~chm/PDL-2.007/Basic/Bad/bad.pd

It even tells the reader at the top of the document "What you are reading
is the pod documentation as extracted directly from the .pd file, which is
not what you will see reported on your own machine. (I'm guessing you're
reading this from CPAN.)"

Should we special case this sort of documentation? I doubt it. In the very
least, if we go the auto-generated route, it would make a lot of sense to
re-clean-up the .pd files that I worked on, including bad.pd and slices.pd.
The underlying .pd code is somewhat obfuscated from my efforts to get them
to render properly.

David

Post by kmx
David,
my latest version produces the following GENERATED/PDL/Bad.pm
https://gist.github.com/kmx/f24248b0c5dfe369b299
Of course if the documentation is different depending on build options
(bad value support or not) it is a problem. But it is a general problem,
what do we want to have as an on-line documentation in these cases?
My opinioun is that if we have a given module in a given version the user
shout get the same documentation regardless the source he uses (pdldoc,
perldoc, man, metacpan.org, search.cpan.org, pdl.perl.org). For example I
mostly use on-line metacpan.org instead of local perldoc - and many other
people will do the same (which is the reason why I would like to see nice
PDL doc on metacpan :)
--
kmx
kmx,
I think that for 95% of use cases, your pre-generated documentation would
work just fine. However, how would you use this system to provide
documentation for bad.pd?
David

Post by David Mertens
The FullDoc field is a way to specify all of the documentation for a
given PDL::PP-generated function, rather than having PDL::PP generate it
for you. It also supports extraction of Pars and OtherPars directly from
said documentation. You can specify this key explicitly or it is also
detected if there are multiple lines in the function's "name", i.e. the
first argument to pp_def. See
https://metacpan.org/source/CHM/PDL-2.007/Basic/Gen/PP.pm#L1119
You can have the machinery extract the Pars field from the FullDoc field
(https://metacpan.org/source/CHM/PDL-2.007/Basic/Gen/PP.pm#L2978), and
also have it extract the OtherPars field from the FullDoc field (
https://metacpan.org/source/CHM/PDL-2.007/Basic/Gen/PP.pm#L2982). It
will only perform those extractions if you have not provided those fields
yourself, i.e. you can override them in your call to pp_def.
These functionalities do not make FullDoc an immediate POD fixup. But,
you can sprinkle POD into the FullDoc text, and when it's scanned by the
CPAN indexers, it gets picked up as documentation.
David

Post by Chris Marshall
What are FullDocs?

Post by David Mertens
Hey kmx,
In my attempt to solve this problem back in 2013, I added functionality
to PDL::PP that let you pass your documentation to the pp_def function. I
https://metacpan.org/source/CHM/PDL-2.007/Basic/Bad/bad.pd#L634.
search.cpan.org processes the .pd file and correctly renders the
documentation: http://search.cpan.org/~chm/PDL-2.007/Basic/Bad/bad.pd
bad.pd also illustrates the problem with generating documentation on
the release manager's machine. If you read the documentation on
search.cpan.org, hopefully it'll be clear. The actual code generated
for PDL::Bad depends on whether or not you compiled PDL with bad value
support, so the documentation you get will be different depending on your
compilation.
The solution I advocated, before running out of steam on this issue,
was to use FullDocs for all pp_defs in the core, and to change the file
extension from .pd to .xs.PL, which is what it should be anyway.
I would not be opposed to generating documentation on the release
manager's machine as long as we are aware of the limitations.
David

Post by kmx
Hi,
most of you probably know about incorrectly displayed/parsed
documentation for many PDL modules (as well as PDL core) at
https://metacpan.org/
The trouble is that metacpan.org is not able to parse *.pd files into
proper *.pod documentation and to be honest looking at documentation for
PDL related perl modules on metacpan.org or search.cpan.org
definitely distracts potential users. I know that there is some
documentation available at pdl.perl.org but people already using perl
(like me) will very likely first try to look at PDL documentation at
metacpan.org and/or search.cpan.org.
I have made a proof-of-concept experiment with PDL::LinearAlgebra
*/ before experiment there was LinearAlgebra-0.08
- https://metacpan.org/release/CHM/PDL-LinearAlgebra-0.08
- http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08
*/ let's have a look at PDL::LinearAlgebra::Real
- metacpan.org is not able to show any documentation
- search.cpan.org show something but it is "ugly"
http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08/Real/real.pd
*/ after couple of attempts I have ended up with a hack like this
-
https://metacpan.org/source/CHM/PDL-LinearAlgebra-0.08_03/Makefile.PL#L23
- In shot: during "make dist" phase it creates "GENERATED"
subdirectory with *.pm files corresponding to *.pd files (no changes in
module code, just one simple GENERATED subdir which is automatically
generated)
*/ the final tarball going to CPAN has the following content
- https://metacpan.org/source/CHM/PDL-LinearAlgebra-0.08_03 (see
GENERATED subdir)
-
https://metacpan.org/pod/release/CHM/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm
-
http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm
*/ The hack is is quite simple if your distribution contains just one
*.pd file like my module PDL::Finance::TA
https://metacpan.org/source/KMX/PDL-Finance-TA-0.008/Makefile.PL#L72
- https://metacpan.org/pod/PDL::Finance::TA
- http://search.cpan.org/perldoc?PDL::Finance::TA
- in distributions with more *.pd files it gets a bit more
complicated, but still doable
My suggestion is to have a discussion whether this hack or something
similar (or maybe something completely different) is OK and declare it as a
"recommended way".
1/ we should patch PDL (core distribution) to have nice doc at metacpan.org
2/ maybe we can patch PDL/Core/Dev.pm (sub pdlpp_stdargs_int) to
generate proper dist => {PREOP=>'...'} automatically
Opinions?
--
kmx
_______________________________________________
PDL-porters mailing list
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters

--
"Debugging is twice as hard as writing the code in the first place.
Therefore, if you write the code as cleverly as possible, you are,
by definition, not smart enough to debug it." -- Brian Kernighan
_______________________________________________
PDL-porters mailing list
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters

--
"Debugging is twice as hard as writing the code in the first place.
Therefore, if you write the code as cleverly as possible, you are,
by definition, not smart enough to debug it." -- Brian Kernighan

--
"Debugging is twice as hard as writing the code in the first place.
Therefore, if you write the code as cleverly as possible, you are,
by definition, not smart enough to debug it." -- Brian Kernighan

[kmx]

The safest way is IMHO to render a *.pm file (with pod documentation)
exactly as it is rendered during module installation because only in that
case we can be sure that we have the same documentation for all the
following cases:
- locally: perldoc PDL::Bad
- locally: pdldoc PDL::Bad
- locally: man PDL::Bad
- online: https://metacpan.org/pod/PDL::Bad
- online: http://search.cpan.org/perldoc?PDL::Bad
- online: http://pdl.perl.org/?docs=Bad&title=PDL::Bad
- etc.

--
kmx

At the moment, search.cpan.org <http://search.cpan.org> (which does
http://search.cpan.org/~chm/PDL-2.007/Basic/Bad/bad.pd
<http://search.cpan.org/%7Echm/PDL-2.007/Basic/Bad/bad.pd>
It even tells the reader at the top of the document "What you are reading
is the pod documentation as extracted directly from the .pd file, which
is not what you will see reported on your own machine. (I'm guessing
you're reading this from CPAN.)"
Should we special case this sort of documentation? I doubt it. In the
very least, if we go the auto-generated route, it would make a lot of
sense to re-clean-up the .pd files that I worked on, including bad.pd and
slices.pd. The underlying .pd code is somewhat obfuscated from my efforts
to get them to render properly.
David
David,
my latest version produces the following GENERATED/PDL/Bad.pm
https://gist.github.com/kmx/f24248b0c5dfe369b299
Of course if the documentation is different depending on build
options (bad value support or not) it is a problem. But it is a
general problem, what do we want to have as an on-line documentation
in these cases?
My opinioun is that if we have a given module in a given version the
user shout get the same documentation regardless the source he uses
(pdldoc, perldoc, man, metacpan.org <http://metacpan.org>,
search.cpan.org <http://search.cpan.org>, pdl.perl.org
<http://pdl.perl.org>). For example I mostly use on-line metacpan.org
<http://metacpan.org> instead of local perldoc - and many other
people will do the same (which is the reason why I would like to see
nice PDL doc on metacpan :)
--
kmx

Post by David Mertens
kmx,
I think that for 95% of use cases, your pre-generated documentation
would work just fine. However, how would you use this system to
provide documentation for bad.pd?
David
On Thu, Dec 18, 2014 at 7:52 PM, David Mertens
The FullDoc field is a way to specify all of the documentation
for a given PDL::PP-generated function, rather than having
PDL::PP generate it for you. It also supports extraction of Pars
and OtherPars directly from said documentation. You can specify
this key explicitly or it is also detected if there are multiple
lines in the function's "name", i.e. the first argument to
pp_def. See
https://metacpan.org/source/CHM/PDL-2.007/Basic/Gen/PP.pm#L1119
You can have the machinery extract the Pars field from the FullDoc field
(https://metacpan.org/source/CHM/PDL-2.007/Basic/Gen/PP.pm#L2978),
and also have it extract the OtherPars field from the FullDoc field
(https://metacpan.org/source/CHM/PDL-2.007/Basic/Gen/PP.pm#L2982).
It will only perform those extractions if you have not provided
those fields yourself, i.e. you can override them in your call
to pp_def.
These functionalities do not make FullDoc an immediate POD
fixup. But, you can sprinkle POD into the FullDoc text, and when
it's scanned by the CPAN indexers, it gets picked up as
documentation.
David
On Thu, Dec 18, 2014 at 9:22 AM, Chris Marshall
What are FullDocs?
On Thu, Dec 18, 2014 at 8:56 AM, David Mertens
Hey kmx,
In my attempt to solve this problem back in 2013, I
added functionality to PDL::PP that let you pass your
documentation to the pp_def function. I demonstrated the
https://metacpan.org/source/CHM/PDL-2.007/Basic/Bad/bad.pd#L634.
search.cpan.org <http://search.cpan.org> processes the
http://search.cpan.org/~chm/PDL-2.007/Basic/Bad/bad.pd
<http://search.cpan.org/%7Echm/PDL-2.007/Basic/Bad/bad.pd>
bad.pd also illustrates the problem with generating
documentation on the release manager's machine. If you
read the documentation on search.cpan.org
<http://search.cpan.org>, hopefully it'll be clear. The
actual code generated for PDL::Bad depends on whether or
not you compiled PDL with bad value support, so the
documentation you get will be different depending on
your compilation.
The solution I advocated, before running out of steam on
this issue, was to use FullDocs for all pp_defs in the
core, and to change the file extension from .pd to
.xs.PL, which is what it should be anyway.
I would not be opposed to generating documentation on
the release manager's machine as long as we are aware of
the limitations.
David
Hi,
most of you probably know about incorrectly
displayed/parsed documentation for many PDL modules
(as well as PDL core) at https://metacpan.org/
The trouble is that metacpan.org
<http://metacpan.org> is not able to parse *.pd
files into proper *.pod documentation and to be
honest looking at documentation for PDL related perl
modules on metacpan.org <http://metacpan.org> or
search.cpan.org <http://search.cpan.org> definitely
distracts potential users. I know that there is some
documentation available at pdl.perl.org
<http://pdl.perl.org> but people already using perl
(like me) will very likely first try to look at PDL
documentation at metacpan.org <http://metacpan.org>
and/or search.cpan.org <http://search.cpan.org>.
I have made a proof-of-concept experiment with
*/ before experiment there was LinearAlgebra-0.08
-
https://metacpan.org/release/CHM/PDL-LinearAlgebra-0.08
- http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08
<http://search.cpan.org/%7Echm/PDL-LinearAlgebra-0.08>
*/ let's have a look at PDL::LinearAlgebra::Real
- metacpan.org <http://metacpan.org> is not able to
show any documentation
- search.cpan.org <http://search.cpan.org> show
something but it is "ugly"
http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08/Real/real.pd
<http://search.cpan.org/%7Echm/PDL-LinearAlgebra-0.08/Real/real.pd>
*/ after couple of attempts I have ended up with a
hack like this
-
https://metacpan.org/source/CHM/PDL-LinearAlgebra-0.08_03/Makefile.PL#L23
- In shot: during "make dist" phase it creates
"GENERATED" subdirectory with *.pm files
corresponding to *.pd files (no changes in module
code, just one simple GENERATED subdir which is
automatically generated)
*/ the final tarball going to CPAN has the following
content
-
https://metacpan.org/source/CHM/PDL-LinearAlgebra-0.08_03
(see GENERATED subdir)
*/ with my workaround you can see nice documentation
-
https://metacpan.org/pod/release/CHM/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm
-
http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm
<http://search.cpan.org/%7Echm/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm>
*/ The hack is is quite simple if your distribution
contains just one *.pd file like my module
PDL::Finance::TA
https://metacpan.org/source/KMX/PDL-Finance-TA-0.008/Makefile.PL#L72
- https://metacpan.org/pod/PDL::Finance::TA
- http://search.cpan.org/perldoc?PDL::Finance::TA
- in distributions with more *.pd files it gets a
bit more complicated, but still doable
My suggestion is to have a discussion whether this
hack or something similar (or maybe something
completely different) is OK and declare it as a
"recommended way".
1/ we should patch PDL (core distribution) to have
nice doc at metacpan.org <http://metacpan.org>
2/ maybe we can patch PDL/Core/Dev.pm (sub
pdlpp_stdargs_int) to generate proper dist =>
{PREOP=>'...'} automatically
Opinions?
--
kmx
_______________________________________________
PDL-porters mailing list
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters
--
"Debugging is twice as hard as writing the code in the
first place.
Therefore, if you write the code as cleverly as
possible, you are,
by definition, not smart enough to debug it." -- Brian
Kernighan
_______________________________________________
PDL-porters mailing list
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters
--
"Debugging is twice as hard as writing the code in the first place.
Therefore, if you write the code as cleverly as possible, you are,
by definition, not smart enough to debug it." -- Brian Kernighan
--
"Debugging is twice as hard as writing the code in the first place.
Therefore, if you write the code as cleverly as possible, you are,
by definition, not smart enough to debug it." -- Brian Kernighan

--
"Debugging is twice as hard as writing the code in the first place.
Therefore, if you write the code as cleverly as possible, you are,
by definition, not smart enough to debug it." -- Brian Kernighan

[Ed .]

I am baffled by the idea of documentation varying based on config options, beyond maybe, just maybe, having a note on the options’ values there.

From: David Mertens
Sent: Friday, December 19, 2014 1:59 AM
To: kmx
Cc: Chris Marshall ; pdl-porters
Subject: Re: [Pdl-porters] Proposal on how to make PDL related doc available at matacpan.org

At the moment, search.cpan.org (which does render the pod in .pd files) has documentation for *both* possibilities:

http://search.cpan.org/~chm/PDL-2.007/Basic/Bad/bad.pd


It even tells the reader at the top of the document "What you are reading is the pod documentation as extracted directly from the .pd file, which is not what you will see reported on your own machine. (I'm guessing you're reading this from CPAN.)"


Should we special case this sort of documentation? I doubt it. In the very least, if we go the auto-generated route, it would make a lot of sense to re-clean-up the .pd files that I worked on, including bad.pd and slices.pd. The underlying .pd code is somewhat obfuscated from my efforts to get them to render properly.


David


On Thu, Dec 18, 2014 at 8:29 PM, kmx <***@atlas.cz> wrote:
David,

my latest version produces the following GENERATED/PDL/Bad.pm
https://gist.github.com/kmx/f24248b0c5dfe369b299

Of course if the documentation is different depending on build options (bad value support or not) it is a problem. But it is a general problem, what do we want to have as an on-line documentation in these cases?

My opinioun is that if we have a given module in a given version the user shout get the same documentation regardless the source he uses (pdldoc, perldoc, man, metacpan.org, search.cpan.org, pdl.perl.org). For example I mostly use on-line metacpan.org instead of local perldoc - and many other people will do the same (which is the reason why I would like to see nice PDL doc on metacpan :)

--
kmx



On 19.12.2014 1:54, David Mertens wrote:

kmx,

I think that for 95% of use cases, your pre-generated documentation would work just fine. However, how would you use this system to provide documentation for bad.pd?


David

On Thu, Dec 18, 2014 at 7:52 PM, David Mertens <***@gmail.com> wrote:
The FullDoc field is a way to specify all of the documentation for a given PDL::PP-generated function, rather than having PDL::PP generate it for you. It also supports extraction of Pars and OtherPars directly from said documentation. You can specify this key explicitly or it is also detected if there are multiple lines in the function's "name", i.e. the first argument to pp_def. See https://metacpan.org/source/CHM/PDL-2.007/Basic/Gen/PP.pm#L1119


You can have the machinery extract the Pars field from the FullDoc field (https://metacpan.org/source/CHM/PDL-2.007/Basic/Gen/PP.pm#L2978), and also have it extract the OtherPars field from the FullDoc field (https://metacpan.org/source/CHM/PDL-2.007/Basic/Gen/PP.pm#L2982). It will only perform those extractions if you have not provided those fields yourself, i.e. you can override them in your call to pp_def.


These functionalities do not make FullDoc an immediate POD fixup. But, you can sprinkle POD into the FullDoc text, and when it's scanned by the CPAN indexers, it gets picked up as documentation.


David


On Thu, Dec 18, 2014 at 9:22 AM, Chris Marshall <***@gmail.com> wrote:
What are FullDocs?


On Thu, Dec 18, 2014 at 8:56 AM, David Mertens <***@gmail.com> wrote:
Hey kmx,

In my attempt to solve this problem back in 2013, I added functionality to PDL::PP that let you pass your documentation to the pp_def function. I demonstrated the use in bad.pd, as can be seen here: https://metacpan.org/source/CHM/PDL-2.007/Basic/Bad/bad.pd#L634. search.cpan.org processes the .pd file and correctly renders the documentation: http://search.cpan.org/~chm/PDL-2.007/Basic/Bad/bad.pd


bad.pd also illustrates the problem with generating documentation on the release manager's machine. If you read the documentation on search.cpan.org, hopefully it'll be clear. The actual code generated for PDL::Bad depends on whether or not you compiled PDL with bad value support, so the documentation you get will be different depending on your compilation.


The solution I advocated, before running out of steam on this issue, was to use FullDocs for all pp_defs in the core, and to change the file extension from .pd to .xs.PL, which is what it should be anyway.


I would not be opposed to generating documentation on the release manager's machine as long as we are aware of the limitations.

David


On Thu, Dec 18, 2014 at 3:51 AM, kmx <***@atlas.cz> wrote:
Hi,

most of you probably know about incorrectly displayed/parsed documentation for many PDL modules (as well as PDL core) at https://metacpan.org/

The trouble is that metacpan.org is not able to parse *.pd files into proper *.pod documentation and to be honest looking at documentation for PDL related perl modules on metacpan.org or search.cpan.org definitely distracts potential users. I know that there is some documentation available at pdl.perl.org but people already using perl (like me) will very likely first try to look at PDL documentation at metacpan.org and/or search.cpan.org.

I have made a proof-of-concept experiment with PDL::LinearAlgebra (with help of Chris):

*/ before experiment there was LinearAlgebra-0.08
- https://metacpan.org/release/CHM/PDL-LinearAlgebra-0.08
- http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08

*/ let's have a look at PDL::LinearAlgebra::Real
- metacpan.org is not able to show any documentation
- search.cpan.org show something but it is "ugly" http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08/Real/real.pd

*/ after couple of attempts I have ended up with a hack like this
- https://metacpan.org/source/CHM/PDL-LinearAlgebra-0.08_03/Makefile.PL#L23
- In shot: during "make dist" phase it creates "GENERATED" subdirectory with *.pm files corresponding to *.pd files (no changes in module code, just one simple GENERATED subdir which is automatically generated)

*/ the final tarball going to CPAN has the following content
- https://metacpan.org/source/CHM/PDL-LinearAlgebra-0.08_03 (see GENERATED subdir)

*/ with my workaround you can see nice documentation at both:
- https://metacpan.org/pod/release/CHM/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm
- http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm

*/ The hack is is quite simple if your distribution contains just one *.pd file like my module PDL::Finance::TA
- Makefile hack: https://metacpan.org/source/KMX/PDL-Finance-TA-0.008/Makefile.PL#L72
- https://metacpan.org/pod/PDL::Finance::TA
- http://search.cpan.org/perldoc?PDL::Finance::TA
- in distributions with more *.pd files it gets a bit more complicated, but still doable

My suggestion is to have a discussion whether this hack or something similar (or maybe something completely different) is OK and declare it as a "recommended way".

Then:
1/ we should patch PDL (core distribution) to have nice doc at metacpan.org
2/ maybe we can patch PDL/Core/Dev.pm (sub pdlpp_stdargs_int) to generate proper dist => {PREOP=>'...'} automatically

Opinions?

--
kmx


_______________________________________________
PDL-porters mailing list
PDL-***@jach.hawaii.edu
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters




--

"Debugging is twice as hard as writing the code in the first place.
Therefore, if you write the code as cleverly as possible, you are,
by definition, not smart enough to debug it." -- Brian Kernighan


_______________________________________________
PDL-porters mailing list
PDL-***@jach.hawaii.edu
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters




--

"Debugging is twice as hard as writing the code in the first place.
Therefore, if you write the code as cleverly as possible, you are,
by definition, not smart enough to debug it." -- Brian Kernighan



--

"Debugging is twice as hard as writing the code in the first place.
Therefore, if you write the code as cleverly as possible, you are,
by definition, not smart enough to debug it." -- Brian Kernighan

[Chris Marshall]

There are a fair number of programs/hardware with specific documentation
for the platform of interest (as installed or with the correct hardware).
For on-line, non-site-specific documentation, maybe we could have a way of
indicating what is required when an option is specific to a feature that
may be enabled or not....

Post by Ed .
I am baffled by the idea of documentation varying based on config
options, beyond maybe, just maybe, having a note on the options’ values
there.
*Sent:* Friday, December 19, 2014 1:59 AM
*Subject:* Re: [Pdl-porters] Proposal on how to make PDL related doc
available at matacpan.org
At the moment, search.cpan.org (which does render the pod in .pd
http://search.cpan.org/~chm/PDL-2.007/Basic/Bad/bad.pd
It even tells the reader at the top of the document "What you are reading
is the pod documentation as extracted directly from the .pd file, which is
not what you will see reported on your own machine. (I'm guessing you're
reading this from CPAN.)"
Should we special case this sort of documentation? I doubt it. In the very
least, if we go the auto-generated route, it would make a lot of sense to
re-clean-up the .pd files that I worked on, including bad.pd and slices.pd.
The underlying .pd code is somewhat obfuscated from my efforts to get them
to render properly.
David

Post by kmx
David,
my latest version produces the following GENERATED/PDL/Bad.pm
https://gist.github.com/kmx/f24248b0c5dfe369b299
Of course if the documentation is different depending on build options
(bad value support or not) it is a problem. But it is a general problem,
what do we want to have as an on-line documentation in these cases?
My opinioun is that if we have a given module in a given version the user
shout get the same documentation regardless the source he uses (pdldoc,
perldoc, man, metacpan.org, search.cpan.org, pdl.perl.org). For example
I mostly use on-line metacpan.org instead of local perldoc - and many
other people will do the same (which is the reason why I would like to see
nice PDL doc on metacpan :)
--
kmx

[Zakariyya Mughal]

Post by Chris Marshall
There are a fair number of programs/hardware with specific documentation
for the platform of interest (as installed or with the correct hardware).
For on-line, non-site-specific documentation, maybe we could have a way of
indicating what is required when an option is specific to a feature that
may be enabled or not....

I like what the Vim documentation does. It lists the features that might
be compiled in Vim (`:help +feature-list`) and wherever something is
documented, it will tell you what features need to be enabled for that
to function. For example, `:help serverlist()` says

{only available when compiled with the |+clientserver| feature}

Is something like that possible?

Regards,
- Zaki Mughal

Post by Chris Marshall

Post by Ed .
I am baffled by the idea of documentation varying based on config
options, beyond maybe, just maybe, having a note on the options’ values
there.
*Sent:* Friday, December 19, 2014 1:59 AM
*Subject:* Re: [Pdl-porters] Proposal on how to make PDL related doc
available at matacpan.org
At the moment, search.cpan.org (which does render the pod in .pd
http://search.cpan.org/~chm/PDL-2.007/Basic/Bad/bad.pd
It even tells the reader at the top of the document "What you are reading
is the pod documentation as extracted directly from the .pd file, which is
not what you will see reported on your own machine. (I'm guessing you're
reading this from CPAN.)"
Should we special case this sort of documentation? I doubt it. In the very
least, if we go the auto-generated route, it would make a lot of sense to
re-clean-up the .pd files that I worked on, including bad.pd and slices.pd.
The underlying .pd code is somewhat obfuscated from my efforts to get them
to render properly.
David

Post by kmx
David,
my latest version produces the following GENERATED/PDL/Bad.pm
https://gist.github.com/kmx/f24248b0c5dfe369b299
Of course if the documentation is different depending on build options
(bad value support or not) it is a problem. But it is a general problem,
what do we want to have as an on-line documentation in these cases?
My opinioun is that if we have a given module in a given version the user
shout get the same documentation regardless the source he uses (pdldoc,
perldoc, man, metacpan.org, search.cpan.org, pdl.perl.org). For example
I mostly use on-line metacpan.org instead of local perldoc - and many
other people will do the same (which is the reason why I would like to see
nice PDL doc on metacpan :)
--
kmx

_______________________________________________
PDL-porters mailing list
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters

[Chris Marshall]

We should probably add documentation for this if we're supporting it.

Post by David Mertens
The FullDoc field is a way to specify all of the documentation for a given
PDL::PP-generated function, rather than having PDL::PP generate it for you.
It also supports extraction of Pars and OtherPars directly from said
documentation. You can specify this key explicitly or it is also detected
if there are multiple lines in the function's "name", i.e. the first
argument to pp_def. See
https://metacpan.org/source/CHM/PDL-2.007/Basic/Gen/PP.pm#L1119
You can have the machinery extract the Pars field from the FullDoc field (
https://metacpan.org/source/CHM/PDL-2.007/Basic/Gen/PP.pm#L2978), and
also have it extract the OtherPars field from the FullDoc field (
https://metacpan.org/source/CHM/PDL-2.007/Basic/Gen/PP.pm#L2982). It will
only perform those extractions if you have not provided those fields
yourself, i.e. you can override them in your call to pp_def.
These functionalities do not make FullDoc an immediate POD fixup. But, you
can sprinkle POD into the FullDoc text, and when it's scanned by the CPAN
indexers, it gets picked up as documentation.
David

Post by Chris Marshall
What are FullDocs?

Post by David Mertens
Hey kmx,
In my attempt to solve this problem back in 2013, I added functionality
to PDL::PP that let you pass your documentation to the pp_def function. I
https://metacpan.org/source/CHM/PDL-2.007/Basic/Bad/bad.pd#L634.
search.cpan.org processes the .pd file and correctly renders the
documentation: http://search.cpan.org/~chm/PDL-2.007/Basic/Bad/bad.pd
bad.pd also illustrates the problem with generating documentation on the
release manager's machine. If you read the documentation on
search.cpan.org, hopefully it'll be clear. The actual code generated
for PDL::Bad depends on whether or not you compiled PDL with bad value
support, so the documentation you get will be different depending on your
compilation.
The solution I advocated, before running out of steam on this issue, was
to use FullDocs for all pp_defs in the core, and to change the file
extension from .pd to .xs.PL, which is what it should be anyway.
I would not be opposed to generating documentation on the release
manager's machine as long as we are aware of the limitations.
David

Post by kmx
Hi,
most of you probably know about incorrectly displayed/parsed
documentation for many PDL modules (as well as PDL core) at
https://metacpan.org/
The trouble is that metacpan.org is not able to parse *.pd files into
proper *.pod documentation and to be honest looking at documentation for
PDL related perl modules on metacpan.org or search.cpan.org definitely
distracts potential users. I know that there is some documentation
available at pdl.perl.org but people already using perl (like me) will
very likely first try to look at PDL documentation at metacpan.org
and/or search.cpan.org.
I have made a proof-of-concept experiment with PDL::LinearAlgebra (with
*/ before experiment there was LinearAlgebra-0.08
- https://metacpan.org/release/CHM/PDL-LinearAlgebra-0.08
- http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08
*/ let's have a look at PDL::LinearAlgebra::Real
- metacpan.org is not able to show any documentation
- search.cpan.org show something but it is "ugly"
http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08/Real/real.pd
*/ after couple of attempts I have ended up with a hack like this
-
https://metacpan.org/source/CHM/PDL-LinearAlgebra-0.08_03/Makefile.PL#L23
- In shot: during "make dist" phase it creates "GENERATED" subdirectory
with *.pm files corresponding to *.pd files (no changes in module code,
just one simple GENERATED subdir which is automatically generated)
*/ the final tarball going to CPAN has the following content
- https://metacpan.org/source/CHM/PDL-LinearAlgebra-0.08_03 (see
GENERATED subdir)
-
https://metacpan.org/pod/release/CHM/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm
-
http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm
*/ The hack is is quite simple if your distribution contains just one
*.pd file like my module PDL::Finance::TA
https://metacpan.org/source/KMX/PDL-Finance-TA-0.008/Makefile.PL#L72
- https://metacpan.org/pod/PDL::Finance::TA
- http://search.cpan.org/perldoc?PDL::Finance::TA
- in distributions with more *.pd files it gets a bit more complicated,
but still doable
My suggestion is to have a discussion whether this hack or something
similar (or maybe something completely different) is OK and declare it as a
"recommended way".
1/ we should patch PDL (core distribution) to have nice doc at metacpan.org
2/ maybe we can patch PDL/Core/Dev.pm (sub pdlpp_stdargs_int) to
generate proper dist => {PREOP=>'...'} automatically
Opinions?
--
kmx
_______________________________________________
PDL-porters mailing list
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters

--
"Debugging is twice as hard as writing the code in the first place.
Therefore, if you write the code as cleverly as possible, you are,
by definition, not smart enough to debug it." -- Brian Kernighan
_______________________________________________
PDL-porters mailing list
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters

--
"Debugging is twice as hard as writing the code in the first place.
Therefore, if you write the code as cleverly as possible, you are,
by definition, not smart enough to debug it." -- Brian Kernighan

[Derek Lamb]

FWIW, "generating documentation on the release manager's machine" has been basically the method for generating the docs at pdl.perl.org <http://pdl.perl.org/> for some time: once Chris releases a new version, I build it, compiling documentation for all the optional-but-included modules, and upload it to the website. Essentially this just involves

$ make doctest

and the uploading the contents of blib/


/HTMLdocs. Note that this doesn't help with POD parsing on [meta]cpan (I think).

Derek

Post by David Mertens
Hey kmx,
In my attempt to solve this problem back in 2013, I added functionality to PDL::PP that let you pass your documentation to the pp_def function. I demonstrated the use in bad.pd, as can be seen here: https://metacpan.org/source/CHM/PDL-2.007/Basic/Bad/bad.pd#L634 <https://metacpan.org/source/CHM/PDL-2.007/Basic/Bad/bad.pd#L634>. search.cpan.org <http://search.cpan.org/> processes the .pd file and correctly renders the documentation: http://search.cpan.org/~chm/PDL-2.007/Basic/Bad/bad.pd <http://search.cpan.org/~chm/PDL-2.007/Basic/Bad/bad.pd>
bad.pd also illustrates the problem with generating documentation on the release manager's machine. If you read the documentation on search.cpan.org <http://search.cpan.org/>, hopefully it'll be clear. The actual code generated for PDL::Bad depends on whether or not you compiled PDL with bad value support, so the documentation you get will be different depending on your compilation.
The solution I advocated, before running out of steam on this issue, was to use FullDocs for all pp_defs in the core, and to change the file extension from .pd to .xs.PL, which is what it should be anyway.
I would not be opposed to generating documentation on the release manager's machine as long as we are aware of the limitations.
David
Hi,
most of you probably know about incorrectly displayed/parsed documentation for many PDL modules (as well as PDL core) athttps://metacpan.org/ <https://metacpan.org/>
The trouble is that metacpan.org <http://metacpan.org/> is not able to parse *.pd files into proper *.pod documentation and to be honest looking at documentation for PDL related perl modules on metacpan.org <http://metacpan.org/> or search.cpan.org <http://search.cpan.org/> definitely distracts potential users. I know that there is some documentation available at pdl.perl.org <http://pdl.perl.org/> but people already using perl (like me) will very likely first try to look at PDL documentation at metacpan.org <http://metacpan.org/> and/or search.cpan.org <http://search.cpan.org/>.
*/ before experiment there was LinearAlgebra-0.08
- https://metacpan.org/release/CHM/PDL-LinearAlgebra-0.08 <https://metacpan.org/release/CHM/PDL-LinearAlgebra-0.08>
- http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08 <http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08>
*/ let's have a look at PDL::LinearAlgebra::Real
- metacpan.org <http://metacpan.org/> is not able to show any documentation
- search.cpan.org <http://search.cpan.org/> show something but it is "ugly" http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08/Real/real.pd <http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08/Real/real.pd>
*/ after couple of attempts I have ended up with a hack like this
- https://metacpan.org/source/CHM/PDL-LinearAlgebra-0.08_03/Makefile.PL#L23 <https://metacpan.org/source/CHM/PDL-LinearAlgebra-0.08_03/Makefile.PL#L23>
- In shot: during "make dist" phase it creates "GENERATED" subdirectory with *.pm files corresponding to *.pd files (no changes in module code, just one simple GENERATED subdir which is automatically generated)
*/ the final tarball going to CPAN has the following content
- https://metacpan.org/source/CHM/PDL-LinearAlgebra-0.08_03 <https://metacpan.org/source/CHM/PDL-LinearAlgebra-0.08_03> (see GENERATED subdir)
- https://metacpan.org/pod/release/CHM/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm <https://metacpan.org/pod/release/CHM/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm>
- http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm <http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm>
*/ The hack is is quite simple if your distribution contains just one *.pd file like my module PDL::Finance::TA
- Makefile hack: https://metacpan.org/source/KMX/PDL-Finance-TA-0.008/Makefile.PL#L72 <https://metacpan.org/source/KMX/PDL-Finance-TA-0.008/Makefile.PL#L72>
- https://metacpan.org/pod/PDL::Finance::TA <https://metacpan.org/pod/PDL::Finance::TA>
- http://search.cpan.org/perldoc?PDL::Finance::TA <http://search.cpan.org/perldoc?PDL::Finance::TA>
- in distributions with more *.pd files it gets a bit more complicated, but still doable
My suggestion is to have a discussion whether this hack or something similar (or maybe something completely different) is OK and declare it as a "recommended way".
1/ we should patch PDL (core distribution) to have nice doc at metacpan.org <http://metacpan.org/>
2/ maybe we can patch PDL/Core/Dev.pm (sub pdlpp_stdargs_int) to generate proper dist => {PREOP=>'...'} automatically
Opinions?
--
kmx
_______________________________________________
PDL-porters mailing list
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters <http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters>
--
"Debugging is twice as hard as writing the code in the first place.
Therefore, if you write the code as cleverly as possible, you are,
by definition, not smart enough to debug it." -- Brian Kernighan
_______________________________________________
PDL-porters mailing list
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters

[Bryan Jurish]

moin kmx,

fwiw, i've been using something very similar to what you're proposing, to
wit: pre-generating *.pm and including them in the archive uploaded to
cpan. in my case, i ended up wrapping the functionality into a
"pdlmaker.plm" file included by Makefile.PL; see e.g.
https://metacpan.org/source/MOOCOW/PDL-HMM-0.06002/pdlmaker.plm : it works
by scanning the MANIFEST for *.pd files and asssociated *.pm files (if
present in a second column).

some thoughts:
+ i like your idea of using a dedicated "GENERATED/" subdirectory to put
the dummy pm-files; a number of "pdlmaker.plm" hacks were required to
remove them at configuration time
+ the PREOP code in PDL::Finance::TA looks a bit unwieldy ... then again,
it's quite regular and easy to auto-generate with some extra perl code, or
even incorporate that into PDL::Core::Dev (as you suggested... argh; sorry,
wrote without thinking again)

... and a question: does this strategy actually keep perl from installing
stale GENERATED/*.pm files, or do you need to define PM?

marmosets,
Bryan

Post by kmx
Hi,
most of you probably know about incorrectly displayed/parsed documentation
for many PDL modules (as well as PDL core) at https://metacpan.org/
The trouble is that metacpan.org is not able to parse *.pd files into
proper *.pod documentation and to be honest looking at documentation for
PDL related perl modules on metacpan.org or search.cpan.org definitely
distracts potential users. I know that there is some documentation
available at pdl.perl.org but people already using perl (like me) will
very likely first try to look at PDL documentation at metacpan.org and/or
search.cpan.org.
I have made a proof-of-concept experiment with PDL::LinearAlgebra (with
*/ before experiment there was LinearAlgebra-0.08
- https://metacpan.org/release/CHM/PDL-LinearAlgebra-0.08
- http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08
*/ let's have a look at PDL::LinearAlgebra::Real
- metacpan.org is not able to show any documentation
- search.cpan.org show something but it is "ugly"
http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08/Real/real.pd
*/ after couple of attempts I have ended up with a hack like this
-
https://metacpan.org/source/CHM/PDL-LinearAlgebra-0.08_03/Makefile.PL#L23
- In shot: during "make dist" phase it creates "GENERATED" subdirectory
with *.pm files corresponding to *.pd files (no changes in module code,
just one simple GENERATED subdir which is automatically generated)
*/ the final tarball going to CPAN has the following content
- https://metacpan.org/source/CHM/PDL-LinearAlgebra-0.08_03 (see
GENERATED subdir)
-
https://metacpan.org/pod/release/CHM/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm
- http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm
*/ The hack is is quite simple if your distribution contains just one *.pd
file like my module PDL::Finance::TA
https://metacpan.org/source/KMX/PDL-Finance-TA-0.008/Makefile.PL#L72
- https://metacpan.org/pod/PDL::Finance::TA
- http://search.cpan.org/perldoc?PDL::Finance::TA
- in distributions with more *.pd files it gets a bit more complicated,
but still doable
My suggestion is to have a discussion whether this hack or something
similar (or maybe something completely different) is OK and declare it as a
"recommended way".
1/ we should patch PDL (core distribution) to have nice doc at
metacpan.org
2/ maybe we can patch PDL/Core/Dev.pm (sub pdlpp_stdargs_int) to generate
proper dist => {PREOP=>'...'} automatically
Opinions?
--
kmx
_______________________________________________
PDL-porters mailing list
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters

[Chris Marshall]

If we make the change of filename .pd to .xs.PL does
that fix the problem? I don't recall the specific discussion
of why or why not for ..pd versus .xs.PL. If it was
compatibility, maybe PDL::Tiny and PDL3 would be
a good time to revisit this.

--Chris

Post by Bryan Jurish
moin kmx,
fwiw, i've been using something very similar to what you're proposing, to
wit: pre-generating *.pm and including them in the archive uploaded to
cpan. in my case, i ended up wrapping the functionality into a
"pdlmaker.plm" file included by Makefile.PL; see e.g.
https://metacpan.org/source/MOOCOW/PDL-HMM-0.06002/pdlmaker.plm : it
works by scanning the MANIFEST for *.pd files and asssociated *.pm files
(if present in a second column).
+ i like your idea of using a dedicated "GENERATED/" subdirectory to put
the dummy pm-files; a number of "pdlmaker.plm" hacks were required to
remove them at configuration time
+ the PREOP code in PDL::Finance::TA looks a bit unwieldy ... then again,
it's quite regular and easy to auto-generate with some extra perl code, or
even incorporate that into PDL::Core::Dev (as you suggested... argh; sorry,
wrote without thinking again)
... and a question: does this strategy actually keep perl from installing
stale GENERATED/*.pm files, or do you need to define PM?
marmosets,
Bryan

Post by kmx
Hi,
most of you probably know about incorrectly displayed/parsed
documentation for many PDL modules (as well as PDL core) at
https://metacpan.org/
The trouble is that metacpan.org is not able to parse *.pd files into
proper *.pod documentation and to be honest looking at documentation for
PDL related perl modules on metacpan.org or search.cpan.org definitely
distracts potential users. I know that there is some documentation
available at pdl.perl.org but people already using perl (like me) will
very likely first try to look at PDL documentation at metacpan.org
and/or search.cpan.org.
I have made a proof-of-concept experiment with PDL::LinearAlgebra (with
*/ before experiment there was LinearAlgebra-0.08
- https://metacpan.org/release/CHM/PDL-LinearAlgebra-0.08
- http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08
*/ let's have a look at PDL::LinearAlgebra::Real
- metacpan.org is not able to show any documentation
- search.cpan.org show something but it is "ugly"
http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08/Real/real.pd
*/ after couple of attempts I have ended up with a hack like this
-
https://metacpan.org/source/CHM/PDL-LinearAlgebra-0.08_03/Makefile.PL#L23
- In shot: during "make dist" phase it creates "GENERATED" subdirectory
with *.pm files corresponding to *.pd files (no changes in module code,
just one simple GENERATED subdir which is automatically generated)
*/ the final tarball going to CPAN has the following content
- https://metacpan.org/source/CHM/PDL-LinearAlgebra-0.08_03 (see
GENERATED subdir)
-
https://metacpan.org/pod/release/CHM/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm
- http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm
*/ The hack is is quite simple if your distribution contains just one
*.pd file like my module PDL::Finance::TA
https://metacpan.org/source/KMX/PDL-Finance-TA-0.008/Makefile.PL#L72
- https://metacpan.org/pod/PDL::Finance::TA
- http://search.cpan.org/perldoc?PDL::Finance::TA
- in distributions with more *.pd files it gets a bit more complicated,
but still doable
My suggestion is to have a discussion whether this hack or something
similar (or maybe something completely different) is OK and declare it as a
"recommended way".
1/ we should patch PDL (core distribution) to have nice doc at metacpan.org
2/ maybe we can patch PDL/Core/Dev.pm (sub pdlpp_stdargs_int) to generate
proper dist => {PREOP=>'...'} automatically
Opinions?
--
kmx
_______________________________________________
PDL-porters mailing list
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters

--
Bryan Jurish "There is *always* one more bug."
_______________________________________________
PDL-porters mailing list
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters

[Chris Marshall]

How about .pd.PL rather than .xs.PL to indicate that the content is
specifically PDL::PP rather than just any-old-perl-to-xs code?

Post by Chris Marshall
If we make the change of filename .pd to .xs.PL does
that fix the problem? I don't recall the specific discussion
of why or why not for ..pd versus .xs.PL. If it was
compatibility, maybe PDL::Tiny and PDL3 would be
a good time to revisit this.
--Chris

Post by Bryan Jurish
moin kmx,
fwiw, i've been using something very similar to what you're proposing, to
wit: pre-generating *.pm and including them in the archive uploaded to
cpan. in my case, i ended up wrapping the functionality into a
"pdlmaker.plm" file included by Makefile.PL; see e.g.
https://metacpan.org/source/MOOCOW/PDL-HMM-0.06002/pdlmaker.plm : it
works by scanning the MANIFEST for *.pd files and asssociated *.pm files
(if present in a second column).
+ i like your idea of using a dedicated "GENERATED/" subdirectory to put
the dummy pm-files; a number of "pdlmaker.plm" hacks were required to
remove them at configuration time
+ the PREOP code in PDL::Finance::TA looks a bit unwieldy ... then again,
it's quite regular and easy to auto-generate with some extra perl code, or
even incorporate that into PDL::Core::Dev (as you suggested... argh; sorry,
wrote without thinking again)
... and a question: does this strategy actually keep perl from installing
stale GENERATED/*.pm files, or do you need to define PM?
marmosets,
Bryan

Post by kmx
Hi,
most of you probably know about incorrectly displayed/parsed
documentation for many PDL modules (as well as PDL core) at
https://metacpan.org/
The trouble is that metacpan.org is not able to parse *.pd files into
proper *.pod documentation and to be honest looking at documentation for
PDL related perl modules on metacpan.org or search.cpan.org definitely
distracts potential users. I know that there is some documentation
available at pdl.perl.org but people already using perl (like me) will
very likely first try to look at PDL documentation at metacpan.org
and/or search.cpan.org.
I have made a proof-of-concept experiment with PDL::LinearAlgebra (with
*/ before experiment there was LinearAlgebra-0.08
- https://metacpan.org/release/CHM/PDL-LinearAlgebra-0.08
- http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08
*/ let's have a look at PDL::LinearAlgebra::Real
- metacpan.org is not able to show any documentation
- search.cpan.org show something but it is "ugly"
http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08/Real/real.pd
*/ after couple of attempts I have ended up with a hack like this
-
https://metacpan.org/source/CHM/PDL-LinearAlgebra-0.08_03/Makefile.PL#L23
- In shot: during "make dist" phase it creates "GENERATED" subdirectory
with *.pm files corresponding to *.pd files (no changes in module code,
just one simple GENERATED subdir which is automatically generated)
*/ the final tarball going to CPAN has the following content
- https://metacpan.org/source/CHM/PDL-LinearAlgebra-0.08_03 (see
GENERATED subdir)
-
https://metacpan.org/pod/release/CHM/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm
-
http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm
*/ The hack is is quite simple if your distribution contains just one
*.pd file like my module PDL::Finance::TA
https://metacpan.org/source/KMX/PDL-Finance-TA-0.008/Makefile.PL#L72
- https://metacpan.org/pod/PDL::Finance::TA
- http://search.cpan.org/perldoc?PDL::Finance::TA
- in distributions with more *.pd files it gets a bit more complicated,
but still doable
My suggestion is to have a discussion whether this hack or something
similar (or maybe something completely different) is OK and declare it as a
"recommended way".
1/ we should patch PDL (core distribution) to have nice doc at metacpan.org
2/ maybe we can patch PDL/Core/Dev.pm (sub pdlpp_stdargs_int) to
generate proper dist => {PREOP=>'...'} automatically
Opinions?
--
kmx
_______________________________________________
PDL-porters mailing list
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters

--
Bryan Jurish "There is *always* one more bug."
_______________________________________________
PDL-porters mailing list
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters

[kmx]

This approach works with:
Makefile.PL >>> Makefile

However with *.pd it is not pure 1:1 conversion but 1:2 fork
Something.pd >>> Something.pm + Something.xs

The other trouble is that you still need to convince guys running
matacpan.org and search.cpan.org to execute the conversion before indexing.

--
kmx

Post by Chris Marshall
How about .pd.PL rather than .xs.PL to indicate that the content is
specifically PDL::PP rather than just any-old-perl-to-xs code?
If we make the change of filename .pd to .xs.PL does
that fix the problem? I don't recall the specific discussion
of why or why not for ..pd versus .xs.PL. If it was
compatibility, maybe PDL::Tiny and PDL3 would be
a good time to revisit this.
--Chris
On Thu, Dec 18, 2014 at 9:16 AM, Bryan Jurish
moin kmx,
fwiw, i've been using something very similar to what you're
proposing, to wit: pre-generating *.pm and including them in the
archive uploaded to cpan. in my case, i ended up wrapping the
functionality into a "pdlmaker.plm" file included by Makefile.PL;
see e.g.
it works by scanning the MANIFEST for *.pd files and asssociated
*.pm files (if present in a second column).
+ i like your idea of using a dedicated "GENERATED/" subdirectory
to put the dummy pm-files; a number of "pdlmaker.plm" hacks were
required to remove them at configuration time
+ the PREOP code in PDL::Finance::TA looks a bit unwieldy ...
then again, it's quite regular and easy to auto-generate with
some extra perl code, or even incorporate that into
PDL::Core::Dev (as you suggested... argh; sorry, wrote without
thinking again)
... and a question: does this strategy actually keep perl from
installing stale GENERATED/*.pm files, or do you need to define PM?
marmosets,
Bryan
Hi,
most of you probably know about incorrectly displayed/parsed
documentation for many PDL modules (as well as PDL core) at
https://metacpan.org/
The trouble is that metacpan.org <http://metacpan.org> is not
able to parse *.pd files into proper *.pod documentation and
to be honest looking at documentation for PDL related perl
modules on metacpan.org <http://metacpan.org> or
search.cpan.org <http://search.cpan.org> definitely distracts
potential users. I know that there is some documentation
available at pdl.perl.org <http://pdl.perl.org> but people
already using perl (like me) will very likely first try to
look at PDL documentation at metacpan.org
<http://metacpan.org> and/or search.cpan.org
<http://search.cpan.org>.
I have made a proof-of-concept experiment with
*/ before experiment there was LinearAlgebra-0.08
- https://metacpan.org/release/CHM/PDL-LinearAlgebra-0.08
- http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08
<http://search.cpan.org/%7Echm/PDL-LinearAlgebra-0.08>
*/ let's have a look at PDL::LinearAlgebra::Real
- metacpan.org <http://metacpan.org> is not able to show any
documentation
- search.cpan.org <http://search.cpan.org> show something but
it is "ugly"
http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08/Real/real.pd
<http://search.cpan.org/%7Echm/PDL-LinearAlgebra-0.08/Real/real.pd>
*/ after couple of attempts I have ended up with a hack like this
-
https://metacpan.org/source/CHM/PDL-LinearAlgebra-0.08_03/Makefile.PL#L23
- In shot: during "make dist" phase it creates "GENERATED"
subdirectory with *.pm files corresponding to *.pd files (no
changes in module code, just one simple GENERATED subdir
which is automatically generated)
*/ the final tarball going to CPAN has the following content
- https://metacpan.org/source/CHM/PDL-LinearAlgebra-0.08_03
(see GENERATED subdir)
-
https://metacpan.org/pod/release/CHM/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm
-
http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm
<http://search.cpan.org/%7Echm/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm>
*/ The hack is is quite simple if your distribution contains
just one *.pd file like my module PDL::Finance::TA
https://metacpan.org/source/KMX/PDL-Finance-TA-0.008/Makefile.PL#L72
- https://metacpan.org/pod/PDL::Finance::TA
- http://search.cpan.org/perldoc?PDL::Finance::TA
- in distributions with more *.pd files it gets a bit more
complicated, but still doable
My suggestion is to have a discussion whether this hack or
something similar (or maybe something completely different)
is OK and declare it as a "recommended way".
1/ we should patch PDL (core distribution) to have nice doc
at metacpan.org <http://metacpan.org>
2/ maybe we can patch PDL/Core/Dev.pm (sub pdlpp_stdargs_int)
to generate proper dist => {PREOP=>'...'} automatically
Opinions?
--
kmx
_______________________________________________
PDL-porters mailing list
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters
--
Bryan Jurish "There is *always* one more bug."
-Lubarsky's Law of Cybernetic Entomology
_______________________________________________
PDL-porters mailing list
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters

[Joel Berger]

The .PL extension means that when executed the file itself generates a file
of the same name except without the .PL. This is why .xs.PL is probably the
right name (though, IIRC it also generates a .pm file, so it could be
argued to be .pm.PL too). While I could see arguments that .pd is
historically used and we could campaign for the sites to use them as
intended, I think that using .pd.PL would give the wrong idea to anyone
else from the Perl community; it doesn't generate a .pd file.

Post by Chris Marshall
How about .pd.PL rather than .xs.PL to indicate that the content is
specifically PDL::PP rather than just any-old-perl-to-xs code?

Post by Chris Marshall
If we make the change of filename .pd to .xs.PL does
that fix the problem? I don't recall the specific discussion
of why or why not for ..pd versus .xs.PL. If it was
compatibility, maybe PDL::Tiny and PDL3 would be
a good time to revisit this.
--Chris

Post by Bryan Jurish
moin kmx,
fwiw, i've been using something very similar to what you're proposing,
to wit: pre-generating *.pm and including them in the archive uploaded to
cpan. in my case, i ended up wrapping the functionality into a
"pdlmaker.plm" file included by Makefile.PL; see e.g.
https://metacpan.org/source/MOOCOW/PDL-HMM-0.06002/pdlmaker.plm : it
works by scanning the MANIFEST for *.pd files and asssociated *.pm files
(if present in a second column).
+ i like your idea of using a dedicated "GENERATED/" subdirectory to put
the dummy pm-files; a number of "pdlmaker.plm" hacks were required to
remove them at configuration time
+ the PREOP code in PDL::Finance::TA looks a bit unwieldy ... then
again, it's quite regular and easy to auto-generate with some extra perl
code, or even incorporate that into PDL::Core::Dev (as you suggested...
argh; sorry, wrote without thinking again)
... and a question: does this strategy actually keep perl from
installing stale GENERATED/*.pm files, or do you need to define PM?
marmosets,
Bryan

Post by kmx
Hi,
most of you probably know about incorrectly displayed/parsed
documentation for many PDL modules (as well as PDL core) at
https://metacpan.org/
The trouble is that metacpan.org is not able to parse *.pd files into
proper *.pod documentation and to be honest looking at documentation for
PDL related perl modules on metacpan.org or search.cpan.org definitely
distracts potential users. I know that there is some documentation
available at pdl.perl.org but people already using perl (like me) will
very likely first try to look at PDL documentation at metacpan.org
and/or search.cpan.org.
I have made a proof-of-concept experiment with PDL::LinearAlgebra (with
*/ before experiment there was LinearAlgebra-0.08
- https://metacpan.org/release/CHM/PDL-LinearAlgebra-0.08
- http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08
*/ let's have a look at PDL::LinearAlgebra::Real
- metacpan.org is not able to show any documentation
- search.cpan.org show something but it is "ugly"
http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08/Real/real.pd
*/ after couple of attempts I have ended up with a hack like this
-
https://metacpan.org/source/CHM/PDL-LinearAlgebra-0.08_03/Makefile.PL#L23
- In shot: during "make dist" phase it creates "GENERATED" subdirectory
with *.pm files corresponding to *.pd files (no changes in module code,
just one simple GENERATED subdir which is automatically generated)
*/ the final tarball going to CPAN has the following content
- https://metacpan.org/source/CHM/PDL-LinearAlgebra-0.08_03 (see
GENERATED subdir)
-
https://metacpan.org/pod/release/CHM/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm
-
http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm
*/ The hack is is quite simple if your distribution contains just one
*.pd file like my module PDL::Finance::TA
https://metacpan.org/source/KMX/PDL-Finance-TA-0.008/Makefile.PL#L72
- https://metacpan.org/pod/PDL::Finance::TA
- http://search.cpan.org/perldoc?PDL::Finance::TA
- in distributions with more *.pd files it gets a bit more complicated,
but still doable
My suggestion is to have a discussion whether this hack or something
similar (or maybe something completely different) is OK and declare it as a
"recommended way".
1/ we should patch PDL (core distribution) to have nice doc at metacpan.org
2/ maybe we can patch PDL/Core/Dev.pm (sub pdlpp_stdargs_int) to
generate proper dist => {PREOP=>'...'} automatically
Opinions?
--
kmx
_______________________________________________
PDL-porters mailing list
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters

--
Bryan Jurish "There is *always* one more bug."
_______________________________________________
PDL-porters mailing list
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters

_______________________________________________
PDL-porters mailing list
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters

[kmx]

Hi Joel,

I have done some testing which you can find here:
https://metacpan.org/source/KMX/Acme-KMX-Test-0.005

This distribution has 3 modules:
Acme::KMX::Test
Acme::KMX::Pokus1 (generated from Pokus1.pm.PL)
Acme::KMX::Pokus2 (generated from Pokus2.pm.PL)
(try "cpanm Acme::KMX::Test" and you will have all 3 installed)

As you can see here:
https://metacpan.org/release/KMX/Acme-KMX-Test-0.005
there is no documentation for
Acme::KMX::Pokus1
Acme::KMX::Pokus2

So, yes using *.xs.PL or *.pm.PL or *.pd.PL in PDL3 is worth considering,
however it will not solve the troubles with documentation at metacpan.org
as metacpan does not seem to execute *.pm.PL files before indexing.

Of course there might be something completely wrong in my Acme-KMX-Test
(feel free to correct me).

--
kmx

Post by Joel Berger
The .PL extension means that when executed the file itself generates a
file of the same name except without the .PL. This is why .xs.PL is
probably the right name (though, IIRC it also generates a .pm file, so it
could be argued to be .pm.PL too). While I could see arguments that .pd
is historically used and we could campaign for the sites to use them as
intended, I think that using .pd.PL would give the wrong idea to anyone
else from the Perl community; it doesn't generate a .pd file.
How about .pd.PL rather than .xs.PL to indicate that the content is
specifically PDL::PP rather than just any-old-perl-to-xs code?
On Thu, Dec 18, 2014 at 9:20 AM, Chris Marshall
If we make the change of filename .pd to .xs.PL does
that fix the problem? I don't recall the specific discussion
of why or why not for ..pd versus .xs.PL. If it was
compatibility, maybe PDL::Tiny and PDL3 would be
a good time to revisit this.
--Chris
On Thu, Dec 18, 2014 at 9:16 AM, Bryan Jurish
moin kmx,
fwiw, i've been using something very similar to what you're
proposing, to wit: pre-generating *.pm and including them in
the archive uploaded to cpan. in my case, i ended up
wrapping the functionality into a "pdlmaker.plm" file
included by Makefile.PL; see e.g.
https://metacpan.org/source/MOOCOW/PDL-HMM-0.06002/pdlmaker.plm
: it works by scanning the MANIFEST for *.pd files and
asssociated *.pm files (if present in a second column).
+ i like your idea of using a dedicated "GENERATED/"
subdirectory to put the dummy pm-files; a number of
"pdlmaker.plm" hacks were required to remove them at
configuration time
+ the PREOP code in PDL::Finance::TA looks a bit unwieldy ...
then again, it's quite regular and easy to auto-generate with
some extra perl code, or even incorporate that into
without thinking again)
... and a question: does this strategy actually keep perl
from installing stale GENERATED/*.pm files, or do you need to
define PM?
marmosets,
Bryan
Hi,
most of you probably know about incorrectly
displayed/parsed documentation for many PDL modules (as
well as PDL core) at https://metacpan.org/
The trouble is that metacpan.org <http://metacpan.org> is
not able to parse *.pd files into proper *.pod
documentation and to be honest looking at documentation
for PDL related perl modules on metacpan.org
<http://metacpan.org> or search.cpan.org
<http://search.cpan.org> definitely distracts potential
users. I know that there is some documentation available
at pdl.perl.org <http://pdl.perl.org> but people already
using perl (like me) will very likely first try to look
at PDL documentation at metacpan.org
<http://metacpan.org> and/or search.cpan.org
<http://search.cpan.org>.
I have made a proof-of-concept experiment with
*/ before experiment there was LinearAlgebra-0.08
- https://metacpan.org/release/CHM/PDL-LinearAlgebra-0.08
- http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08
<http://search.cpan.org/%7Echm/PDL-LinearAlgebra-0.08>
*/ let's have a look at PDL::LinearAlgebra::Real
- metacpan.org <http://metacpan.org> is not able to show
any documentation
- search.cpan.org <http://search.cpan.org> show something
but it is "ugly"
http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08/Real/real.pd
<http://search.cpan.org/%7Echm/PDL-LinearAlgebra-0.08/Real/real.pd>
*/ after couple of attempts I have ended up with a hack
like this
-
https://metacpan.org/source/CHM/PDL-LinearAlgebra-0.08_03/Makefile.PL#L23
- In shot: during "make dist" phase it creates
"GENERATED" subdirectory with *.pm files corresponding to
*.pd files (no changes in module code, just one simple
GENERATED subdir which is automatically generated)
*/ the final tarball going to CPAN has the following content
-
https://metacpan.org/source/CHM/PDL-LinearAlgebra-0.08_03
(see GENERATED subdir)
-
https://metacpan.org/pod/release/CHM/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm
-
http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm
<http://search.cpan.org/%7Echm/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm>
*/ The hack is is quite simple if your distribution
contains just one *.pd file like my module PDL::Finance::TA
https://metacpan.org/source/KMX/PDL-Finance-TA-0.008/Makefile.PL#L72
- https://metacpan.org/pod/PDL::Finance::TA
- http://search.cpan.org/perldoc?PDL::Finance::TA
- in distributions with more *.pd files it gets a bit
more complicated, but still doable
My suggestion is to have a discussion whether this hack
or something similar (or maybe something completely
different) is OK and declare it as a "recommended way".
1/ we should patch PDL (core distribution) to have nice
doc at metacpan.org <http://metacpan.org>
2/ maybe we can patch PDL/Core/Dev.pm (sub
pdlpp_stdargs_int) to generate proper dist =>
{PREOP=>'...'} automatically
Opinions?
--
kmx
_______________________________________________
PDL-porters mailing list
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters
--
Bryan Jurish "There is *always* one
more bug."
-Lubarsky's Law of Cybernetic Entomology
_______________________________________________
PDL-porters mailing list
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters
_______________________________________________
PDL-porters mailing list
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters
_______________________________________________
PDL-porters mailing list
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters

[Ed .]

How truly important is it to not just have the same POD for all installations? Why is PDL so unique that it has requirements that, as far as I know, no other Perl software has ever used?


From: kmx
Sent: Monday, December 22, 2014 3:45 PM
To: pdl-***@jach.hawaii.edu
Subject: [Pdl-porters] metacpan.org & .pm.PL "urban legend"

Hi Joel,

I have done some testing which you can find here:
https://metacpan.org/source/KMX/Acme-KMX-Test-0.005

This distribution has 3 modules:
Acme::KMX::Test
Acme::KMX::Pokus1 (generated from Pokus1.pm.PL)
Acme::KMX::Pokus2 (generated from Pokus2.pm.PL)
(try "cpanm Acme::KMX::Test" and you will have all 3 installed)

As you can see here:
https://metacpan.org/release/KMX/Acme-KMX-Test-0.005
there is no documentation for
Acme::KMX::Pokus1
Acme::KMX::Pokus2

So, yes using *.xs.PL or *.pm.PL or *.pd.PL in PDL3 is worth considering, however it will not solve the troubles with documentation at metacpan.org as metacpan does not seem to execute *.pm.PL files before indexing.

Of course there might be something completely wrong in my Acme-KMX-Test (feel free to correct me).

--
kmx


On 18.12.2014 19:55, Joel Berger wrote:

The .PL extension means that when executed the file itself generates a file of the same name except without the .PL. This is why .xs.PL is probably the right name (though, IIRC it also generates a .pm file, so it could be argued to be .pm.PL too). While I could see arguments that .pd is historically used and we could campaign for the sites to use them as intended, I think that using .pd.PL would give the wrong idea to anyone else from the Perl community; it doesn't generate a .pd file.

On Thu, Dec 18, 2014 at 8:24 AM, Chris Marshall <***@gmail.com> wrote:
How about .pd.PL rather than .xs.PL to indicate that the content is specifically PDL::PP rather than just any-old-perl-to-xs code?


On Thu, Dec 18, 2014 at 9:20 AM, Chris Marshall <***@gmail.com> wrote:
If we make the change of filename .pd to .xs.PL does
that fix the problem? I don't recall the specific discussion
of why or why not for ..pd versus .xs.PL. If it was

compatibility, maybe PDL::Tiny and PDL3 would be
a good time to revisit this.


--Chris



On Thu, Dec 18, 2014 at 9:16 AM, Bryan Jurish <***@gmail.com> wrote:
moin kmx,

fwiw, i've been using something very similar to what you're proposing, to wit: pre-generating *.pm and including them in the archive uploaded to cpan. in my case, i ended up wrapping the functionality into a "pdlmaker.plm" file included by Makefile.PL; see e.g.
https://metacpan.org/source/MOOCOW/PDL-HMM-0.06002/pdlmaker.plm : it works by scanning the MANIFEST for *.pd files and asssociated *.pm files (if present in a second column).


some thoughts:
+ i like your idea of using a dedicated "GENERATED/" subdirectory to put the dummy pm-files; a number of "pdlmaker.plm" hacks were required to remove them at configuration time
+ the PREOP code in PDL::Finance::TA looks a bit unwieldy ... then again, it's quite regular and easy to auto-generate with some extra perl code, or even incorporate that into PDL::Core::Dev (as you suggested... argh; sorry, wrote without thinking again)

... and a question: does this strategy actually keep perl from installing stale GENERATED/*.pm files, or do you need to define PM?

marmosets,
Bryan

On Thu, Dec 18, 2014 at 9:51 AM, kmx <***@atlas.cz> wrote:
Hi,

most of you probably know about incorrectly displayed/parsed documentation for many PDL modules (as well as PDL core) at https://metacpan.org/

The trouble is that metacpan.org is not able to parse *.pd files into proper *.pod documentation and to be honest looking at documentation for PDL related perl modules on metacpan.org or search.cpan.org definitely distracts potential users. I know that there is some documentation available at pdl.perl.org but people already using perl (like me) will very likely first try to look at PDL documentation at metacpan.org and/or search.cpan.org.

I have made a proof-of-concept experiment with PDL::LinearAlgebra (with help of Chris):

*/ before experiment there was LinearAlgebra-0.08
- https://metacpan.org/release/CHM/PDL-LinearAlgebra-0.08
- http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08

*/ let's have a look at PDL::LinearAlgebra::Real
- metacpan.org is not able to show any documentation
- search.cpan.org show something but it is "ugly" http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08/Real/real.pd

*/ after couple of attempts I have ended up with a hack like this
- https://metacpan.org/source/CHM/PDL-LinearAlgebra-0.08_03/Makefile.PL#L23
- In shot: during "make dist" phase it creates "GENERATED" subdirectory with *.pm files corresponding to *.pd files (no changes in module code, just one simple GENERATED subdir which is automatically generated)

*/ the final tarball going to CPAN has the following content
- https://metacpan.org/source/CHM/PDL-LinearAlgebra-0.08_03 (see GENERATED subdir)

*/ with my workaround you can see nice documentation at both:
- https://metacpan.org/pod/release/CHM/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm
- http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm

*/ The hack is is quite simple if your distribution contains just one *.pd file like my module PDL::Finance::TA
- Makefile hack: https://metacpan.org/source/KMX/PDL-Finance-TA-0.008/Makefile.PL#L72
- https://metacpan.org/pod/PDL::Finance::TA
- http://search.cpan.org/perldoc?PDL::Finance::TA
- in distributions with more *.pd files it gets a bit more complicated, but still doable

My suggestion is to have a discussion whether this hack or something similar (or maybe something completely different) is OK and declare it as a "recommended way".

Then:
1/ we should patch PDL (core distribution) to have nice doc at metacpan.org
2/ maybe we can patch PDL/Core/Dev.pm (sub pdlpp_stdargs_int) to generate proper dist => {PREOP=>'...'} automatically

Opinions?

--
kmx


_______________________________________________
PDL-porters mailing list
PDL-***@jach.hawaii.edu
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters





--

Bryan Jurish "There is *always* one more bug."
***@gmail.com -Lubarsky's Law of Cybernetic Entomology


_______________________________________________
PDL-porters mailing list
PDL-***@jach.hawaii.edu
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters



_______________________________________________
PDL-porters mailing list
PDL-***@jach.hawaii.edu
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters





_______________________________________________
PDL-porters mailing list
PDL-***@jach.hawaii.edu
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters




--------------------------------------------------------------------------------

[David Mertens]

Hey kmx,

I believe this is a bug with MetaCPAN. The original bug filed is
https://github.com/CPAN-API/metacpan-web/issues/679.

I have added a link to your recent distribution. Apparently, it was thought
that .pm.PL files would be indexed, but your example dist shows this is not
the case. Hopefully we can get this resolved so that, at the very least,
the documentation for .pm.PL and like files can get properly indexed.

David

Post by kmx
Hi Joel,
https://metacpan.org/source/KMX/Acme-KMX-Test-0.005
Acme::KMX::Test
Acme::KMX::Pokus1 (generated from Pokus1.pm.PL)
Acme::KMX::Pokus2 (generated from Pokus2.pm.PL)
(try "cpanm Acme::KMX::Test" and you will have all 3 installed)
https://metacpan.org/release/KMX/Acme-KMX-Test-0.005
there is no documentation for
Acme::KMX::Pokus1
Acme::KMX::Pokus2
So, yes using *.xs.PL or *.pm.PL or *.pd.PL in PDL3 is worth considering,
however it will not solve the troubles with documentation at metacpan.org
as metacpan does not seem to execute *.pm.PL files before indexing.
Of course there might be something completely wrong in my Acme-KMX-Test
(feel free to correct me).
--
kmx
The .PL extension means that when executed the file itself generates a
file of the same name except without the .PL. This is why .xs.PL is
probably the right name (though, IIRC it also generates a .pm file, so it
could be argued to be .pm.PL too). While I could see arguments that .pd is
historically used and we could campaign for the sites to use them as
intended, I think that using .pd.PL would give the wrong idea to anyone
else from the Perl community; it doesn't generate a .pd file.

Post by Chris Marshall
How about .pd.PL rather than .xs.PL to indicate that the content is
specifically PDL::PP rather than just any-old-perl-to-xs code?

Post by Chris Marshall
If we make the change of filename .pd to .xs.PL does
that fix the problem? I don't recall the specific discussion
of why or why not for ..pd versus .xs.PL. If it was
compatibility, maybe PDL::Tiny and PDL3 would be
a good time to revisit this.
--Chris

Post by Bryan Jurish
moin kmx,
fwiw, i've been using something very similar to what you're
proposing, to wit: pre-generating *.pm and including them in the archive
uploaded to cpan. in my case, i ended up wrapping the functionality into a
"pdlmaker.plm" file included by Makefile.PL; see e.g.
https://metacpan.org/source/MOOCOW/PDL-HMM-0.06002/pdlmaker.plm : it
works by scanning the MANIFEST for *.pd files and asssociated *.pm files
(if present in a second column).
+ i like your idea of using a dedicated "GENERATED/" subdirectory to
put the dummy pm-files; a number of "pdlmaker.plm" hacks were required to
remove them at configuration time
+ the PREOP code in PDL::Finance::TA looks a bit unwieldy ... then
again, it's quite regular and easy to auto-generate with some extra perl
code, or even incorporate that into PDL::Core::Dev (as you suggested...
argh; sorry, wrote without thinking again)
... and a question: does this strategy actually keep perl from
installing stale GENERATED/*.pm files, or do you need to define PM?
marmosets,
Bryan

Post by kmx
Hi,
most of you probably know about incorrectly displayed/parsed
documentation for many PDL modules (as well as PDL core) at
https://metacpan.org/
The trouble is that metacpan.org is not able to parse *.pd files into
proper *.pod documentation and to be honest looking at documentation for
PDL related perl modules on metacpan.org or search.cpan.org
definitely distracts potential users. I know that there is some
documentation available at pdl.perl.org but people already using perl
(like me) will very likely first try to look at PDL documentation at
metacpan.org and/or search.cpan.org.
I have made a proof-of-concept experiment with PDL::LinearAlgebra
*/ before experiment there was LinearAlgebra-0.08
- https://metacpan.org/release/CHM/PDL-LinearAlgebra-0.08
- http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08
*/ let's have a look at PDL::LinearAlgebra::Real
- metacpan.org is not able to show any documentation
- search.cpan.org show something but it is "ugly"
http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08/Real/real.pd
*/ after couple of attempts I have ended up with a hack like this
-
https://metacpan.org/source/CHM/PDL-LinearAlgebra-0.08_03/Makefile.PL#L23
- In shot: during "make dist" phase it creates "GENERATED"
subdirectory with *.pm files corresponding to *.pd files (no changes in
module code, just one simple GENERATED subdir which is automatically
generated)
*/ the final tarball going to CPAN has the following content
- https://metacpan.org/source/CHM/PDL-LinearAlgebra-0.08_03 (see
GENERATED subdir)
-
https://metacpan.org/pod/release/CHM/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm
-
http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm
*/ The hack is is quite simple if your distribution contains just one
*.pd file like my module PDL::Finance::TA
https://metacpan.org/source/KMX/PDL-Finance-TA-0.008/Makefile.PL#L72
- https://metacpan.org/pod/PDL::Finance::TA
- http://search.cpan.org/perldoc?PDL::Finance::TA
- in distributions with more *.pd files it gets a bit more
complicated, but still doable
My suggestion is to have a discussion whether this hack or something
similar (or maybe something completely different) is OK and declare it as a
"recommended way".
1/ we should patch PDL (core distribution) to have nice doc at metacpan.org
2/ maybe we can patch PDL/Core/Dev.pm (sub pdlpp_stdargs_int) to
generate proper dist => {PREOP=>'...'} automatically
Opinions?
--
kmx
_______________________________________________
PDL-porters mailing list
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters

--
Bryan Jurish "There is *always* one more bug."
_______________________________________________
PDL-porters mailing list
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters

_______________________________________________
PDL-porters mailing list
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters

_______________________________________________
_______________________________________________
PDL-porters mailing list
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters

[kmx]

David,

my example demonstrates not only a problem with metacpan:
https://metacpan.org/release/Acme-KMX-Test
but also with search.cpan.org
http://search.cpan.org/dist/Acme-KMX-Test/

Note for those who do not follow the whole discussion:
On both sites there completely missing modules Acme::KMX::Pokus1 and
Acme::KMX::Pokus2 that are generated from .pm.PL files

So it is not enough to convince metacpan.org developers but also
search.cpan.org developers + others that are about to come in the future
with similar site.

The conversion of *.<ext>.PL into *.<ext> is a feature of
ExtUtils::MakeMaker (look for PL_FILES option) andIMO neither metacpan.org
nor search.cpan.org never claimed to support this (so I would be careful to
call it a metacpan bug).

Besides that if I were on metacpan side I would be worried about:

1/ launching any *.pm.PL file comming from any CPAN distribution imposes
quite serious security risk

2/ in case of PDL related distributions we expect that the environment in
which *.pm.PL is executed has installed PDL core (as it will definitely
need something like PDL::PP PDL::Core::Dev ...)

3/ in general case the indexer should probably install all prerequisites
for all modules containing *.<whatever>.PL

Frankly speaking implementing 1/ .. 3/ on metacpan side seems to me quite
complicated with serious security consequences and potential performance
impact. Now, as mentioned above you not only have to convince metacpan.org
but also search.cpan.org developers.

I am not saying that it is not possible but I consider it too complicated
and not applicable to *.pd files (so it will not help with PDL 2
documentation). It will take months if not year(s) + it requires
co-ordination with two other projects whereas using approach I am proposing
we can have complete PDL documentation on metacpan.org and search.cpan.org
tomorrow (and the decision depends just on us).

To sum up:
There was a question whether using *.pm.PL or *.xs.PL or even *.pd.PL can
fix documentation issue on metacpan and search.cpan.org.
And the answer is: No.

--
kmx

Post by David Mertens
Hey kmx,
I believe this is a bug with MetaCPAN. The original bug filed is
https://github.com/CPAN-API/metacpan-web/issues/679.
I have added a link to your recent distribution. Apparently, it was
thought that .pm.PL files would be indexed, but your example dist shows
this is not the case. Hopefully we can get this resolved so that, at the
very least, the documentation for .pm.PL and like files can get properly
indexed.
David
Hi Joel,
https://metacpan.org/source/KMX/Acme-KMX-Test-0.005
Acme::KMX::Test
Acme::KMX::Pokus1 (generated from Pokus1.pm.PL <http://Pokus1.pm.PL>)
Acme::KMX::Pokus2 (generated from Pokus2.pm.PL <http://Pokus2.pm.PL>)
(try "cpanm Acme::KMX::Test" and you will have all 3 installed)
https://metacpan.org/release/KMX/Acme-KMX-Test-0.005
there is no documentation for
Acme::KMX::Pokus1
Acme::KMX::Pokus2
So, yes using *.xs.PL or *.pm.PL or *.pd.PL in PDL3 is worth
considering, however it will not solve the troubles with
documentation at metacpan.org <http://metacpan.org> as metacpan does
not seem to execute *.pm.PL files before indexing.
Of course there might be something completely wrong in my
Acme-KMX-Test (feel free to correct me).
--
kmx

Post by Joel Berger
The .PL extension means that when executed the file itself generates
a file of the same name except without the .PL. This is why .xs.PL
is probably the right name (though, IIRC it also generates a .pm
file, so it could be argued to be .pm.PL too). While I could see
arguments that .pd is historically used and we could campaign for
the sites to use them as intended, I think that using .pd.PL would
give the wrong idea to anyone else from the Perl community; it
doesn't generate a .pd file.
On Thu, Dec 18, 2014 at 8:24 AM, Chris Marshall
How about .pd.PL rather than .xs.PL to indicate that the content
is specifically PDL::PP rather than just any-old-perl-to-xs code?
On Thu, Dec 18, 2014 at 9:20 AM, Chris Marshall
If we make the change of filename .pd to .xs.PL does
that fix the problem? I don't recall the specific discussion
of why or why not for ..pd versus .xs.PL. If it was
compatibility, maybe PDL::Tiny and PDL3 would be
a good time to revisit this.
--Chris
On Thu, Dec 18, 2014 at 9:16 AM, Bryan Jurish
moin kmx,
fwiw, i've been using something very similar to what
you're proposing, to wit: pre-generating *.pm and
including them in the archive uploaded to cpan. in my
case, i ended up wrapping the functionality into a
"pdlmaker.plm" file included by Makefile.PL; see e.g.
https://metacpan.org/source/MOOCOW/PDL-HMM-0.06002/pdlmaker.plm
: it works by scanning the MANIFEST for *.pd files and
asssociated *.pm files (if present in a second column).
+ i like your idea of using a dedicated "GENERATED/"
subdirectory to put the dummy pm-files; a number of
"pdlmaker.plm" hacks were required to remove them at
configuration time
+ the PREOP code in PDL::Finance::TA looks a bit
unwieldy ... then again, it's quite regular and easy to
auto-generate with some extra perl code, or even
incorporate that into PDL::Core::Dev (as you
suggested... argh; sorry, wrote without thinking again)
... and a question: does this strategy actually keep
perl from installing stale GENERATED/*.pm files, or do
you need to define PM?
marmosets,
Bryan
Hi,
most of you probably know about incorrectly
displayed/parsed documentation for many PDL modules
(as well as PDL core) at https://metacpan.org/
The trouble is that metacpan.org
<http://metacpan.org> is not able to parse *.pd
files into proper *.pod documentation and to be
honest looking at documentation for PDL related perl
modules on metacpan.org <http://metacpan.org> or
search.cpan.org <http://search.cpan.org> definitely
distracts potential users. I know that there is some
documentation available at pdl.perl.org
<http://pdl.perl.org> but people already using perl
(like me) will very likely first try to look at PDL
documentation at metacpan.org <http://metacpan.org>
and/or search.cpan.org <http://search.cpan.org>.
I have made a proof-of-concept experiment with
*/ before experiment there was LinearAlgebra-0.08
-
https://metacpan.org/release/CHM/PDL-LinearAlgebra-0.08
- http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08
<http://search.cpan.org/%7Echm/PDL-LinearAlgebra-0.08>
*/ let's have a look at PDL::LinearAlgebra::Real
- metacpan.org <http://metacpan.org> is not able to
show any documentation
- search.cpan.org <http://search.cpan.org> show
something but it is "ugly"
http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08/Real/real.pd
<http://search.cpan.org/%7Echm/PDL-LinearAlgebra-0.08/Real/real.pd>
*/ after couple of attempts I have ended up with a
hack like this
-
https://metacpan.org/source/CHM/PDL-LinearAlgebra-0.08_03/Makefile.PL#L23
- In shot: during "make dist" phase it creates
"GENERATED" subdirectory with *.pm files
corresponding to *.pd files (no changes in module
code, just one simple GENERATED subdir which is
automatically generated)
*/ the final tarball going to CPAN has the following
content
-
https://metacpan.org/source/CHM/PDL-LinearAlgebra-0.08_03
(see GENERATED subdir)
*/ with my workaround you can see nice documentation
-
https://metacpan.org/pod/release/CHM/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm
-
http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm
<http://search.cpan.org/%7Echm/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm>
*/ The hack is is quite simple if your distribution
contains just one *.pd file like my module
PDL::Finance::TA
https://metacpan.org/source/KMX/PDL-Finance-TA-0.008/Makefile.PL#L72
- https://metacpan.org/pod/PDL::Finance::TA
- http://search.cpan.org/perldoc?PDL::Finance::TA
- in distributions with more *.pd files it gets a
bit more complicated, but still doable
My suggestion is to have a discussion whether this
hack or something similar (or maybe something
completely different) is OK and declare it as a
"recommended way".
1/ we should patch PDL (core distribution) to have
nice doc at metacpan.org <http://metacpan.org>
2/ maybe we can patch PDL/Core/Dev.pm (sub
pdlpp_stdargs_int) to generate proper dist =>
{PREOP=>'...'} automatically
Opinions?
--
kmx

[David Mertens]

Hey kmx,

Your conclusions are not quite right. For a counterexample, see my module,
PDL::Drawing::Prima:

http://search.cpan.org/~dcmertens/PDL-Drawing-Prima-0.10/
https://metacpan.org/release/PDL-Drawing-Prima

The module's documentation is correctly indexed and rendered on both sites.
Note, however, that I put my .pm.PL files in the lib/ directory, not in the
root directory. I believe that ExtUtils::MakeMaker imposes that .xx.PL
files must be in the root directory, but Module::Build allows .xx.PL files
to live anywhere. It appears that MetaCPAN and search.cpan.org
automatically do quite a bit with files that live in lib/, but files that
live elsewhere may need special notation in the meta.json and meta.yml
files.

Sorry for not thinking about this module sooner as it could have avoided
some confusion.

David

Post by kmx
David,
https://metacpan.org/release/Acme-KMX-Test
but also with search.cpan.org
http://search.cpan.org/dist/Acme-KMX-Test/
On both sites there completely missing modules Acme::KMX::Pokus1 and Acme::KMX::Pokus2
that are generated from .pm.PL files
So it is not enough to convince metacpan.org developers but also
search.cpan.org developers + others that are about to come in the future
with similar site.
The conversion of *.<ext>.PL into *.<ext> is a feature of
ExtUtils::MakeMaker (look for PL_FILES option) and IMO neither
metacpan.org nor search.cpan.org never claimed to support this (so I
would be careful to call it a metacpan bug).
1/ launching any *.pm.PL file comming from any CPAN distribution imposes
quite serious security risk
2/ in case of PDL related distributions we expect that the environment in
which *.pm.PL is executed has installed PDL core (as it will definitely
need something like PDL::PP PDL::Core::Dev ...)
3/ in general case the indexer should probably install all prerequisites
for all modules containing *.<whatever>.PL
Frankly speaking implementing 1/ .. 3/ on metacpan side seems to me quite
complicated with serious security consequences and potential performance
impact. Now, as mentioned above you not only have to convince metacpan.org
but also search.cpan.org developers.
I am not saying that it is not possible but I consider it too complicated
and not applicable to *.pd files (so it will not help with PDL 2
documentation). It will take months if not year(s) + it requires
co-ordination with two other projects whereas using approach I am proposing
we can have complete PDL documentation on metacpan.org and search.cpan.org
tomorrow (and the decision depends just on us).
There was a question whether using *.pm.PL or *.xs.PL or even *.pd.PL can
fix documentation issue on metacpan and search.cpan.org.
And the answer is: No.
--
kmx
Hey kmx,
I believe this is a bug with MetaCPAN. The original bug filed is
https://github.com/CPAN-API/metacpan-web/issues/679.
I have added a link to your recent distribution. Apparently, it was
thought that .pm.PL files would be indexed, but your example dist shows
this is not the case. Hopefully we can get this resolved so that, at the
very least, the documentation for .pm.PL and like files can get properly
indexed.
David

Post by kmx
Hi Joel,
https://metacpan.org/source/KMX/Acme-KMX-Test-0.005
Acme::KMX::Test
Acme::KMX::Pokus1 (generated from Pokus1.pm.PL)
Acme::KMX::Pokus2 (generated from Pokus2.pm.PL)
(try "cpanm Acme::KMX::Test" and you will have all 3 installed)
https://metacpan.org/release/KMX/Acme-KMX-Test-0.005
there is no documentation for
Acme::KMX::Pokus1
Acme::KMX::Pokus2
So, yes using *.xs.PL or *.pm.PL or *.pd.PL in PDL3 is worth considering,
however it will not solve the troubles with documentation at metacpan.org
as metacpan does not seem to execute *.pm.PL files before indexing.
Of course there might be something completely wrong in my Acme-KMX-Test
(feel free to correct me).
--
kmx
The .PL extension means that when executed the file itself generates a
file of the same name except without the .PL. This is why .xs.PL is
probably the right name (though, IIRC it also generates a .pm file, so it
could be argued to be .pm.PL too). While I could see arguments that .pd is
historically used and we could campaign for the sites to use them as
intended, I think that using .pd.PL would give the wrong idea to anyone
else from the Perl community; it doesn't generate a .pd file.

Post by Chris Marshall
How about .pd.PL rather than .xs.PL to indicate that the content is
specifically PDL::PP rather than just any-old-perl-to-xs code?

Post by Chris Marshall
If we make the change of filename .pd to .xs.PL does
that fix the problem? I don't recall the specific discussion
of why or why not for ..pd versus .xs.PL. If it was
compatibility, maybe PDL::Tiny and PDL3 would be
a good time to revisit this.
--Chris

Post by Bryan Jurish
moin kmx,
fwiw, i've been using something very similar to what you're
proposing, to wit: pre-generating *.pm and including them in the archive
uploaded to cpan. in my case, i ended up wrapping the functionality into a
"pdlmaker.plm" file included by Makefile.PL; see e.g.
https://metacpan.org/source/MOOCOW/PDL-HMM-0.06002/pdlmaker.plm : it
works by scanning the MANIFEST for *.pd files and asssociated *.pm files
(if present in a second column).
+ i like your idea of using a dedicated "GENERATED/" subdirectory to
put the dummy pm-files; a number of "pdlmaker.plm" hacks were required to
remove them at configuration time
+ the PREOP code in PDL::Finance::TA looks a bit unwieldy ... then
again, it's quite regular and easy to auto-generate with some extra perl
code, or even incorporate that into PDL::Core::Dev (as you suggested...
argh; sorry, wrote without thinking again)
... and a question: does this strategy actually keep perl from
installing stale GENERATED/*.pm files, or do you need to define PM?
marmosets,
Bryan

Post by kmx
Hi,
most of you probably know about incorrectly displayed/parsed
documentation for many PDL modules (as well as PDL core) at
https://metacpan.org/
The trouble is that metacpan.org is not able to parse *.pd files
into proper *.pod documentation and to be honest looking at documentation
for PDL related perl modules on metacpan.org or search.cpan.org
definitely distracts potential users. I know that there is some
documentation available at pdl.perl.org but people already using
perl (like me) will very likely first try to look at PDL documentation at
metacpan.org and/or search.cpan.org.
I have made a proof-of-concept experiment with PDL::LinearAlgebra
*/ before experiment there was LinearAlgebra-0.08
- https://metacpan.org/release/CHM/PDL-LinearAlgebra-0.08
- http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08
*/ let's have a look at PDL::LinearAlgebra::Real
- metacpan.org is not able to show any documentation
- search.cpan.org show something but it is "ugly"
http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08/Real/real.pd
*/ after couple of attempts I have ended up with a hack like this
-
https://metacpan.org/source/CHM/PDL-LinearAlgebra-0.08_03/Makefile.PL#L23
- In shot: during "make dist" phase it creates "GENERATED"
subdirectory with *.pm files corresponding to *.pd files (no changes in
module code, just one simple GENERATED subdir which is automatically
generated)
*/ the final tarball going to CPAN has the following content
- https://metacpan.org/source/CHM/PDL-LinearAlgebra-0.08_03 (see
GENERATED subdir)
-
https://metacpan.org/pod/release/CHM/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm
-
http://search.cpan.org/~chm/PDL-LinearAlgebra-0.08_03/GENERATED/Real.pm
*/ The hack is is quite simple if your distribution contains just one
*.pd file like my module PDL::Finance::TA
https://metacpan.org/source/KMX/PDL-Finance-TA-0.008/Makefile.PL#L72
- https://metacpan.org/pod/PDL::Finance::TA
- http://search.cpan.org/perldoc?PDL::Finance::TA
- in distributions with more *.pd files it gets a bit more
complicated, but still doable
My suggestion is to have a discussion whether this hack or something
similar (or maybe something completely different) is OK and declare it as a
"recommended way".
1/ we should patch PDL (core distribution) to have nice doc at metacpan.org
2/ maybe we can patch PDL/Core/Dev.pm (sub pdlpp_stdargs_int) to
generate proper dist => {PREOP=>'...'} automatically
Opinions?
--
kmx

_______________________________________________
PDL-porters mailing list
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters

[David Mertens]

Oh, a few more clarifications in light of PDL::Drawing::Prima...

Post by kmx
David,
https://metacpan.org/release/Acme-KMX-Test
but also with search.cpan.org
http://search.cpan.org/dist/Acme-KMX-Test/
On both sites there completely missing modules Acme::KMX::Pokus1 and Acme::KMX::Pokus2
that are generated from .pm.PL files

This is correct, but it's not clear why it failed for your modules and not
for mine. It may be possible to get the files properly rendered if they are
indicated specially in the meta files, or if they live in the lib/
directory, or some other magic. The magic is not clear at this point.

Post by kmx
So it is not enough to convince metacpan.org developers but also
search.cpan.org developers + others that are about to come in the future
with similar site.

I suspect that marking files in the meta files is the real magic, so
convincing future site developers to work with the meta spec is probably
sufficient.

Post by kmx
The conversion of *.<ext>.PL into *.<ext> is a feature of
ExtUtils::MakeMaker (look for PL_FILES option) and IMO neither
metacpan.org nor search.cpan.org never claimed to support this (so I
would be careful to call it a metacpan bug).

They do not and will not. Documentation for my files is pulled DIRECTLY
from the .xx.PL files. It's identical to saying at your command prompt
"perldoc MyModule.pm.PL". They do not execute any code directly from the
tarball.

Post by kmx
<snip>

I am not saying that it is not possible but I consider it too complicated

Post by kmx
and not applicable to *.pd files (so it will not help with PDL 2
documentation). It will take months if not year(s) + it requires
co-ordination with two other projects whereas using approach I am proposing
we can have complete PDL documentation on metacpan.org and search.cpan.org
tomorrow (and the decision depends just on us).

It is possible. It's not as difficult as you had guessed, but it is a huge
pain, and leads to rather confusing .pm.PL source files. Having done this
for bad.pd, I recommend *against* renaming .pd -> .pm.PL. I prefer your
approach.

Post by kmx
There was a question whether using *.pm.PL or *.xs.PL or even *.pd.PL can
fix documentation issue on metacpan and search.cpan.org.
And the answer is: No.

The answer is certainly: Yes, but it's not worth the effort. Your solution
is easier. I say we use kmx's documentation generation hack, and document
it as the easiest way to get things to work for PDL developers using
ExtUtils::MakeMaker. I would also appreciate if a similar thing could be
written for Module::Build as I use that to distribute my modules, but I
don't think the lack of such a facility is a show stopper.

David

[kmx]

Post by David Mertens
Oh, a few more clarifications in light of PDL::Drawing::Prima...
David,
https://metacpan.org/release/Acme-KMX-Test
but also with search.cpan.org <http://search.cpan.org>
http://search.cpan.org/dist/Acme-KMX-Test/
On both sites there completely missing modules Acme::KMX::Pokus1 and
Acme::KMX::Pokus2 that are generated from .pm.PL files
This is correct, but it's not clear why it failed for your modules and
not for mine. It may be possible to get the files properly rendered if
they are indicated specially in the meta files, or if they live in the
lib/ directory, or some other magic. The magic is not clear at this point.
So it is not enough to convince metacpan.org <http://metacpan.org>
developers but also search.cpan.org <http://search.cpan.org>
developers + others that are about to come in the future with similar
site.
I suspect that marking files in the meta files is the real magic, so
convincing future site developers to work with the meta spec is probably
sufficient.
The conversion of *.<ext>.PL into *.<ext> is a feature of
ExtUtils::MakeMaker (look for PL_FILES option) andIMO neither
metacpan.org <http://metacpan.org> nor search.cpan.org
<http://search.cpan.org> never claimed to support this (so I would be
careful to call it a metacpan bug).
They do not and will not. Documentation for my files is pulled DIRECTLY
from the .xx.PL files. It's identical to saying at your command prompt
"perldoc MyModule.pm.PL <http://MyModule.pm.PL>". They do not execute any
code directly from the tarball.

Yes, and it is important to keep it in mind: "No *.<ext>.PL will ever be
executed before metacpan indexing"

This is the reason why this kind of indexing will never work 100% for *.pd
files (renamed to *.<whatever>.PL) using pp_def(..) for creating function
with Doc=>...

Consider a *.pd code (real code from my module):

pp_def('ta_dema',
Pars => 'double inpdl(n); int InTimePeriod(); double [o]outpdl(n);',
GenericTypes => ['D'],
Code => q{
...
},
Doc => <<'END',
Calculates Double Exponential Moving Average

some other info
END
);

Your workaround for this is to use:

Doc => <<'END',
=head2 ta_dema

=for sig

Signature: (double inpdl(n); int InTimePeriod(); double [o]outpdl(n))

=for ref

Calculates Double Exponential Moving Average

some other info
END

But what if you want to use a interpolated perl variable in Doc string? In
that case even your workaround will fail. You have also duplicate signature
info ...

Post by David Mertens
<snip>
I am not saying that it is not possible but I consider it too
complicated and not applicable to *.pd files (so it will not help
with PDL 2 documentation). It will take months if not year(s) + it
requires co-ordination with two other projects whereas using approach
I am proposing we can have complete PDL documentation on metacpan.org
<http://metacpan.org> and search.cpan.org <http://search.cpan.org>
tomorrow (and the decision depends just on us).
It is possible. It's not as difficult as you had guessed, but it is a
huge pain, and leads to rather confusing .pm.PL source files. Having done
this for bad.pd, I recommend *against* renaming .pd -> .pm.PL. I prefer
your approach.

OK, in that case let's do it :)

Post by David Mertens
There was a question whether using *.pm.PL or *.xs.PL or even *.pd.PL
can fix documentation issue on metacpan and search.cpan.org
<http://search.cpan.org>.
And the answer is: No.
The answer is certainly: Yes, but it's not worth the effort. Your
solution is easier. I say we use kmx's documentation generation hack, and
document it as the easiest way to get things to work for PDL developers
using ExtUtils::MakeMaker. I would also appreciate if a similar thing
could be written for Module::Build as I use that to distribute my
modules, but I don't think the lack of such a facility is a show stopper.

For Module::Build it is quite simple.

By subclassing Module::Build with this overridden method:

sub ACTION_dist {
my $self = shift;
$self->dispatch('distdir');
my $dir = $self->dist_dir;
my $cmd = [qw{-Iblib/arch -Iblib -MPDL::Core::Dev -e
pdlpp_dist_preop}, $dir];
$self->run_perl_command($cmd) or die "pdlpp_dist_preop FAILED";
$self->make_tarball($dir);
$self->delete_filetree($dir);
}

My question is: where should this Module::Build hack go? to
Module::Build::PDL? or somewhere else?

--
kmx

[kmx]

Post by Bryan Jurish
moin kmx,
fwiw, i've been using something very similar to what you're proposing, to
wit: pre-generating *.pm and including them in the archive uploaded to
cpan. in my case, i ended up wrapping the functionality into a
"pdlmaker.plm" file included by Makefile.PL; see e.g.
https://metacpan.org/source/MOOCOW/PDL-HMM-0.06002/pdlmaker.plm : it
works by scanning the MANIFEST for *.pd files and asssociated *.pm files
(if present in a second column).

Using MANIFEST as a source of all *.pd files in distribution is a very good
point, it can make things even easier.

In an extreme case we might squeeze relevant Makefile.PL section into
something like this (only idea, not a serious code):

dist => {
PREOP => '$(PERL) -MPDL::Dev=mkpreop -E mkpreop $(DISTVNAME)'
}

where mkpreop function will scan MANIFEST and convert all *.pd files into
$(DISTVNAME)/GENERATED/*.pm files

Post by Bryan Jurish
+ i like your idea of using a dedicated "GENERATED/" subdirectory to put
the dummy pm-files; a number of "pdlmaker.plm" hacks were required to
remove them at configuration time
+ the PREOP code in PDL::Finance::TA looks a bit unwieldy ... then again,
it's quite regular and easy to auto-generate with some extra perl code,
or even incorporate that into PDL::Core::Dev (as you suggested... argh;
sorry, wrote without thinking again)
... and a question: does this strategy actually keep perl from installing
stale GENERATED/*.pm files, or do you need to define PM?

Yes, these files are simply ignored by all CPAN clients (tested with: cpan,
cpanm, cpanp), which is good.


--
kmx

[kmx]

I have done further experiments and prepared a modified version based on
Bryan's MANIFEST scanning idea

1/ section in Makefile.PL now looks a bit less scary

dist => { PREOP => '$(PERL) -MPDL::Core::Dev -e pdlpp_dist_preop
$(DISTVNAME)' }

2/ even if the distribution contains more *.pd files it has the same simple
dist => { PREOP => ... } as in 1/

3/ I have added new sub pdlpp_dist_preop in PDL/Core/Dev.pm where all
necessary kung-fu happens

https://gist.github.com/kmx/22608eefeeb7e6c08c6e/revisions

4/ It woks like the original "solution" (with GENERATED subdir) with less
hacks in Makefile.PL


Now the troubles:

When we scan MANIFEST for all existing *.pd files we have all *.pd files;
however we do not know the corresponding module names or I least I do not
know how to extract the module name from *.pd file.

To handle this I have implemented two workarounds:
- guessing module name by searching for "=head1 NAME\nPDL::Module::Name
..." in *.pd file
- explicitly declaring module name in Makefile.PL like this:
dist => { PREOP => '$(PERL) -MPDL::Core::Dev -e pdlpp_dist_preop
$(DISTVNAME) Fxy.pd PDL::Module::Fxy' }
Yes, a bit ugly (it might be a good idea for PDL3 to make module name
extractable from *.pd).

Another issue is (was) how to do the *.pd >> *.pm+*.xs conversion from perl
code. Unfortunately I ended up with this:
system($^X, "-MPDL::PP qw[$mod $mod $prefix]", $pd);

Attempts to call:
require PDL::PP;
PDL::PP->import($mod, $mod, $prefix, $pd);
PDL::PP->pp_done;
did not work well.

Anyway improved patch is available at the URL above.

--
kmx

Post by kmx

Post by Bryan Jurish
moin kmx,
fwiw, i've been using something very similar to what you're proposing,
to wit: pre-generating *.pm and including them in the archive uploaded
to cpan. in my case, i ended up wrapping the functionality into a
"pdlmaker.plm" file included by Makefile.PL; see e.g.
https://metacpan.org/source/MOOCOW/PDL-HMM-0.06002/pdlmaker.plm : it
works by scanning the MANIFEST for *.pd files and asssociated *.pm files
(if present in a second column).

Using MANIFEST as a source of all *.pd files in distribution is a very
good point, it can make things even easier.
In an extreme case we might squeeze relevant Makefile.PL section into
dist => {
PREOP => '$(PERL) -MPDL::Dev=mkpreop -E mkpreop $(DISTVNAME)'
}
where mkpreop function will scan MANIFEST and convert all *.pd files into
$(DISTVNAME)/GENERATED/*.pm files

Post by Bryan Jurish
+ i like your idea of using a dedicated "GENERATED/" subdirectory to put
the dummy pm-files; a number of "pdlmaker.plm" hacks were required to
remove them at configuration time
+ the PREOP code in PDL::Finance::TA looks a bit unwieldy ... then
again, it's quite regular and easy to auto-generate with some extra perl
code, or even incorporate that into PDL::Core::Dev (as you suggested...
argh; sorry, wrote without thinking again)
... and a question: does this strategy actually keep perl from
installing stale GENERATED/*.pm files, or do you need to define PM?

cpan, cpanm, cpanp), which is good.
--
kmx

[Bryan Jurish]

On Fri, Dec 19, 2014 at 1:32 AM, kmx <***@atlas.cz> wrote:
[...]

Post by kmx
When we scan MANIFEST for all existing *.pd files we have all *.pd files;
however we do not know the corresponding module names or I least I do not
know how to extract the module name from *.pd file.

ExtUtils::MANIFEST treats anything beyond the first whitespace in a line as
a commet; cf https://metacpan.org/pod/ExtUtils::Manifest#MANIFEST . the
"pdlmaker.plm" heuristics are:

1: if a comment is present for a *.pd file, trim any leading "#" and
whitespace, and assume the result is the name of the generated *.pm file
(see e.g. https://metacpan.org/source/MOOCOW/PDL-CCS-1.20.2/MANIFEST for a
nontrivial example)

2: otherwise, assume FILE.pd generates FILE.pm

.... the strategy in (1) could be extended to allow "real" comments for
*.pd files as well, say anything after the second whitespace. i think your
suggestion of scanning the *.pd file for "=head1 NAME" is preferable is
preferable to strategy (2), but (1) still strikes me as sufficiently
flexible for most cases and more comfortable than direct overrides in
Makefile.PL.

marmosets,
Bryan

Post by kmx
I have done further experiments and prepared a modified version based on
Bryan's MANIFEST scanning idea
1/ section in Makefile.PL now looks a bit less scary
dist => { PREOP => '$(PERL) -MPDL::Core::Dev -e pdlpp_dist_preop
$(DISTVNAME)' }
2/ even if the distribution contains more *.pd files it has the same simple
dist => { PREOP => ... } as in 1/
3/ I have added new sub pdlpp_dist_preop in PDL/Core/Dev.pm where all
necessary kung-fu happens
https://gist.github.com/kmx/22608eefeeb7e6c08c6e/revisions
4/ It woks like the original "solution" (with GENERATED subdir) with less
hacks in Makefile.PL
When we scan MANIFEST for all existing *.pd files we have all *.pd files;
however we do not know the corresponding module names or I least I do not
know how to extract the module name from *.pd file.
- guessing module name by searching for "=head1 NAME\nPDL::Module::Name
..." in *.pd file
dist => { PREOP => '$(PERL) -MPDL::Core::Dev -e pdlpp_dist_preop
$(DISTVNAME) Fxy.pd PDL::Module::Fxy' }
Yes, a bit ugly (it might be a good idea for PDL3 to make module name
extractable from *.pd).
Another issue is (was) how to do the *.pd >> *.pm+*.xs conversion from
system($^X, "-MPDL::PP qw[$mod $mod $prefix]", $pd);
require PDL::PP;
PDL::PP->import($mod, $mod, $prefix, $pd);
PDL::PP->pp_done;
did not work well.
Anyway improved patch is available at the URL above.
--
kmx
moin kmx,
fwiw, i've been using something very similar to what you're proposing, to
wit: pre-generating *.pm and including them in the archive uploaded to
cpan. in my case, i ended up wrapping the functionality into a
"pdlmaker.plm" file included by Makefile.PL; see e.g.
https://metacpan.org/source/MOOCOW/PDL-HMM-0.06002/pdlmaker.plm : it
works by scanning the MANIFEST for *.pd files and asssociated *.pm files
(if present in a second column).
Using MANIFEST as a source of all *.pd files in distribution is a very
good point, it can make things even easier.
In an extreme case we might squeeze relevant Makefile.PL section into
dist => {
PREOP => '$(PERL) -MPDL::Dev=mkpreop -E mkpreop $(DISTVNAME)'
}
where mkpreop function will scan MANIFEST and convert all *.pd files into
$(DISTVNAME)/GENERATED/*.pm files
+ i like your idea of using a dedicated "GENERATED/" subdirectory to put
the dummy pm-files; a number of "pdlmaker.plm" hacks were required to
remove them at configuration time
+ the PREOP code in PDL::Finance::TA looks a bit unwieldy ... then again,
it's quite regular and easy to auto-generate with some extra perl code, or
even incorporate that into PDL::Core::Dev (as you suggested... argh; sorry,
wrote without thinking again)
... and a question: does this strategy actually keep perl from installing
stale GENERATED/*.pm files, or do you need to define PM?
cpan, cpanm, cpanp), which is good.
--
kmx
_______________________________________________
PDL-porters mailing list
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters

[kmx]

Bryan,

ad ExtUtils::Manifest - you are right, I'll switch to this module in the
next version of my patch as there are too many corner cases to do it
correctly on my own

ad extracting (or not) module name from *.pd files - I am convinced that we
simply need the module name because we have to pass it to PDL::PP,
otherwise the resulting *.pm files will not have correct "package
PDL::Module::Name" declaration (which is crucial for at least metacpan.org
idexer).

Thanks for your feedback. I'll prepare updated patch during the weekend.

--
kmx

Post by kmx
[...]
When we scan MANIFEST for all existing *.pd files we have all *.pd
files; however we do not know the corresponding module names or I
least I do not know how to extract the module name from *.pd file.
ExtUtils::MANIFEST treats anything beyond the first whitespace in a line
as a commet; cf https://metacpan.org/pod/ExtUtils::Manifest#MANIFEST .
1: if a comment is present for a *.pd file, trim any leading "#" and
whitespace, and assume the result is the name of the generated *.pm file
(see e.g. https://metacpan.org/source/MOOCOW/PDL-CCS-1.20.2/MANIFEST for
a nontrivial example)
2: otherwise, assume FILE.pd generates FILE.pm
.... the strategy in (1) could be extended to allow "real" comments for
*.pd files as well, say anything after the second whitespace. i think
your suggestion of scanning the *.pd file for "=head1 NAME" is preferable
is preferable to strategy (2), but (1) still strikes me as sufficiently
flexible for most cases and more comfortable than direct overrides in
Makefile.PL.
marmosets,
Bryan
I have done further experiments and prepared a modified version based
on Bryan's MANIFEST scanning idea
1/ section in Makefile.PL now looks a bit less scary
dist => { PREOP => '$(PERL) -MPDL::Core::Dev -e pdlpp_dist_preop
$(DISTVNAME)' }
2/ even if the distribution contains more *.pd files it has the same
simple dist => { PREOP => ... } as in 1/
3/ I have added new sub pdlpp_dist_preop in PDL/Core/Dev.pm where all
necessary kung-fu happens
https://gist.github.com/kmx/22608eefeeb7e6c08c6e/revisions
4/ It woks like the original "solution" (with GENERATED subdir) with
less hacks in Makefile.PL
When we scan MANIFEST for all existing *.pd files we have all *.pd
files; however we do not know the corresponding module names or I
least I do not know how to extract the module name from *.pd file.
- guessing module name by searching for "=head1
NAME\nPDL::Module::Name ..." in *.pd file
dist => { PREOP => '$(PERL) -MPDL::Core::Dev -e
pdlpp_dist_preop $(DISTVNAME) Fxy.pd PDL::Module::Fxy' }
Yes, a bit ugly (it might be a good idea for PDL3 to make module name
extractable from *.pd).
Another issue is (was) how to do the *.pd >> *.pm+*.xs conversion
system($^X, "-MPDL::PP qw[$mod $mod $prefix]", $pd);
require PDL::PP;
PDL::PP->import($mod, $mod, $prefix, $pd);
PDL::PP->pp_done;
did not work well.
Anyway improved patch is available at the URL above.
--
kmx

Post by kmx

Post by Bryan Jurish
moin kmx,
fwiw, i've been using something very similar to what you're
proposing, to wit: pre-generating *.pm and including them in the
archive uploaded to cpan. in my case, i ended up wrapping the
functionality into a "pdlmaker.plm" file included by Makefile.PL;
see e.g.
it works by scanning the MANIFEST for *.pd files and asssociated
*.pm files (if present in a second column).

Using MANIFEST as a source of all *.pd files in distribution is a
very good point, it can make things even easier.
In an extreme case we might squeeze relevant Makefile.PL section
dist => {
PREOP => '$(PERL) -MPDL::Dev=mkpreop -E mkpreop $(DISTVNAME)'
}
where mkpreop function will scan MANIFEST and convert all *.pd files
into $(DISTVNAME)/GENERATED/*.pm files

Post by Bryan Jurish
+ i like your idea of using a dedicated "GENERATED/" subdirectory
to put the dummy pm-files; a number of "pdlmaker.plm" hacks were
required to remove them at configuration time
+ the PREOP code in PDL::Finance::TA looks a bit unwieldy ... then
again, it's quite regular and easy to auto-generate with some extra
perl code, or even incorporate that into PDL::Core::Dev (as you
suggested... argh; sorry, wrote without thinking again)
... and a question: does this strategy actually keep perl from
installing stale GENERATED/*.pm files, or do you need to define PM?

Yes, these files are simply ignored by all CPAN clients (tested
with: cpan, cpanm, cpanp), which is good.
--
kmx

_______________________________________________
PDL-porters mailing list
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters
--
Bryan Jurish "There is *always* one more bug."
-Lubarsky's Law of Cybernetic Entomology

[kmx]

... I'll prepare updated patch during the weekend.

Here is my patch:
https://github.com/kmx/pdl/commit/a6e198f6dc713bfd08164174517befd6cc8ef349

1/ new sub pdlpp_dist_preop() was added to PDL::Core::Dev

2/ PDL core's Makefile.PL was updated to call the new function
pdlpp_dist_preop during "make dist"

3/ if any other PDL related distribution wants to do the same trick it can
be done by adding
dist => { PREOP => '$(PERL) -I$(INST_ARCHLIB) -I$(INST_LIB)
-MPDL::Core::Dev -e pdlpp_dist_preop $(DISTVNAME)' }

4/ I have also modified pdlpp_stdargs() which now creates dist => { PREOP
=> ... } line mentioned in 3/ automatically

Creating PDL core tarball via "make dist" works as intended (contains
subdir GENERATED).

--
kmx

[Chris Marshall]

All-

From the discussion, it appears there is a consensus that this is a
persistent problem for PDL, definitely worthy of multiple solutions in core
PDL and in external PDL modules. kmx has volunteered to work the
implementation as discussed for the PDL-2.008 release. I propose starting
with a new CPAN developers release of PDL once this patch has been applied
to master. That will give time for any iterations or further refinement
before the formal release.

As usual, comments or other feedback welcome.

--Chris

... I'll prepare updated patch during the weekend.
https://github.com/kmx/pdl/commit/a6e198f6dc713bfd08164174517befd6cc8ef349
1/ new sub pdlpp_dist_preop() was added to PDL::Core::Dev
2/ PDL core's Makefile.PL was updated to call the new function
pdlpp_dist_preop during "make dist"
3/ if any other PDL related distribution wants to do the same trick it can
be done by adding
dist => { PREOP => '$(PERL) -I$(INST_ARCHLIB) -I$(INST_LIB)
-MPDL::Core::Dev -e pdlpp_dist_preop $(DISTVNAME)' }
4/ I have also modified pdlpp_stdargs() which now creates dist => {
PREOP => ... } line mentioned in 3/ automatically
Creating PDL core tarball via "make dist" works as intended (contains
subdir GENERATED).
--
kmx
_______________________________________________
PDL-porters mailing list
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters

[Ed .]

I propose starting with a new CPAN developers release of PDL once this
patch has been applied to master. That will give time for any iterations
or further refinement before the formal release.
As usual, comments or other feedback welcome.

Once again I suggest that as with each of the previous dev releases, a
production release then be made after a decent interval (a week) to make
sure cpantesters don't reveal any regressions. (Less than) Once a year is a
problem for attracting contributors. Let me illustrate how.

A new contributor (NC) wants PDL to have some new core capability that can't
be done in a separate module - to pick a completely made-up example, to fix
a fatal bug in the PDL_BOOT code. She looks for the usual open-source
avenue: a github repository to fork, update and issue a pull request. As a
good engineer she even wants to include a test to avoid future regressions.
PDL doesn't have one of those. Oh, a sourceforge one, good enough. She goes
through the clunkier process of the sourceforge merge-request, and waits for
feedback.

Scenario 1: And waits. And waits. And loses interest. She spots a different
problem a month or two later, but does nothing because she knows it's not
worth it.

Scenario 2: People comment on the MR, and she improves the test to make it
more general and test the other PDL_* functions in Core::Dev. Within a few
days, it's merged. A week or two later, a dev release is issued. A week
after that, the next main release comes out. All the users of the project
benefit from slightly better-working code. Contributor is pleased and knows
next time they spot a problem, it will actually end up fixed quite soon, for
everyone.

This is not some wild speculation, by the way. This is how open-source
projects work[1]. Do feel free however to ignore it and continue with
business as usual.

Best regards,
Ed

[1] "The Cathedral and the Bazaar" -
http://www.catb.org/~esr/writings/cathedral-bazaar/cathedral-bazaar/

[Chris Marshall]

Post by Ed .

I propose starting with a new CPAN developers release of PDL once this
patch has been applied to master. That will give time for any iterations
or further refinement before the formal release.
As usual, comments or other feedback welcome.

Once again I suggest that as with each of the previous dev releases, a
production release then be made after a decent interval (a week) to make
sure cpantesters don't reveal any regressions. (Less than) Once a year is a
problem for attracting contributors. Let me illustrate how.

CPAN developers releases are made specifically because they are tested by
CPAN Testers. The idea is that the PDL development be tracked as far as
how it tests on multiple perl platforms which are not available or used by
PDL developers or other contributors. If someone has a need for a new,
official release of PDL to support some requirement that cannot be met by
the CPAN developer release snapshots----such as supporting the release of
XXX that needs to use or refer to the new PDL version in an official
capacity---we're happy to push the current master through QA for a formal
release.

--Chris

A new contributor (NC) wants PDL to have some new core capability that

Post by Ed .
can't be done in a separate module - to pick a completely made-up example,
to fix a fatal bug in the PDL_BOOT code. She looks for the usual
open-source avenue: a github repository to fork, update and issue a pull
request. As a good engineer she even wants to include a test to avoid
future regressions. PDL doesn't have one of those. Oh, a sourceforge one,
good enough. She goes through the clunkier process of the sourceforge
merge-request, and waits for feedback.
Scenario 1: And waits. And waits. And loses interest. She spots a
different problem a month or two later, but does nothing because she knows
it's not worth it.
Scenario 2: People comment on the MR, and she improves the test to make it
more general and test the other PDL_* functions in Core::Dev. Within a few
days, it's merged. A week or two later, a dev release is issued. A week
after that, the next main release comes out. All the users of the project
benefit from slightly better-working code. Contributor is pleased and knows
next time they spot a problem, it will actually end up fixed quite soon,
for everyone.
This is not some wild speculation, by the way. This is how open-source
projects work[1]. Do feel free however to ignore it and continue with
business as usual.
Best regards,
Ed
[1] "The Cathedral and the Bazaar" - http://www.catb.org/~esr/
writings/cathedral-bazaar/cathedral-bazaar/

[kmx]

So now we have improved doc at:
https://metacpan.org/release/CHM/PDL-2.007_07

but there are two UNAUTHORIZED errors:
- PDL::Slatec (according to PAUSE owned by PERLDL account)
- PDL::Graphics::PLplot (according to PAUSE owned by DHUNT - Douglas Hunt)

Chris, you will very likely need to get co-main for those two.

--
kmx

[Chris Marshall]

My guess is that the GENERATED files now exposed these to the indexer where
before they were missed.

Post by kmx
https://metacpan.org/release/CHM/PDL-2.007_07
- PDL::Slatec (according to PAUSE owned by PERLDL account)
- PDL::Graphics::PLplot (according to PAUSE owned by DHUNT - Douglas Hunt)
Chris, you will very likely need to get co-main for those two.
--
kmx
_______________________________________________
PDL-porters mailing list
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters

[Doug Hunt]

Hi PDL porters: I'm sorry I've been mostly missing from
PDL::Graphics::PLplot maintenance recently. What needs to be done for
this 'UNAUTHORIZED' error?

--Doug

Post by kmx
https://metacpan.org/release/CHM/PDL-2.007_07
- PDL::Slatec (according to PAUSE owned by PERLDL account)
- PDL::Graphics::PLplot (according to PAUSE owned by DHUNT - Douglas Hunt)
Chris, you will very likely need to get co-main for those two.
--
kmx
_______________________________________________
PDL-porters mailing list
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters

[Chris Marshall]

Hi Doug-

I've been able to build the latest PLplot library on cygwin pretty much out
of the box. I haven't had the chance to try building PDL::Graphics::PLplot
yet.

As for the permissions, you can go to the http://pause.perl.org and login
under your PAUSE user account. The select "Change Permissions" from the
left side bar and under section 3 of that page add me, CHM, as a
co-maintainer for PDL::Graphics::PLplot.

Cheers,
Chris

Post by Doug Hunt
Hi PDL porters: I'm sorry I've been mostly missing from
PDL::Graphics::PLplot maintenance recently. What needs to be done for this
'UNAUTHORIZED' error?
--Doug

Post by kmx
https://metacpan.org/release/CHM/PDL-2.007_07
- PDL::Slatec (according to PAUSE owned by PERLDL account)
- PDL::Graphics::PLplot (according to PAUSE owned by DHUNT - Douglas Hunt)
Chris, you will very likely need to get co-main for those two.
--
kmx
_______________________________________________
PDL-porters mailing list
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters

_______________________________________________
PDL-porters mailing list
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters

[Doug Hunt]

Hi Chris: I just did a likely-seeming thing on PAUSE (see attached
screenshot). Please let me know if this does the trick for you.

Thanks for all your work!

--Doug

Post by Chris Marshall
Hi Doug-
I've been able to build the latest PLplot library on cygwin pretty much
out of the box. I haven't had the chance to try building
PDL::Graphics::PLplot yet.
As for the permissions, you can go to the http://pause.perl.org and
login under your PAUSE user account. The select "Change Permissions"
from the left side bar and under section 3 of that page add me, CHM, as
a co-maintainer for PDL::Graphics::PLplot.
Cheers,
Chris
Hi PDL porters: I'm sorry I've been mostly missing from
PDL::Graphics::PLplot maintenance recently. What needs to be done
for this 'UNAUTHORIZED' error?
--Doug
https://metacpan.org/release/__CHM/PDL-2.007_07
<https://metacpan.org/release/CHM/PDL-2.007_07>
- PDL::Slatec (according to PAUSE owned by PERLDL account)
- PDL::Graphics::PLplot (according to PAUSE owned by DHUNT - Douglas Hunt)
Chris, you will very likely need to get co-main for those two.
--
kmx
_________________________________________________
PDL-porters mailing list
http://mailman.jach.hawaii.__edu/mailman/listinfo/pdl-__porters
<http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters>
_________________________________________________
PDL-porters mailing list
http://mailman.jach.hawaii.__edu/mailman/listinfo/pdl-__porters
<http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters>

[Chris Marshall]

Looks good. Thanks, Chris.

[kmx]

Proposed changes discussed in this thread committed as:
http://sourceforge.net/p/pdl/code/ci/8b36770fdde280f94005db6f814867d68f3a8dc5/

--
kmx

Post by Chris Marshall
All-
From the discussion, it appears there is a consensus that this is a
persistent problem for PDL, definitely worthy of multiple solutions in
core PDL and in external PDL modules. kmx has volunteered to work the
implementation as discussed for the PDL-2.008 release. I propose
starting with a new CPAN developers release of PDL once this patch has
been applied to master. That will give time for any iterations or
further refinement before the formal release.
As usual, comments or other feedback welcome.
--Chris

... I'll prepare updated patch during the weekend.

https://github.com/kmx/pdl/commit/a6e198f6dc713bfd08164174517befd6cc8ef349
1/ new sub pdlpp_dist_preop() was added to PDL::Core::Dev
2/ PDL core's Makefile.PL was updated to call the new function
pdlpp_dist_preop during "make dist"
3/ if any other PDL related distribution wants to do the same trick
it can be done by adding
dist => { PREOP => '$(PERL) -I$(INST_ARCHLIB) -I$(INST_LIB)
-MPDL::Core::Dev -e pdlpp_dist_preop $(DISTVNAME)' }
4/ I have also modified pdlpp_stdargs() which now creates dist => {
PREOP => ... } line mentioned in 3/ automatically
Creating PDL core tarball via "make dist" works as intended (contains
subdir GENERATED).
--
kmx
_______________________________________________
PDL-porters mailing list
http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters