recent experiences with Lout

[Greg A. Woods]

My quest to do all of our business documents with Lout continues.  Along
my way I've encountered some things that seemed like enormous
road-blocks in my thinking, and only through trial and error have I been
able to achieve the desired results.  I thought I might share some of
these things, and perhaps others might benefit from what I've learned,
or perhaps someone might be able to give me some further pointers that
would help me out in the future.

I should mention that prior to discovering Lout, and during the time
between when I first learned of Lout, and essentially the beginning of
this year, I've been a troff ``expert'' (IMHO, anyway).  I've managed to
make the MM macros jump through high hoops that its authors may never
have imagined, and writing tbl came naturally to me at one time.

In any case I'm sufficiently enamoured with Lout (and dismayed with the
difficulties of troff, and the fact that groff is a big ugly C++
program) that I've decided to make Lout my new standard for documents.

Initially Lout provided most everything I needed, which was to say I was
using it with good success to write trivial letters and reports.

However many of the more advanced tricks I've done in the past with
troff, I would like to repeat now with Lout.  Some of these things have
alreay been much easier with Lout, such as page backgrounds, and others
have been extremely frustrating to get right.

One thing I have yet to learn is how I might centre a group of objects
(paragraphs, displays, and the like), vertically on a page.  My first
desire to do this has been with a simple business letter that looks
terrible if it's scrunched up against the top of the page.

I started my journey into the more complex aspects of Lout by trying to
learn the low-level placement operators in order to create a simple page
footer:

def @FooterString {
        0.5f @Font {
                Printed @Moment&&now @Open {
                        @Month"/"@Day"/"@Century | @Year | "-" |
                        @Hour:@Minute:@Second
                }
        } |
        |0.5rt @OneCol 0.8f @Font {
                @CompanyFullName
        } |
        |1rt 0.5f @Font {
                @DocumentIdString
        } |
        //0.2f |0.5rt 0.8f @Font {
                @PlanixAddressFooter
        }
}

which I then specify as the object for the @*Foot parameters in the
document's @Use invocation.

Getting something that looked like our old letterhead seemed fairly
straight forward until I learned that I couldn't use @Underline in a
page header, and further learned that even @HLine wouldn't work, and
resorted to raw PostScript for an @Graphic call:

import @DocumentLayout
def @CompanyLogo {
        @HScale {
                4.0f @Font {
                        P L A N I X
                } |
                #
                # we can't use @HLine in here, as this is used in
                # the @StartTop in place of pre-printed letterhead
                #
                /0.5f {
                        "0 0 moveto xsize 0 lineto stroke" @Graphic { }
                } |
                //0.5f |0.5rt 0.75f @Font {
                        @UNIX -- Internet -- Security -- Administration
                } |
                //0.2f |0.5rt 0.75f @Font {
                        Consulting -- Programming -- Design
                }
        }
}

Lout tables are also a bit of a conundrum for me.  Today I fought and
fought to get a table to expand to the full width of the page (less the
margins of course) by stretching the gap(s) between the (two) columns.
Nothing worked until as a last resort I put an empty column in the
middle with @HExpand, as so:

@CD @Tab
        @Fmta {
                @Col lines @Break A |
                @Col @HExpand B |
                @Col lines @Break C
        }
{
        A { for the left column }
        B { } # empty object for @HExpand to spread out
        C { for the right column }
}

In fact tables in general seem quite powerful, but few of what I would
consider to be standard examples are in the documentation.

Unfortunately Lout tables are nowhere near as powerful as tbl, even if
they are easier to use for the simple cases.

I've also had to do a fair bit of work to get a standard look & feel to
our documents without giving up on certain flexibilities.  For example
we have three offices and would like to be able to specify either a
common information, or "site" specific information.

What I've ended up doing is customising the "cdoc", "creport", and
adding a "legal", document type extensions.  I've used the same trick as
"mydefs" to include the "site" specific stuff.  This way I can share the
common style options and custom definitions (eg. the above @CompanyLogo)
in a common file that's included in "PlanixDoc", "PlanixReport", and
"PlanixLegal".  I first include "PlanixLocal" though, which can specify
a site-specific address string, etc., to override the standard
definitions in the system-wide "PlanixLocal" that is there for documents
that don't provide their own.

This local file also lets me ``turn on'' the "DRAFT" page background
without having to modify the @Use, by defining an object that's used in
the PlanixDoc @Use invocation:

def @PlanixPageBackground {
# un-comment the next line to make this a "draft" document...
#       @Scale 60d @Rotate lightgrey @Colour DRAFT
}

Which reminds me, the screening is not optimally set for printing grey
backgrounds, and this is especially apparent on a true 600dpi printer.
Somewhere I have a line of PostScript with resets the screening to an
optimal value for a 300dpi printer, and I hope to find some way for Lout
to use that in its document setup.

Back to @Use....  I'd like to do this kind of indirection for more or
even all parameters of the @Use invocations so that an optional local
file ala "mydefs" or "PlanixLocal" could modify appropriate parameters.

This would be even easier if it were possible to "undef" or "redef" an
object -- your global document setup file could include the defaults,
then local re-definitions, and then invoke @Use.  This *should* make it
possible to never have to write your own document setup file, but rather
only re-define the desired objects that are in turn handed as parameters
to the now generic @Use invocation.

I tried to do something even more complex for the page background setup
before I discovered the object scoping rules fouled me up (perhaps
export would have worked):

def @SetPlanixPageBackground
        right   PgBgType
{
        PgBgType @Case {
                { draft } @Yield {
                        def @PlanixPageBackground {
                                @Scale 60d @Rotate lightgrey @Colour DRAFT
                        }
                }
                else @Yield {
                        def @PlanixPageBackground { }
                }
        }
}

(If I had done "export @PlanixPageBackground", would it have worked?  I
don't even know if I want to know!)

I'm still working on completing my "@LegalDocument" extension.  I'd like
to be able to have numbered paragraphs, and perhaps slightly more
flexible control over headings (perhaps defined as separate types of
sections?).  There are probably a lot more ``features'' of legal
documents for which a Lout document layout extension could provide
assistance with....

Another thing that has me extremely puzzled is why in a display a pair
of objects defined as a set of lines behave different from (and wrongly)
the same lines of text included directly.

This works fine:

@CD clines @Break {
Suite "#"1000
1234 Any Street, West
Big City, Province
Canada  L0L 0L0
"+1 416 443-1734"
}

whereas this needs some manual adjustment so that the objects don't run
together:

def @CompanyFullAddress {
Suite "#"1000
1234 Any Street, West
Big City, Province
Canada  L0L 0L0
}

def @CompanyPhoneNumber {
"+1 416 443-1734"
}

        .
        .
        .

@CD clines @Break {
@CompanyFullAddress
# I do not know why this weirdness is necessary to get the display right...
0.1v @High { }
@CompanyPhoneNumber
}

-- 
                                                        Greg A. Woods

+1 416 443-1734                 VE3TCP                  robohack!woods
Planix, Inc. <address@hidden>; Secrets of the Weird <address@hidden>