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
<dcmertens.p...@gmail.com <mailto:dcmertens.p...@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
<devel.chm...@gmail.com <mailto:devel.chm...@gmail.com>> wrote:
What are FullDocs?
On Thu, Dec 18, 2014 at 8:56 AM, David Mertens
<dcmertens.p...@gmail.com <mailto:dcmertens.p...@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 <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/%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
On Thu, Dec 18, 2014 at 3:51 AM, kmx <k...@atlas.cz
<mailto:k...@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
<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
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
<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
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
<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
- 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 <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
PDL-porters@jach.hawaii.edu
<mailto:PDL-porters@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-porters@jach.hawaii.edu
<mailto:PDL-porters@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
