[pmwiki-devel] Markup routine for style questions

[Petko Yotov]

Peter has replied to some of your questions, let me try the others.

W Randolph Franklin writes:
> I'm trying to understand how the markup routine works for style >> <<
> with a view to trying to get nested styles to work.
...
> 3. In  '/^>>(.+?)<<(.*)$/',   what is the final (.*)$ for?
>  The documentation does not mention trailing text after the <<.

Any markup after the >>...<< will be part of the content of the div block.  
You could have
    >>blue<< text in blue
    >>red<< text in red, etc.
    >><<

> 4. In  '(:div:)%div $1 apply=div%$2 '),   what do the percents do?

The percents wrap a "WikiStyle". A WikiStyle is a special markup which is  
converted by PmWiki to CSS styles or classes (an HTML attribute class="..."  
or style="...") which are applied to (inserted into) an HTML tag on the same  
line.

In this case, the >>WikiStyle<< line is first converted to (:div:)%div  
WikiStyle apply=div%.

In a second moment, the (:div:) markup is converted to <div> (or </div><div>  
if a div is already open).

In a third moment, the %div WikiStyle apply=div% markup is converted to eg.  
class="WikiStyle" and inserted into the previous <div> tag on the same line.

> This looks like a nested div, why?

Not exactly a nested div, divs can be nested if they have different numbers  
as suffixes, like this:

(:div1:) parent div1
(:div8:) nested div8 in div1
(:div:) nested div in div8
(:div:) close previous div, reopen new div in div8
(:div1end:) this will close div, div8 and div1

So, the >>...<< markup could be nested if before it we have a (:div#:) but  
in most cases it is a shortcut to quickly switch some styles to sections of  
a page.


> 5. Finally how do I set styles inside list items?   >><< and (:div:)
> terminate the list because they work only in column 1.   Percents appear
> to have an implementation error, where using apply causes the style to
> be ignored.   I need to use apply=p to avoid other formatting problems.

WikiStyles are "applied" to some tag on the same line, which could be a  
block (div, heading, list or list item) or inline (span, image, link).

If we want to apply the WikiStyle to a list item, we'll use the 'apply=item'  
or just 'item' keyword:

    * red text on black %item red bgcolor=black% (or %apply=item...%)

This will output something like:
  <li style="color:red; background-color:black;">red text on black</li>

If we don't use the 'item' keyword, PmWiki will try to create a <span>  
element with the same style="..." attribute, starting at the place where the 
%red...% markup is. If the markup is at the end of the line, nothing will be  
shown in your browser, but at the beginning, it may look similar to the  
previous one, but the HTML will be different:

* %red bgcolor=black% red text on black

will output something like:

  <li><span style="color:red; background-color:black;"> red text on  
black</span></li>

> # In a list item, using any 'apply' inside percents causes the style to
> be ignored.
> *  %red apply=p ignored%   red apply=p ignored  red apply=p ignored

PmWiki doesn't normally produce <p> tags inside <li> tags, so when you  
specify apply=p, PmWiki doesn't find a <p> tag on the current line and
the WikiStyle is ignored.

In a list item, use %...apply=item...% or just %item...%.

> Outside a list, there's no problem:
>
> %blue%   blue  blue  blue  blue  blue  blue  blue  blue  blue  blue

This will produce <p><span style="color:blue;">blue...</span></p>.

> %red apply=p %   red apply=p   red apply=p   red apply=p   red apply=p

This will produce <p style="color:red;">red...</p>.

I think that for someone with a lot of experience with HTML and CSS, the  
"WikiStyle" feature may look at first sight particular, complex or  
unintuitive, but the main reason for its existance is to make it very easy  
for authors without a lot of experience of HTML and CSS, to style their wiki  
pages. And it allows an experienced admin to define "shortcuts" or  
"abbreviations" capable of replacing a lot of CSS classes or styles, and  
making the editing very easy, fast and short for authors (and for the  
admin :-).

Petko