Linux Brochure Project: Documentation

Linux Brochure Project

Documentation

Access to LBP

To access the required files needed to build the brochure our users can either use a file release or else use our Subversion repository. As usual, our SVN version is more volatile than file releases and may not work from time to time, but it does give access to the version that is being actively worked on by the development team.

Building LBP

Make sure the required packages (see next section) are installed on your Linux system. svn checkout lbproject (or else unpack the tarball), cd to the created directory, type, e.g.,

make NAME=generic COUNTRYCODE=en

make NAME=vlug COUNTRYCODE=ca

and a customized Linux brochure should be produced both in PostScript ($(NAME)_$(COUNTRYCODE)_linux_brochure_watermarked.ps.gz) and PDF ($(NAME)_$(COUNTRYCODE)_linux_brochure_watermarked_landscape.pdf) forms. By default these results will print nicely on letter-size paper, but if you use A4 paper you should add the option PAPERTYPE=a4 to the above 'make' commands. If you want to produce a non-English brochure, then you should add the option LANGUAGECODE to the above commands. For example, to generate an Italian-language brochure using a4 paper type

make NAME=generic COUNTRYCODE=it LANGUAGECODE=it PAPERTYPE=a4

Other brochure-building possibilities are contained in the all_brochures.sh script which builds all valid combinations of brochures.

By default all the above make commands use the "all" target, and the resulting PostScript or PDF files should be straightforward to print on Linux systems using the CUPS option "-o sides=two-sided-short-edge". However, some Linux duplex printers have broken configuration where the "-o sides=two-sided-short-edge" option gives the same two-sided results as "-o sides=two-sided-long-edge" with the second-side of the brochure sheet printed up-side-down relative to the first side of the brochure sheet. To compensate temporarily for this error until the era when most Linux duplex printers honor the "-o sides=two-sided-short-edge" option, we provide two additional targets called non_working_short_edge.ps.gz and non_working_short_edge.pdf which rotate the second page by 180 deg. To build these targets simply append them to a valid make command, e.g.,

make NAME=generic COUNTRYCODE=en non_working_short_edge.ps.gz

Note, you may also edit linux_brochure.tex and its translations (such as linux_brochure_it.tex) and add/modify appropriate files in the subdirectory lugs (see the NAME and COUNTRYCODE variables in the Makefile whose values can be modified during make invocation as above) to change any of the wording in the brochure, but if you distribute that result also remember to honor the GPL by distributing all files used to generate your brochure!

Software Requirements

Executive summary: to build the brochure in both PostScript and PDF forms, you need teTeX, skencil (previously known as sketch), ps2eps (the particular package identified below since apparently there are a number of different packages named ps2eps), pstops, and ps2pdf installed on your system. Also, you need to install ImageMagick (to build the thumbnail image and screenshot of the completed brochure) and pdftohtml (to generate the html version of the brochure).

Here are the details of the individual requirements with comments on their use in building the brochure.

LaTeX from the teTeX distribution of TeX-related software. This is the fundamental software used for the brochure production.
The graphicx and rotating packages distributed as part of teTeX. These packages are for magnifying, rotating, and clipping icons and watermarks. These packages also are used to rearrange and overlay whole pages while retaining the results in vector form (for good looks) as well as retaining font and and character information to allow anti-aliasing as well as text searching in the final PDF form of the brochure.
Leaflet style files which are modifications of the article style for leaflet-sized pages. We specifically acknowledge the efforts of Juergen Schlegelmilch in creating the LaTeX leaflet style file in 1998. Its availability inspired us to evaluate LaTeX for generating our brochure with quite happy results. We have downloaded leaflet.dtx (which is not part of teTeX although it should be!) from CTAN and built leaflet.cls from it. We then modified this file to have the fold marks in a more convenient place for our needs both for letter- and A4-sized paper. We redistribute the resulting leaflet_letter.cls and leaflet_a4.cls as part of the LBP software under the LaTeX Project Public License (the one exception to the GPL license for our work).
The skencil (previously known as sketch) package (and especially the accompanying python script called sk2ps for converting skencil-generated files to encapsulated PostScript form.) skencil is a vector drawing programme for Linux/Unix which is extremely easy to use (even for non-artists like the developers of LBP), and its vector artwork results look good at any scale. We use skencil exclusively for the LBP artwork.
ps2eps written by Roland Bless. (See here for details including information on Debian and RPM Linux packages for ps2eps.) We found that this Perl script (and associated small C code for calculating the boundary box) did a wonderful job transforming our quite complicated one-paged PostScript files into eps form. (Results were more reliable than for the ImageMagick convert routine. Also, the ps2epsi script that is widely distributed as part of the gs-common package completely bombed when faced with some of our PostScript files.) Apparently there are other packages named ps2eps so be sure and get and install this particular one. (Installation consists of simply putting the ps2eps Perl script and associated compiled bbox executable in your path.)
pstops (part of the widely distributed ps-utils package). We use this executable to rearrange our 6 leaflet-sized PostScript pages into two letter- or A4-sized PostScript pages and also to watermark that result.
ps2pdf (part of the widely distributed gs-common package). We use this executable to convert our final PostScript result into PDF format.
convert and montage (part of the ImageMagick suite of image manipulation programmes). We use these executables to form a montage of the two sides of the brochure in thumbnail image and medium-resolution screenshot forms.
pdf2html. We use this widely distributed executable to generate the html version of the brochure. Note, pdf2html has some problems with exact geometrical layout, but the result is good enough for BabelFish translation which is the principal motivation for making the brochure available in html form.

Webmaster for LBP

Hosted by