Directory info/beginlatex

This is the README file for the "Formatting Information" document
(formerly "Beginners' LaTeX"). It contains information about the
source code and arrangement of the files, for anyone who feels
inclined to hack on them. If you're not experienced with XML document
production, I suggest you don't try until you are :-)

This file is distributed with version 3.6 (March 2005)

The files are in three directories: a main directory with the PDF
version, and two subdirectories: one called "html" with all the HTML
files and images; and one called "src" with all the source code (XML,
XSLT, images, and assorted files used to create them).

The HTML comes as both as one big single file (beginlatex.html) and as
a chapter-by-chapter series (start at index.html). There are some
minor formatting bugs in the HTML version, especially in the index and
references, and I'd appreciate mail if you find errors, so I can fix
them.  

Not all browsers use the CSS style file correctly (notably Microsoft
Internet Explorer, which ignores some of the instructions and always
sizes fonts too large). If you are using MSIE, I strongly recommend
you throw it out and use Mozilla Firefox instead.

The PDF is formatted for printing at the same size as the LaTeX
Companion series (trim size 187mm wide by 235mm high. It should
therefore print OK on both A4 and Letter paper provided you make sure
your printer settings are for the paper you are using. If you use
Adobe's Acrobat Reader, do NOT click the "Fit to page" or "Enlarge to
fit" or "Shrink to fit" buttons before you print. The last explicitly
Letter-formatted copy was the version published in TUGboat (Nov 2003).

Images for the HTML version are now all PNG. The font samples were
extracted from a JPG page image generated from the PostScript output
of an old version, using the script "cutup", which cuts slices from
the JPG file according to carefully calculated pixel measurements,
using the PBM utilities, so if you do reformat the file with altered
margins, be warned that if you also want to fiddle with the font
samples, you will have to retain some dimensional consistency and
rewrite the cutup script. The JPG page images were generated using
GhostScript with the jpeggray setting, eg

   dvips -o p70.ps -p 70 -n 1 beginlatex
   gs -sDEVICE=jpeggray -r300 -sOutputFile=p70.jpg -q - <p70.ps

and then converted to PNG with jpegtopnm and pnmtopng. The font
samples need redoing, but that will have to wait for the next version.

Some of the screenshot illustrations need redoing now that Fedora Core
3 (soon 4) is stable and that Windows XP is becoming more common.
Recent changes to the source may mean it's no longer p.70 either :-)

There is a list of the LaTeX auxiliary, ancillary, and font files
needed in "auxfiles". This was generated from beginlatex-typebook.log
with the command:

   cat beginlatex-typebook.log | tr '\012(' '\040\012' | sed "s+).*$++" |\
      awk '{print $1}' | grep '/' | grep '\.' | sort | uniq |\
      sed "s+/usr/share/++" | awk -F/ '{print $NF}' |\
      sort -t. -k 2 -k 1 >>auxfiles

and then edited with comments. The files you need to get are probably
the .sty and .fd files for the font sample page, and these should
already be available on CTAN. A few of them are personal hacks and
they should be in the src directory. The font files specific to the
PDF are commercial fonts which I cannot distribute, so if you want to
regenerate the PDF yourself, you'll need to change the typeface
specifications in typebook.sty (read the comments).

Production processing of the whole document is done in the "src"
directory with the "run" script, which acts like a Makefile. It's
commented so you can see what happens. I am assuming you already know
XML and XSLT if you want to fiddle further with this: if you don't, I
suggest you leave it alone.

///Peter Flynn
   March 2005
   peter@silmaril.ie