[drupal-docs] generating Drupal Handbook pdf's manually

[Ron Mahon]

Could not access the pdf file ?
Ron 


InterNet Marketing Resource Center
A Free Super Mart of Articles, Demos, Tutorials everything you need to
Succeed on the net.
www.inmrc.com 


-----Original Message-----
From: Djun Kim [mailto:puregin at puregin.org] 
Sent: Wednesday, April 20, 2005 7:52 PM
To: drupal-docs at drupal.org
Subject: Re: [drupal-docs] generating Drupal Handbook pdf's manually

Quoting Moshe Weitzman <weitzman at tejasa.com>:

> bryan on the web wrote:
>> It seems to me that is might make more sense in the long run to build 
>> Server-Side PDF generation into the book module using PHP.
>> There is a costly PDF library for PHP called PDFlib
>

I have set up a script which will automatically generate PDF from the HTML
'printer friendly' version. The preliminary results may be found here

      http://www.puregin.org/files/Drupal_handbooks.pdf

A good deal more tweaking is possible (and required, I think).  The point is
that this is generated entirely automatically, so we could run the job from
cron once per day, (more frequently if the rate of change of documentation
picks up)

  All of this is done using freely available open-source tools (wget, perl,
html2ps, ps2pdf, ImageMagick).  I'm happy to contribute scripts,
configuration files and installation help if someone wants to set this up on
the documentation site.

> IMO, the fundamental issues here are not about generating the .pdf. 
> They are around empowering a group of authors to contribute content 
> which is later transformed into a *pretty* book. Pretty implies 
> consistency, graphics, sidebars, footnotes, etc.

   I strongly agree.

   Transforming great content into a beautiful book is non-trivial.
Typesetting and print production are difficult and delicate arts, at their
best when readability figures first among aesthetic factors.  Long before
one gets to that point, however, much can be done to make a better book.

   That having been said, I'm strongly in favour of 'good enough is better
than nothing at all'.  Having a printable copy will help with the task of
editing. The process of getting something that looks good on paper will
require debate and decision-making which will lead to a better document.

   Moshe mentions consistency, and I agree that this is something we should
try to improve at the level of form and content.  A style guide would be
useful here, as well as some high-level editorial policy decisions.

   An example of a useful style rule would be 'no use of heading tags in
handbook pages (e.g., no <H1>, <H2>, etc.)'

   An example of a useful policy decision would be splitting the handbook
into
several documents, targeted at different groups of users.   It would also be
useful to have this document be versioned, and track Drupal Core releases.
This would let us archive sections such as 'how to convert from Drupal 2.0
to Drupal 3.0' and hopefully never look at them again :)

>
> Charlie contributed a process which takes a bit of work, and produces 
> decent results (I suppose - I haven't actually seen the output). How 
> can we do better?

   The automatic generation of PDF would be greatly helped by 
consistency in the
authored HTML.  Structural tags such as H1's should not be gratuitously 
embedded
in sections.   There's a certain amount of noise - dubious HTML,
inconsistent
treatment of characters and entities, source formatting, line-end
conventions,
which it would be nice to clean up from time to time.

   Could we build a process for documentation which follows a software
release
model?  People contribute, contributions are discussed, filtered, moderated,
and applied to the documentation; at a release point, there is a 'freeze',
existing problems get fixed, and the HTML gets converted (mostly 
automatically,
but with experienced human interaction where required) into a 'publication'
format such as TeX, DocBook, MIF....  An 'official' print document is 
released,
in PDF, and the publication format is used to automatically generate 
HTML which
gets imported into a Drupal Book for the next round of community editing.



-- 
puregin at puregin.org
http://www.puregin.org