

	Lua 4 Quick Reference Guide README
	Kein-Hong Man <mkh@pl.jaring.my>


-----------------------------------------------------------------------
Home: http://www.geocities.com/keinhong/luaquickref/


1. Introduction
2. Design notes
3. How to print from OpenOffice.org
4. How to produce a PDF booklet for printing
5. How to make changes to the document in OpenOffice.org
6. Problems with the Lua 4 manual
7. Future plans


1. Introduction
-----------------------------------------------------------------------

This is a reworking of the Lua 4 manual that is found in the Lua 4
distribution into a thin and concise booklet (the 'quick reference')
format. I made this because I use Johan Vromans' Perl booklet quite
often when I am programming. Very useful for people who know the
language but do not want to crowd their brains with the details.

Since much of the material is from the manual, I have elected to
release this material under the same copyright. Please see the file
COPYRIGHT for the copyright information.

When printing the PDF booklet, take note of the arrangement of the
pages first, then figure out the steps to be taken before actually
doing any printing. For instance, I print all odd pages first, then
reinsert them and print all even pages. After printing and binding,
you can opt to trim the booklet to 4.5" wide, in order to follow the
Perl booklet width, to get the full effect.

Automatic duplex printing may not work properly on some printers.
This might be due to the incorrect binding information set in the
PDF file. It is possible that the settings for binding information is
not supported by either OpenOffice.org or Ghostscript.

The generated PDF uses TrueType fonts embedded as Adobe Type 42
(embedded TrueType) fonts. Any Adobe Acrobat Reader at version 4 or
later should be able to read the PDF file.

Bug reports are welcome; please send it to <mkh@pl.jaring.my>. I am
also in the Lua mailing list, but I will be slow in responding as I
am bandwidth-challenged. Thus I am not able to maintain the document
using online CVS, though I plan to use SVN privately for versioning.
I will try to get any fixes done ASAP.

If you are interested in commercializing this material, please drop
me a line first. I would like to defer to the wishes of the creators
of Lua in the matter of material published on paper. In other words,
if there is an agreed master plan on the publishing of Lua treeware,
then I will be happy to follow it. There isn't one yet, though, AFAIK.

If you feel rich enough to pay me for my efforts, feel free to send
me an Amazon Gift Certificate (the minimum value is just USD5.) That
way, it is likely that your gift will be used in a constructive
fashion, instead of on drink, drugs or women. :-) :-) (Of course,
that last part was just in jest. ;-) )


2. Design notes
-----------------------------------------------------------------------

- The basic styles were copied/adapted from the Perl Quick Reference
  Guide by Johan Vromans, whose Perl booklet is available online. Note
  that the style might not please everyone, especially on its use of
  sans serif fonts where some might prefer a Courier font.

- The page size is A4 (8.27" x 11.69") for the original document, but
  when shrunk into a booklet, there is ample margin to fit the output
  on a Letter page. Anyway, the Adobe PDF Reader can print using
  'fit to page' so sizing should not be a problem.

- I wanted to use the 'universal' size (8.27" x 11.00") but upon
  shrinking to booklet, the top and bottom margins become too large,
  due to the extra 0.69".

- The design tries to allow for some whitespace so that changes or
  modifications to the document are easily made.

- Margin was added for safety where possible as WYSIWYG formatting
  sometimes changes depending on printer settings (esp. on Win32) or
  font availability.

- The file extension TGZ (tar.gz) is used instead of SXW in order for
  SVN to work more efficiently when making incremental diffs.
  OpenOffice.org still manages to open and save normally. This has not
  been tested all platforms, so YMMV.

- The TGZ extension also allows the file to be placed on Web sites
  that allow only certain types of files to be uploaded.

- The Lua logo has been set to the proper logo (added as an EPS object),
  courtesy of the creators. Thanks Luiz.

- The suite of document and text styles is a bit of a mess. There is
  no guarantee that the styles for source code, keywords, definitions,
  etc. are enforced (or set) properly.

- I used UK spelling for some words, e.g. "behaviour".

- The document may be converted to TeX or DocBook in the future.
  OpenOffice.org already uses XML in a tar-gzipped document bundle,
  so it is really sort of a marked-up document.


3. How to print from OpenOffice.org
-----------------------------------------------------------------------

- The easiest method is really to print the PDF booklet, but you might
  want to roll your own custom version. So here are my notes on
  printing the guide from OpenOffice.org.

- When printing from OpenOffice.org, please check the formatting
  before committing the file to the printer. Different setups on
  different machines can cause small differences in formatting.
  This may be due to fonts and font substitution.

- Here are the steps for OpenOffice.org printing (Win32):
  1. Select File->Print.
  2. Select Options->Brochure in the Print dialog box for printing
     as a booklet, otherwise each page will fit one physical piece
     of paper.
     (NOTE this option resets itself after it is used, so it must
      be set every time you want to print it in brochure format.)
  3. Select your printer driver settings, choose A4 or Letter paper
     and set LANDSCAPE mode there when printing a booklet.
  4. Select to print even pages first, then odd (or vice versa.)
     (NOTE please determine the print order carefully; perhaps
      you will need to perform some simple test printouts.)

- It is also possible to print using the normal (A4/Letter) size,
  then use the printer driver's settings to shrink the output.
  From experience, this is rather more messy, not to mention very
  driver-dependent.


4. How to produce a PDF booklet for printing
-----------------------------------------------------------------------

- It is a good idea to produce a PDF booklet if you wish to
  distribute your own customized version of the guide. This is
  because the formatting changes a bit from machine to machine.

- A PDF file ensures that you will get what you see, since PDF
  documents are fixed and are quite uniform.

- I used the following software to produce the PDF files:
  1. OpenOffice.org 1.0 Writer on Win32 (http://openoffice.org/)
  2. AFPL Ghostscript & Ghostview (gs704w32.exe & gsv43w32.exe)
  3. redmon (redirection monitor) (redmon17.exe) (possibly optional)
  4. AdobePS 4.2 Printer Driver (aps426eng.exe)

- In Adobe driver:
  1. Select driver, then open properties dialog box
  2. Select : Paper->Unprintable area, set print margins to the
     minimum if you are printing it as a booklet, or set reasonable
     margins if you are printing it as a normal-sized document.
  3. For best results, let the driver embed the original fonts as
     Type 42 fonts (select the option to embed TrueType fonts.)

- In OpenOffice.org:
  1. Select : Print->Options->Brochure
  2. Adobe driver : set page size (A4 or Letter)
  3. Adobe driver : set landscape mode (brochure printing)
  4. Select : Print->Print to file (set filename)
  5. Print all pages (total pages should be a multiple of 4)

- In Ghostview:
  1. Select appropriate page size, orientation.
  2. Use convert with pdfwrite driver to write PDF file.


5. How to make changes to the document in OpenOffice.org
-----------------------------------------------------------------------

- Many style schemes are used; open the Stylist (F11) and make
  changes to the style. The changes should be reflected in the
  document immediately.

- Formatting differs a bit from machine to machine, so sometimes
  portions will be thrown out of kilter. When this happens to
  vertical spacing, the results can be a real pain.

- If you have the normal Win32 fonts (Arial, Times New Roman, Courier
  New are also available for Linux, please see info on FreeType on the
  Internet) then formatting (paragraphs, pagination) should not change.
  But no guarantees, though, YMMV.

- A colour version is quite easy to make, but B&W is still better
  because crisp smudge-free black-only laser printing is one of the
  best choices for printing this booklet. Besides, colour ink-jet
  printing is still rather slow, and colour laser is still expensive.


6. Problems with the Lua 4 manual
-----------------------------------------------------------------------

- Where I detected ambiguity, I have checked the sources (following the
  UTSL philosophy). Here are modifications I have made that changes the
  meaning of the wording of the manual:

  a) In Patterns, Character Classes, the literal character x to be
     matched is not one of the magic (special) characters.

  b) In the description for the I/O function seek, the "plus a base"
     is a little ambiguous.

  c) In the description for the I/O function writeto, the pipe is
     really an output pipe.


7. Future plans
-----------------------------------------------------------------------

- Some unused styles still appear to be present. A cleanup is planned.

- It is possible to write a script in OpenOffice.org to make format
  changes automatically; that might be a feature for the future.
  Massaging the XML could also be done. For example, we can switch
  automatically between a colour version and a B&W version.

- Better markup with more style schemes is planned. This allows font
  changes to be made quickly and correctly to the right parts of the
  document.

- If formatting problems bothers me too much, I will switch to TeX or
  DocBook in the future. I know TeX, and I am looking at potential
  DocBook tools that can tightly control formatting. I am also looking
  at Lout and straight PostScript.

- Ease of customization by the typical user is a goal of this booklet.
  Therefore, any changes would be carefully considered so that there
  is no unnecessary barriers against editing of the sources.

- I am looking at a probable switch to Basser Lout, because:
  (a) Lout's installation and use is much easier than TeX
  (b) the source file can be heavily marked-up and easy to process
  (c) a couple of PS processing scripts solves all formatting issues
  (d) one can get a colour version done easily as well


-----------------------------------------------------------------------
Kein-Hong Man
mkh@pl.jaring.my
2003-03-29
Kuala Lumpur, Malaysia

