[pmwiki-users] PmWiki Clipboard extension

[Patrick R. Michaud]

On Fri, Dec 02, 2005 at 06:55:37PM +0000, J. Meijer wrote:
> Some time ago I posted the Clipboard extension to the Cookbook. Pm recently 
> commented it asking how it differs from the (:include:). In the mean time 
> I've upgraded the script a bit and I think the ideas are really worth 
> presenting.

There are indeed some excellent ideas here, but there's also some
overlap with other features that we should resolve.

> ! Basic functionality
> 
> The clipboard defines the capability to cut, copy and paste 'clips'. A 
> source page needs to define a clip, using (:cut:) or (:copy:) and the 
> destination page can (:paste:) it.
> 
> A clip is any text, and it is interpreted as a number of lines, f.e. this 
> defines clip 'pagemenu':
> 
>  (:cut pagemenu:)
>  * PageMenu item1
>  * PageMenu item2
>  (:cutend:)

In PmWiki one would currently do this as

    [[#pagemenu]]
    * PageMenu item1
    * PageMenu item2
    [[#pagemenuend]]

If shouldn't be displayed (i.e., "cut" instead of "copy"), it can be 
wrapped as a >>comment<< section.  Still, I like (:cut:) and (:copy:)
as another way to delineating sections in markup text.

> The sidebar is expected to have this directive:
>  (:paste pagemenu:)
> A similar (but less flexible) result could have been achieved by writing:
>  (:include {$Group}.{$Page} lines=2:)

One would write it as

    (:include {$FullName}#pagemenuend:)

and still have pretty much the same flexibility.

> The main difference of course being that the include would fix the source 
> page while (:paste:) doesn't do such an assumption, the clip can come from 
> any source. 

No, (:paste:) instead makes other assumptions about the order in
which PmWiki pages are processed, which isn't true in certain contexts
or skins.  

For example, doing (:paste pagemenu:) in the sidebar doesn't grab clips
from the main page when someone does ?action=diff, ?action=upload,
?action=edit, etc.  Similarly, authors may be very surprised when
(:cut:)...(:cutend:) sections in the sidebar can't be pasted into
the main text.  And in some skins the sidebars are processed before
the main page, which means that (:paste:) w/o a pagename wouldn't work
there, either.

> The cut-syntax allows one to extract (include) clips from any page, or the 
> entire pagetext itself. The result is processed just like in the include 
> directive, so one can extract specific lines from within a clip.

This seems equivalent to what we have now.

> Note: Clips can also be defined in an XLPage, providing a site-wide 
> 'gallery' of clips. 

I'm not sure why we would want to place clips into an XLPage.  But
we can already have a side-wide gallery of clips, via:

    (:include Site.ClipGallery#clipname:)

One problem with (:cut:)...(:cutend:) clips is that someone viewing
the page may not realize the clip is there -- they can only be seen
when editing the page.  (Along this same line, someone seeing 
(:paste pagemenu:) in a page's markup has no idea where to look for the
clip definition, which also promotes author confusion.)

> <! Pasting clips
> 
> The paste directive/command/statement defines additional capabilities not 
> found in the include directive:
> 
>  (:paste person id=Name:)
>    Search clip 'person' for a section named 'Name'.
>    Sections recognized are headers, lines of the format
>      Name: Patrick Michaud
>    or lines in simples tables with the left columns
>    being 'Name'.

I think we could equivalently do this by adding capability to the
(:include:) directive.  However, I think that "id=" is not a good
choice for the argument parameter, since "id=" already has a different
meaning in the context of HTML tags.  Something like "field=" might
be a better choice.  Or "fields=", so we could get several items out
at once:

    (:include PageName#person fields=Name,Address:)

>  (:paste RecentChanges extract=regular-expression:)
>    Transforms content of RecentChanges, retaining all text matched by
>    regular-expression, then pastes result.

Very interesting.  Again, could be added to (:include:), but
I think this capability falls afoul of PmWikiPhilosophy #3 until
we see a lot of use for it.

>  (:paste RecentChanges sort:)
>    Gets RecentChanges, sorts it, then pastes it. Note:
>    markup confuses sorting, so be sure to use the
>    [[text -> link]] format for links.
>  (:paste pagemenu reverse:)
>    Reverses order of lines in clip 'pagemenu' and
>    pastes result. Use in combination with sort.

I think we already have better forms for these via the (:pagelist:) markup:

    (:pagelist trail=RecentChanges order=name:)
    (:pagelist trail=RecentChanges order=author:)
    (:pagelist trail=RecentChanges order=-time:)

>  (:paste RecentChanges columns=2:)
>    Gets RecentChanges, format it into a table with
>    2 columns and pastes it.

Hmm, this might be an interesting option for (:include:).  But
still better might be to just have a (:columns:) directive that
works on any markup text, not only things that are pasted:

    (:columns 2:)
    Here is my text.
    * bullet list
    * bullet list
    (:include MoreText:)
    (:columnsend:)

Also, in the current clipboard.php recipe the columns=2 option seems
to suppress any block formatting of the pasted text.

>  (:paste RecentChanges list=enumerated:)
>    Gets RecentChanges, pastes it as an #enumerated list.
>  (:paste RecentChanges list=bullet:)
>    Gets RecentChanges, pastes it as a *bullet list.

    (:pagelist trail=RecentChanges fmt=simple:)
    (:pagelist trail=RecentChanges fmt=enumerated:)  # option

> I think these properties make it a candidate for inclusion into the core. 
> Boldly stated the include-statement should be deprecated and replaced by a 
> (:paste:).

I think we just add some of paste's capabilities into (:include:).
>From a linguistic point of view, most people will think "include"
as opposed to "paste".  We can also see about adding (:cut:)
and (:copy:) as alternative mechanisms for defining includable sections.

> ! Controlling CSS
> 
> A recent simplistic extension brings a happy capability: paste clips 
> directly into CSS and skin your pages on the fly. For example:
> 
>  (:css:)
>  body { background-color:black; }
>  (:cssend:)
> 
> makes the page-container background black. 

We've discussed the possibility of a (:css:) directive in the past,
and generally rejected it as being a little too dangerous to give
authors full control of the css.  It probably needs some filtering.
Also, be aware that the form of directive I've been using is

   (:css .classname { background-color: black; } :)

which may conflict with the (:css:)...(:cssend:) form you're proposing.

Pm