[pmwiki-users] Re: AllGroupHeader causes extra vertical space

[Patrick R. Michaud]

On Mon, Jul 25, 2005 at 09:59:09AM +0200, chr at home.se wrote:
> On Sun, 24 Jul 2005, Patrick R. Michaud wrote:
> 
> > On Sun, Jul 24, 2005 at 11:13:41PM +0200, chr at home.se wrote:
> > (:nl:) adds a newline only if there isn't one already there.
> > Thus,  
> > 
> >     (:include Group.SomePage)(:nl:)This is some text
> > 
> > will add a newline only if Group.SomePage doesn't end with a newline.
> 
> Um... from your description above, I suspect it's not working properly.
> Does this page render correctly in your opinion?
> 
> 	http://www.pmwiki.org/wiki/Test/Newline

Yes.  The key is to remember that (:nl:) adds a newline only if
there's not one already there.  Thus, from the examples on the
Test.Newline page:

    A line of text(:nl:)(:nl:)more text.  I thought I'd get some
    newlines here.

The first (:nl:) becomes a newline, so the markup becomes

    A line of text
    (:nl:)more text. I thought I'd get some newlines here.

The second (:nl:) does nothing, since there's already a newline
immediately in front of it, thus

    A line of text
    more text.  I thought I'd get some newlines here.

These two lines end up being rendered as a single paragraph.

In the second example, 

    Bla bla bla.  (:include NonExistingPage:)(:nl:)Some text - no new line??

After the include we have

    Bla bla bla.  (:nl:)Some text - no new line??

which then becomes

    Bla bla bla.  
    Some text - no new line??

which is again a single paragraph.

Okay, so now you're probably wondering what (:nl:) is good for.  Here's
the long answer:  it's primarily designed to add newlines around 
(:include:)s that may or may not have them already.  Consider a 
Site.SiteGroupHeader that contains

    %define=Pm color=purple font-style=italic%

but doesn't have a newline at the end.  The result of

    (:include Site.SiteGroupHeader:)Some text

is "%define=Pm color=purple font-style=italic%Some text"  which means
that the text will be rendered in purple.  To avoid this, an author
would have to write

    (:include Site.SiteGroupHeader:)
    Some text

which is equivalent to

    %define=Pm color=purple font-style=italic%
    Some text

and it looks fine.  But now, suppose someone edits Site.SiteGroupHeader
and puts a newline at the end of the %define=% line.  Then the markup 
above becomes equivalent to

    %define=Pm color=purple font-style=italic%

    Some text

and the inadvertent blank line generates a vertical space, which means
the author would have to go back to doing

    (:include Site.SiteGroupHeader:)Some text

to eliminate it.

So, the purpose of (:nl:) is to add in an extra newline only when 
it's needed:

    (:include Site.SiteGroupHeader:)(:nl:)Some text

which will always come out to

    %define=Pm color=purple font-style=italic%
    Some text

regardless of Site.SiteGroupHeader having a newline at the end of its
%define=... % statement..  A similar case exists for includes at the
end (e.g., footers).  Something like

    (:nl:)(:include {$Group}.GroupFooter:)(:nl:)(:include Site.SiteGroupFooter:)

can be used to make sure that each of the includes start at the
beginning of a line without inadvertently creating a blank one.

Originally I had thought that getting the newlines correct around
(:include:) markups would require some options, but then the problem
became needing diferent options to add a newline at the beginning
versus at the end, as well as being able to explain when to use it.
The (:nl:) markup ends up being a lot more flexible, because it provides
an easy way to insert newlines only where they're needed without
generating extra ones.

And, of course, this isn't a markup I expect authors to use very often;
they're really more of an "internal" markup.

Hope this helps,

Pm