I also very much agree with the idea of reorganizing the docs. As for POD or reStructuredText or other format, I would say rst is really better than pod. It's very succuessful even outside the Python community. If the PDL dev team is fine with a non-pod solution then as an, well, now observer maybe, I would recommend rst. On the other hand, if you finally decide to stay with pod, it's best to communicate with MetaCPAN dev or maybe even Perl core dev for supporting new directives, maybe a new "=for math" for latex expressions (you may need to see how reStructuredText designs and implements it), and for pictures although MetaCPAN can do it now but I want a feature that allows me to easily use a picture that is within my package rather than stored at an external website like github. Besides you know there is Pod::Weaver and you probably can see how it can be ultilized.
And I have one more thing: If you look at numpy doc, mostly every method has examples, examples that you can simply copy and paste and run. For PDL there're much less examples of that level of quality... Regards, Stephan On Tue, Jun 11, 2019 at 11:10 PM Ed . <[email protected]> wrote: > I think that moving away from POD is incompatible with sticking with > metacpan.org. I would instead advocate: > > * reorganise docs as you've rightly said > * stick with POD - I would also advocate using Inline::Pdlpp as I have > with > PDLA::IO::HDF::* - > > https://metacpan.org/source/ETJ/PDLA-IO-HDF-2.019102/lib/PDLA/IO/HDF/VS.pm#L491 > * drop pdl.perl.org (or even better have it redirect to metacpan.org/PDL) > * tables aren't awful as they are now, but an alternative model is visible > at > > https://metacpan.org/pod/DBIx::Class::DeploymentHandler#WHY-IS-THIS-SO-WEIRD > - the diagram is generated using "ditaa" > * I have no opinion on mathematical notation! > > -----Original Message----- > From: Diab Jerius > Sent: Tuesday, June 11, 2019 3:53 PM > To: [email protected] ; [email protected] > Subject: [Pdl-devel] RFC: Improving documentation > > I recognize how hard documentation is to write, and I'm grateful that > PDL has so much of it. However, there is room for improvement. The > following comments are intended as an objective critique and to start > a discussion which can lead to cohesive design and documentation > standards. > > The current documentation is a combination of user guide, history > lesson, notes to self and reference manual. There are a few things we > can learn from other successful projects that would improve it. > > 1. Separate out the different approaches into different document > hierarchies. (Type::Tiny[1] and the Template Toolkt[2] have done > that pretty well) > > I think the documentation falls naturally into these categories: > > a. Reference manual: terse, complete documentation accompanying > every method and subroutine. The documentation should reflect which > version of PDL a method was added or when its behavior changed. > Documentation should reflect the current behavior, not changes from > previous behavior. That adds confusion and never gets removed even > when the change happened years prior. Knowing when behavior changed > allows the user to find the older docs and compare. > > b. User's Guide. This would be topic focused and live in the > PDL::Manual hierarchy > > c. Tutorials: These would include beginning to end discussions of > how to do a more complex analysis and would live in the PDL::Tutorial > hierarchy > > d.. Cookbooks: How to solve specific problems using PDL wizardry > that might not be obvious. These would live in the PDL::Cookbook > heirarchy. > > > 2. Have a single source for the documentation. > > Currently there's pdl.perl.org and metacpan. That's one too many. > For ease of maintenance we should choose metacpan and sunset the > documentation on pdl.perl.org. We don't have the resources to handle > both. > > 3. Math, table, and graphics support > > This is a difficult area, as POD is a very primitive format. I'm > not sure how far we can push things. There are ways of marking > sections to provide different input to different renderers, but that > makes it difficult for documentation authors. We will need tools to > generate POD which contains output for those without the special > renderers. We would also need to work with Metacpan to see if they > are open to rendering math and tables using optional renderers. > > For mathematical notation, we would need to standardize on a single > format. One option is to write it in asciimath[4] (I personally can't > read LaTex math very well, even though I've used it for eons. I use > LyX to write anything with an equation in it.). > > If we need to ditch POD and move to another format, than Sphinx[5] > (used by readthedocs[3]) produces very nice technical docs. (GSL has > moved to it and it has really improved their documentation[6].) That > would require generation of HTML for the static documentation on > metacpan and I don't know how well that would work. > > The nuclear option would be to move the documentation to > readthedocs[3] or some other similar site. To be clear, this is not > at all what I'd like to see happen, but it would provide us with nice > docs out of the box. > > > [1] https://metacpan.org/release/Type-Tiny > [2] https://metacpan.org/pod/Template > [3] https://readthedocs.org/ > [4] http://asciimath.org/ > [5] http://www.sphinx-doc.org/en/master/ > [6] https://www.gnu.org/software/gsl/doc/html/index.html > > > _______________________________________________ > pdl-devel mailing list > [email protected] > https://lists.sourceforge.net/lists/listinfo/pdl-devel > > > > _______________________________________________ > pdl-general mailing list > [email protected] > https://lists.sourceforge.net/lists/listinfo/pdl-general >
_______________________________________________ pdl-general mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/pdl-general
