pdl-io-gd split tasks

[zmughal]

• standalone Makefile.PL: done
• add repository info to metadata: done
• make sure PDL tests for this module are available: done
• check that Travis-CI builds work: done
• check that Appveyor builds work
• add badges to README (coverage, etc.): done in add README.md #4
• prep Changes for new version. Make note that the next release is its own repo and distro: done
• add xt/00-check-changelog.t test: done
• add .gitignore: done
• add a test to check that pdldoc indexing works for the new dist
• make sure all the configuration options for BAD values are tried by Travis-CI (settings are in perldl.conf)

pdl split meta-issue

[devel-chm]

A key issue for modules that have been split out from the PDL
distribution is to make sure that the hooks needed to update the PDL
online docs database are correct. Otherwise the module will be
"invisible" to the pdldoc/help/apropos commands. What might make sense
is to split out PDL::Core and then check the other split out modules
using that rather that the bulk distribution (although it should work
there as well)

[mohawk2]

This might need a rethink of how the pdldoc stuff works.

[zmughal]

Very good points. We'll need to add a test to make sure that this always works no matter how we may build the pdldoc database in the future. Better to check breakage first in dev.

Perhaps we can add a standard hook for what PDL-Stats does with its add_doc.pl?

[devel-chm]

A standard hook sounds like the right direction. I'm with Ed that we might
want to rethink the pdldoc a little bit. The current add_doc.pl works but
seems a bit hackish. It would be nice to have something a little clearer,
simpler, maybe even automatic/transparent...

--Chris

[zmughal]

I was looking online for past discussion and saw that you commented that

It would be nice if the implementation could be
made more modular (e.g., you could compose the
docs from multiple database files somehow, undo
changes,...).

We can do that now! If we are doing a split, then now would be the perfect time to look into that.

[mohawk2]

I think that add_doc.pl is very similar to the code in PDL::Doc's "EXAMPLE". What this tells me is we just need an extra bit of API to encapsulate this. Shouldn't be hard. Thoughts?

[mohawk2]

Re @zmughal 's quote of a previous remark by @devel-chm , let's not get overcomplicated. I think adding docs that can then be found in the same way as now, i.e. preserving current functionality under the new scheme is enough. What do you guys think?

[devel-chm]

I think keeping it minimal---just enough to maintain the pdldoc status quo
while we divest the PDL distribution makes sense. However, it would be
nice if there were something a bit less magical than adding mysterious
lines by hand..

[zmughal]

Right, doing it the same way will get the release out the door faster without backcompat issues.

And if we do add a hook to PDL::Core, it will already know where the database file is so all it needs to know is the path to scan, correct?

[mohawk2]

I assume you mean PDL::Doc, not PDL::Core? It will work in the same way as currently, but hide the detail that is currently revealed/required.

[zmughal]

Yes, @mohawk2. See the issue I created here PDLPorters/pdla-core#2.

There are only 2 modules that use the scan interface. The rest use the already existing add_module function.

[mohawk2]

A suitably minimal (4-line) fix that makes PDL::IO::GD "just work" in pdldoc: PDLPorters/pdl#122 - though it will need a suitably up-to-date PDL once we release this.

[zmughal]

To replicate the process I've been using to check if this would work with a dep on just PDL::Core, run:

git clone -b pdl-core-only https://github.com/PDLPorters/pdl.git
cd pdl
perl Makefile.PL && make test && make install

cd ..

git clone https://github.com/PDLPorters/pdl-io-gd.git
cd pdl-io-gd
perl Makefile.PL && make test && make install

Just a note: PDL::IO::GD depends on PDL::IO::Misc as well as PDL::Core.

[mohawk2]

Wow, nice research. May I suggest a follow-up or edit of the above to be a full perlbrew snippet that those reading along at home can try out / see the results of?

[zmughal]

Feel free!