[Live-demo] osgeo live documentation as a booklet/handout

[maning sambale]

Thanks Hamish and Cameron for the pointers.

I tried compiling using the make latex instead of the direct pdf via
rst2pdf.  The output is much better.  I had to create a separate
index.rst as the source of the toctree to do this.

Some concerns:

1.  It is not advisable to automatically generate the pdf by globbing:

.. toctree::
    :glob:

Since the output pdf won't have the logical order of pages.  I propose
we create a separate for rst for each language for the pdf generation.
 (Or an automated way to do this.)

2.  Running pdflatex, I get lots of errors for gif and png images like this:
 LaTeX Error: Unknown graphics extension: .gif.

See the LaTeX manual or LaTeX Companion for explanation.
Type  H <return>  for immediate help.
 ...

l.632 \includegraphics{usb_penlinux_licence2.gif}

3.  The project and osgeo logo are always on the last page of the
preceding project page.  Unlike in the html where it is on the
upper-right corner.



On Tue, Dec 6, 2011 at 3:30 AM, Cameron Shorter
<cameron.shorter at gmail.com> wrote:
> On 5/12/2011 8:27 PM, Hamish wrote:
>>
>> maning wrote:
>>>
>>> Excellent! I tried creating a pdf
>>> using rst2pdf.  This is the process:
>>>
>>> # get rst docs from svn
>>> svn co https://svn.osgeo.org/osgeo/livedvd/gisvm/trunk/doc/
>>
>> try also:
>>
>> $ cd doc/
>> $ make help
>> Please use `make<target>' where<target>  is one of
>>   html      to make standalone HTML files
>>   dirhtml   to make HTML files named index.html in directories
>>   pickle    to make pickle files
>>   json      to make JSON files
>>   htmlhelp  to make HTML files and a HTML help project
>>   qthelp    to make HTML files and a qthelp project
>>   latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter
>>   changes   to make an overview of all changed/added/deprecated items
>>   linkcheck to check all external links for integrity
>>   doctest   to run all doctests embedded in the documentation (if enabled)
>>
>>
>> $ make latex
>> ...
>> reading sources... [ 16%] de/quickstart/ushahidi_quickstart
>> reading sources... [ 16%] de/quickstart/virtualbox_quickstart
>> reading sources... [ 17%] de/quickstart/zoo-project_quickstart
>> reading sources... [ 17%] de/sponsors
>>
>> reST markup error:
>> .../trunk/doc/de/sponsors.rst:33: (SEVERE/4) Problems with "include"
>> directive path:
>> IOError: [Errno 2] No such file or directory: 'contributors.rst'.
>> make: *** [latex] Error 1
>>
>> (so I get the similar problems as you)
>>
>> # if that had worked you could then do LaTeX to dvi/postscript/pdf,
>> # with any of the classic tools.
>> $ pdflatex ...
>>
>
> Maning, I think that your efforts to make a PDF book will be an excellent
> addition.
> Hamish is on the right track with his advice.
>
> What I suggest is that we update our Makefile in order to supporting making
> PDF documents. Eventually, we should be able to type "make pdf", and pdf
> documentation will be created.
>
> Are you familiar with to format of Makefiles? If not, it might be worth
> doing a quick refresher, then having a look at the "make html" directive,
> which we have been keeping up to date. (Look in the Makefile [1] for the
> "html: ...." directive).
>
> We will need to update the "make latex" to have a similar set of
> dependencies to the "make html".
> This will fix some of the errors you have been seeing.
> Ie, update the latex directive to something like:
>
> latex: sphinxbuild fix_header_links banner_links win_installer_links
> test_page css link_to_en_docs link_to_en_docs
>
> [1] https://svn.osgeo.org/osgeo/livedvd/gisvm/trunk/doc/Makefile
>
>
>
> --
> Cameron Shorter
> Geospatial Solutions Manager
> Tel: +61 (0)2 8570 5050
> Mob: +61 (0)419 142 254
>
> Think Globally, Fix Locally
> Geospatial Solutions enhanced with Open Standards and Open Source
> http://www.lisasoft.com
>



-- 
cheers,
maning
------------------------------------------------------
"Freedom is still the most radical idea of all" -N.Branden
wiki: http://esambale.wikispaces.com/
blog: http://epsg4253.wordpress.com/
------------------------------------------------------