I'm trying to understand how the markup routine works for style >> <<
with a view to trying to get nested styles to work. For reference,
here's the relevant code from scripts/stdmarkup.php
1. Why is > used instead of > in the search pattern? Since the page
being edited contains >, this should always fail.
2. Is there a reason that the pattern name is ^>> ? Does the leading ^
do anything in the pattern name?
3. In '/^>>(.+?)<<(.*)$/', what is the final (.*)$ for?
The documentation does not mention trailing text after the <<.
4. In '(:div:)%div $1 apply=div%$2 '), what do the percents do? This
looks like a nested div, why?
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.
--------------------
In a list item, percents work, boxing each line. > < and div do not, if
indented, or terminate the list, if not indented.
# In a list item, using any 'apply' inside percents causes the style to
be ignored.
%blue% blue blue blue blue blue blue blue blue blue blue
blue blue blue blue blue blue blue blue blue blue blue blue
blue blue blue blue blue
%red apply=p ignored% red apply=p ignored red apply=p ignored red
apply=p ignored red apply=p ignored red apply=p ignored red apply=p
ignored red apply=p ignored red apply=p ignored red apply=p ignored
red apply=p ignored red apply=p ignored red apply=p ignored red
apply=p ignored red apply=p ignored red apply=p ignored red apply=p
ignored red apply=p ignored
%green% green green green green green green green green green
green green green green green green green green green green
green green green green green green green green green green
green green green green green green green green green green
Outside a list, there's no problem:
%blue% blue blue blue blue blue blue blue blue blue blue
blue blue blue blue blue blue blue blue blue blue blue blue
blue blue blue blue blue
%red apply=p % red apply=p red apply=p red apply=p red apply=p
red apply=p red apply=p red apply=p red apply=p red apply=p
red apply=p red apply=p red apply=p red apply=p red apply=p
red apply=p red apply=p red apply=p
%green% green green green green green green green green green
green green green green green green green green green green
green green green green green green green green green green
green green green green green green green green green green
> 1. Why is > used instead of > in the search pattern? Since the page
> being edited contains >, this should always fail.
See htmlentities or htmlspecialchars. Typically in HTML putting < or
> signs will be interpreted as commands to HTML and so to avoid that
you use these special entities if you want to actually see a LT or GT
sign.
> 2. Is there a reason that the pattern name is ^>> ? Does the leading ^
> do anything in the pattern name?
The name of the rule is arbitrary -- it has no functional value other
than to identify the rule. Since this rule fires with lines that
START with >> the name of the rule includes the ^ anchor character
just so someone who knows regular expressions will know what type of
search will occur. But you could name it foo or sally or
rumpelstiltskin and it would not change the behavior of the rule --
it's just the name of the rule.
> 3. In '/^>>(.+?)<<(.*)$/', what is the final (.*)$ for?
> The documentation does not mention trailing text after the <<.
Looks like it just strips off any characters after the closing << and
then puts them back on again. So practically it has no effect.
Probably there was some special behavior that broke if it wasn't
handled like this, but since it didn't affect the functionality from a
user's perspective it's not mentioned in the documentation. You would
probably have to do some extensive testing to figure out what breaks
if you don't do that (or else hope that PM or Petko has a long memory
and can help you...)
> 4. In '(:div:)%div $1 apply=div%$2 '), what do the percents do? This
> looks like a nested div, why?
Looks like some style is being applied, but someone else more familiar
with the % styles can answer that one.
> 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.
On Fri, Oct 26, 2012 at 12:19:06PM -0400, W Randolph Franklin wrote:
> Markup('^>>', '<table',
> '/^>>(.+?)<<(.*)$/',
> '(:div:)%div $1 apply=div%$2 ');
> Markup('^>><<', '<^>>',
> '/^>><</',
> '(:divend:)');
> My questions:
> 1. Why is > used instead of > in the search pattern? Since the page
> being edited contains >, this should always fail.
One of the first markup rules that PmWiki performs is to convert all
<'s and >'s to html entities to minimize injection attacks.
> 2. Is there a reason that the pattern name is ^>> ? Does the leading ^
> do anything in the pattern name?
Pattern names are just identifiers, so it doesn't do anything.
But someone reading the rule or seeing the identifier in a list
would be informed that it's a markup that only applies at the beginning
of lines.
> 3. In '/^>>(.+?)<<(.*)$/', what is the final (.*)$ for?
> The documentation does not mention trailing text after the <<.
I'm not sure why there's a trailing (.*)$ there. There must've been
something that failed when it wasn't there, though.
> 4. In '(:div:)%div $1 apply=div%$2 '), what do the percents do? This
> looks like a nested div, why?
This rule is taking markup of the form
>>red something<< text
and converting it to markup of
(:div:)%div red something apply=div% text
This then gets processed by the standard (:div:) and WikiStyle
markup rules. The percents are just the standard WikiStyle markup, with the first 'div' causing standard div styles to be applied, and the 'apply=div' being thrown in to force application of the style to the entire <div> element that is ultimately generated.
> 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.
You might want %item%, as in:
* First item
* %item red% This item is red
* This item is normal
* %item blue% This item is blue
> --------------------
> In a list item, percents work, boxing each line. > < and div do not, if
> indented, or terminate the list, if not indented.
Technically, percent WikiStyles don't box an entire line -- they box content until either the end of the line or the next WikiStyle.
> # In a list item, using any 'apply' inside percents causes the style to
> be ignored.
> %blue% blue
> %red apply=p ignored% red apply=p ignored
> %green% green
For a variety of reasons, PmWiki doesn't wrap the content of list items
as <p> paragraph elements, even when surrounded by blank lines. Thus the
'apply=p' has no effect inside of a list item because there's no <p>...</p> available for it to apply the style to.
(One reason PmWiki doesn't put list item contents into <p>...</p> tags
is because <p> paragraphs in HTML 4 aren't allowed to have nested block elements, such as nested lists. I decided nested lists were more
important and went that direction.)
What sort of "other formatting problems" are you needing to
avoid by using 'apply=p'?
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 :-).
<pkw...@wrfranklin.org> wrote:
>...
> On 10/26/12 14:34, Peter Bowers wrote:
>> On Fri, Oct 26, 2012 at 6:19 PM, W Randolph Franklin
>> <pmw...@wrfranklin.org> wrote:
>>> 1. Why is > used instead of > in the search pattern? Since the page
>>> being edited contains >, this should always fail.
>> See htmlentities or htmlspecialchars. Typically in HTML putting < or
>>> signs will be interpreted as commands to HTML and so to avoid that
>> you use these special entities if you want to actually see a LT or GT
>> sign.
> My problem is as follows. I do know that, in html, you can use
> ampersand-lt-semicolon etc. They're converted by the html layout engine.
> However the file is still pmwiki code, not yet html. The pmwiki command
> in the file is two less-than chars. This markup rule should search for
> a pmwiki construct composed of two less-than chars. The fact that this
> markup routine, which is searching for two sets of
> ampersand-lt-semicolon chars, works is what puzzles me.
It all depends where the rule occurs in the order of rules. I don't
remember exactly which rule converts > to > and < to < and etc.
If you want to know which rule you can either code-read or else use
the final tip on
http://www.pmwiki.org/wiki/Cookbook/DebuggingForCookbookAuthors-Talk to see what your text looks like between each rule. (Do note the
cautions there -- you get a HUGE log file pretty quickly...)
