Re: @Break semi-bug

[Valeriy E. Ushakov]

On Mon, May 07, 2001 at 07:35:06 +0400, Adrian Kubala wrote:

> If "//" joins objects vertically, why doesn't "@Break" introduce the
> "//" itself? 

Lout objects are cannot affect the context they appear in, this is the
primary reason why Lout needs macros.


> What meaning does an "&" --- which as far as I can tell is the same
> as "|", although I couldn't find where it's explained explicitly ---
> have after a vertical break?  Regardless, why does it "suppress" the
> meaning of the @Break?

"&" is a "paragraph" concatentation.
See section 3.2 of the expert's guide.

In a nutshell, Lout _defines_ paragraph to be a sequence of objects
concatenated with "&" (white space between two objects is an implicit
"&").

When available width is not enough, Lout performs paragraph breaking
by converting some of &'s into "//1vx" - that's by breaking paragraph
into lines.  It also performs line justification as specified by the
enclosing @Break symbol.  In other words @Break does NOT create a
paragraph, it just specifies paragraph breaking style.

Nested @Break withing one paragraph might be confusing.  For

    // & clines @Break { ... }

the "fully-pronounced" form is something like

    // @InitialBreak @Break { "" & { clines Break { ... } } }

and outer @Break cancels the effect of the inner.


> I ask because I'm trying to create a simple macro like so, and get more
> confusing behaviour which seems to have similar causes:
> 
> def @Letter right @Body
> {
> @Doc @Text @Begin
> @PP
> #//
> @Body
> @End @Text
> }
> ...
> @Letter @Begin
> address@hidden
> Blah blah
> @End @Letter
> 
> If you uncomment the "@PP", the body doesn't wrap properly. 

Because @PP @Body creates paragraph that has the whole @Body as a
single word (object) in it.


> If you uncomment the "//", it's fixed.

Because now you have an empty paragraph followed by the @Body.

    @PP {}
    //
    @Body

i.e.

    //@ParaGap { @ParaIndent @Wide {} } & {}
    //
    @Body

and @PP doesn't affect the @Body.


> Is there a simple rule for when "//" is required that doesn't
> require me knowing the implementation of the doc macros?

Well, macros are really there only to implement syntactic sugar for
the end user that types the document.  But they promptly become a
syntactic strychnine if used inside definitions by an unwary.

As a rule of thumb, avoid macros in definitions unless you understand
what they do.  Macros serve to hide ugly details from user that types
his document (e.g. see the discussion of @Display in expert's guide).
It is just a list of tokens, so when you apply it "inline" and when
you apply it to a prameter the effects are different.  In

    @PP blah blah

@PP "fuses" with the following text, but in

    @PP @Body

the @Body is already "promoted" to an object and @PP cannot
"penetrate" the object's boundary.


I see that macros cause a lot of confusion for people that starts to
write their own definitions.  Perhaps expert's guide should expand a
little more on why macros are needed and how (and how not) they should
be used.  Given the amount of confusion they cause, they definitely
deserve a section on their own.

Hope this helps.

SY, Uwe
-- 
address@hidden                         |       Zu Grunde kommen
http://www.ptc.spbu.ru/~uwe/            |       Ist zu Grunde gehen