[Plplot-devel] A second rewrite of the Fortran chapter of the DocBook documentation

[Alan W. I. <ir...@be...>]

Hi Arjen:

As discussed off list I fundamentally liked your rewrite of the Fortran
chapter and just wanted to change a few things about it.  But that
effort grew and grew with the result that I have rewritten the whole
thing (as of commit e50b011) inspired by the documentation ideas
that you used in your first rewrite.
It's now 4 pages rather than 3 and
mostly stays focussed on the idea of what a PLplot developer 20 years
from now will need to know about the implementation of our Fortran
binding so he can quickly understand it.  I essentially use all
details of our binding for plstring throughout as an illustrative
example and to keep the discussion focussed.  Although there are
interfacing details in this chapter that an ordinary Fortran user will
want to skim or even skip, there is also useful information in this
chapter for that level of user as well.

I would appreciate you giving this rewritten chapter a critical read,
and if there are some further things you would like to make please go
ahead and do that and commit those changes.  Although I hope and trust
another complete rewrite will not be necessary. :-)

Normally as a Cygwin user you should be able to easily build the
DocBook documentation following the Cygwin instructions Phil inserted
into doc/docbook/README.developers.  But since you haven't tried that
procedure yet, I have attached fortran_chapter.pdf as a convenient way
for you to look at my rewrite of the Fortran chapter.  That file was produced
by the command

make -j4 print && \
pdftk doc/docbook/src/plplot-5.11.1.pdf cat 78-81 output fortran_chapter.pdf

where raw pages 78-81 correspond to the Fortran chapter part of the
doc/docbook/src/plplot-5.11.1.pdf file produced by that make command.
I have never used pdftk before, but it looks like it is an extremely
useful Linux command-line tool (unfortunately for you apparently not
yet packaged for Cygwin) for manipulating PDF files.

By the way, I think I have figured out a way to beat the
disambiguation issue with plstransform and plslabelfunc that I 
documented in the above PDF.  The idea is to have two optional
callbacks in the argument list (one being the single-precision one,
and the other being the double-precision one) with only one or the
other allowed for a given call.  But fingers crossed, and we will see
whether that wild idea actually works later today after I get
some sleep.

Alan
__________________________
Alan W. Irwin

Astronomical research affiliation with Department of Physics and Astronomy,
University of Victoria (astrowww.phys.uvic.ca).

Programming affiliations with the FreeEOS equation-of-state
implementation for stellar interiors (freeeos.sf.net); the Time
Ephemerides project (timeephem.sf.net); PLplot scientific plotting
software package (plplot.sf.net); the libLASi project
(unifont.org/lasi); the Loads of Linux Links project (loll.sf.net);
and the Linux Brochure Project (lbproject.sf.net).
__________________________

Linux-powered Science
__________________________