We should probably add documentation for this if we're supporting it.
On Thu, Dec 18, 2014 at 7:52 PM, David Mertens <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> > wrote: >> >> What are FullDocs? >> >> On Thu, Dec 18, 2014 at 8:56 AM, David Mertens <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 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 >>> >>> > > -- > "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
