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 <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 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-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 http://mailman.jach.hawaii.edu/mailman/listinfo/pdl-porters
