The PDL Book

This POD shows how to get a local copy of the PDL Book, and what programs you need to use to compile HTML and PDF versions of the book.

Using git to access the PDL Book

The Book source is in POD format and can be read online in the git repository at:

https://github.com/PDLPorters/pdl-book/blob/master/README.pod

To get a local copy on your computer, use:

git clone git@github.com:PDLPorters/pdl-book.git

Making a PDF from the POD - Installing pod2pdf

The repository does not automatically generate a PDF version of the Book from the POD files in it, so if you do see a book.pdf file in there, it's almost certainly not built on the latest PODs.

To make a PDF version of the book, you need to install the Perl modules Image::Size, File::Type and finally pod2pdf. I use the CPAN shell:

sudo cpan
install Image::Size
install File::Type
install App:pod2pdf

All images are included in the PODs as HTML tags. A small script can convert these tags into PDF tags suitable for pod2pdf.

If you want to make the PDF version of the book, you can then run:

./make_chapters.pl
./make_endpieces.pl

This produces the files FrontPage.pdf, toc.pdf, and Chapter??.pdf files. These can be read individually or combined with pdfjam or any software that can join individual PDF files together.

pdfjam -o book_complete.pdf FrontPage.pdf toc.pdf Chapter??.pdf

Adding new material and getting write access to the PDL Book

You need to have a GitHub account, and be authorised by one of the PDL gurus to have access to this repository. When you have both of these things, clone this URL:

git clone git@github.com:PDLPorters/pdl-book.git

When you've downloaded it, do:

cd pdl-book
<edit files and make modifications>
git add <file>

Check with:

git status
git commit . # this stages your file and readies it for the push
git status # check one more time....
git push # send it off to the master origin repo

To update your local repository and working copy to the latest revision committed to the remote repository, you need to execute git pull. This pulls all of the changesets down from the remote repository and merges them with your current changes (if there are any).

To delete a file from the repository (careful there, Ted) you do a:

git rm --cached <file>
git commit <file>
git push

You can wait on the git push for other changes in your current session.

Read Overview to see notes on style and how to generate figures for the PDL Book.