Skip to content

Latest commit

 

History

History
137 lines (82 loc) · 4.33 KB

Overview.pod

File metadata and controls

137 lines (82 loc) · 4.33 KB

Writing Documentation for PDL

The goal is to refactor and expand the older PDL books and their sections into the structure below, and to do it all in the Plain Old Documentation (POD) format. These are text files ending with the extension .pod and are written with a simple formatting similar to HTML. POD can be nicely formatted, but I'm aiming for good, accurate content and we can worry about prettifying it later.

You can read how to write POD with:

perldoc perlpod

When writing the Book/Tutorials/documentation, you should be regularly checking the pod file with the podchecker program, and optionally displaying the HTML output to see how simple formatting should look like.

podchecker "PDL::Docs::Overview.pod"

and if all goes well, it will say: PDL::Docs::Overview.pod pod syntax OK. Otherwise, note the problems and clean them up.

Convert to HTML with this line:

pod2html -noindex "PDL::Docs::Overview.pod" > tmp.html

...and then open tmp.html with your browser to see what it looks like.

Including Figures

POD does not have a capability to display figures, but HTML and PDF output does. For the figure, here's the one line summary:

Make an 8-bit color PNG with width 800 pixels and add this line in the POD:

=for html <p><img width="400" alt="" src="path_to_image/image.png"/></p>

(Insert 3 blank lines after any =for html call so that HTML rendering looks and works better.)

Longer explanation:

Images for HTML and PDF generation should come from the single PNG image with 8 bit color and a width of 800 pixels. The PNG should be 8 bit-color as reported by running the file image.png command in unix. The height can be unconstrained.

Only the HTML code should be added in a POD document - I have a script that will automatically add the correct pod formatting code for a PDF image afterwards. This is done because podchecker complains about the pod formatting code for the PDF image.

The <p></p>, alt="", and width="400" (cf WIDTH=400) elements make the html output valid XHTML.

Book

A book should give an introduction to PDL, running through the basic fratures with enough detail so that the user can do basic operations, learn some simple broadcasting, and output their results to files or plots.

Where to find help
PDL::Book::NDArray What is a PDL object?
PDL::Book::Creating Basic Operations to make PDLs
PDL::Book::NiceSlice Cutting out bits of a PDL
PDL::Book::Functions Writing your own functions for PDL
PDL::Book::Broadcasting Broadcasting and Getting rid of FOR loops
PDL::Book::PGPLOT Graphics with PGPLOT done
PDL::Book::PLplot Graphics with PLplot
PDL::Book::Transform Rotating, Scaling and Translating with PDL::Transform
PDL::Book::Complex Complex Numbers
PDL::Book::Pthreads Parallel Computations with pthreads
PDL::Book::PP Getting C routines into PDL with PDL::PP

Tutorials

Detailed explanations with examples that go into detail about some function, idea or methodology of PDL.

Demonstrating broadcasting with the Game of Life
Making your PGPLOT output look pretty
Getting to grips with PDL::Transform

Reference

The PDL modules and their functions - this is built from the POD conversion scripts that comb the PDL modules. This should be an alphabetized list of all the calleable functions in a given PDL installation.

FAQ

Commonly asked questions from the PDL Mailing list that address repeated topics.

PDF OUTPUT

Conversion for PDF reading is done using:

http://perl.jonallen.info/projects/pod2pdf

pod2pdf PDL.Tut.PGPLOT.pod --icon-scale 0.25 --title "PDL Book" --icon logo2.png --output-file test.pdf

Images are included for the PDF with O < tags followed by the pathname.

Images are left-aligned, and a width of 400 pixels is just over half the width of the PDF page.