On 10/17/2011 4:20 PM, Joel Berger wrote:
You might talk to chromatic about POD book creation, or look at his
repo for Modern Perl, which is written in POD with POD::Weaver at
https://github.com/chromatic/modern_perl_book
An interesting idea but I would prefer to see more
effort on content. The advantage of POD as a base
format is everyone is familiar and it has the advantage
of tying in directly with the PDL documentation tools.
But, I didn't really understand enough of what I read
in the POD::Weaver description to say whether or not
my impression is reasonable. (On the other hand,
if it is not easily apprehensible, that may be making
my point...)
Cheers,
Chris
On Mon, Oct 17, 2011 at 8:21 AM, Matthew Kenworthy
<[email protected]> wrote:
Hi Chris, Karl, and other PDL Book interested people:
On Fri, Sep 30, 2011 at 5:17 PM, Chris Marshall<[email protected]> wrote:
Hi Matt-
How are things going with the PDL book "project"
as far as status, plans, working files, or other
information? Would setting up a git folder at
sf.net help with coordination and contributions?
A git folder would be a good idea :)
Here were my thoughts on PDL Books and Tutorials -
In order to write and edit PDL documentation, it would be good to have
a simple format that everyone could edit easily and see it updated in
a timely fashion, but that it could be exported to something nicer as
a printable format in a PDF, such as the LaTeX output of the original
PDL Book.
To this end, I decided to try rewriting the PDL Book in POD.
I've found out that this works surprisingly well, because:
1) Writing in POD means that it is completely available and searchable
in the PDL help system
2) There's no maintaining a separate documentation repository (it
lives with PDL)
3) It can be cross-linked in with the PDL core documentation
To test this out, I converted the PDL Book Chapter 3, which is image
intensive chapters in the book, in order to see what the output would
be like in HTML and PDF.
The original POD documentation:
http://www.strw.leidenuniv.nl/~kenworthy/pdlpod/PDL.Tut.PGPLOT/PDL.Tut.PGPLOT.pod
Converted to HTML:
http://www.strw.leidenuniv.nl/~kenworthy/pdlpod/PDL.Tut.PGPLOT/PDL.Tut.PGPLOT.html
....and exported as PDF:
http://www.strw.leidenuniv.nl/~kenworthy/pdlpod/PDL.Tut.PGPLOT/test.pdf
So, what does this mean?
Ideally, it would be good to see a PDL Book, a set of PDL Tutorials
and a PDL Reference (mostly made up of the PDL function documentation)
which factor in the hard work done on the earlier separate texts, so
that we can all point new users to a given help page from within PDL.
The main work is doing the control code mangling, the conversion of
the images to PNG and checking that the new texts scan well. I can
take the lead on organisation, but I don't have that much time to do
conversions all by myself - if two or three people are willing to work
on converting a chapter at a time, we could pull something together
for a December/January release.
Okay, have a look at the PDF if nothing else, and let me know what you think.
Cheers,
Matt
_______________________________________________
Perldl mailing list
[email protected]
http://mailman.jach.hawaii.edu/mailman/listinfo/perldl
