[pmwiki-users] Permissions conundrum, section behaviour

[Henrik Bechmann]

Patrick,

For purposes of this discussion, let me define a term for a key 
abstraction: "textblock".

A textblock is an arbitrary collection of text, semantically rich to 
users on its own, available for presentation (possibly in various 
forms), and available for arbitrary combination and re-combination with 
other textblocks to generate user-defined representations of meaning. 
Textblocks can contain inner structures such as, say, wikimarkup, to 
enhance organization, meaning, and readability for users. It is 
understood that the boundaries of textblocks respect the integrity of 
these internal structures.

Textblocks can be arbitrarily combined and recombined into pages, which 
can themselves be arbitrarily combined and recombined. Pages can be 
combined into groups, and groups into wiki fields. Textblocks are 
understood to be the smallest atomic unit of semantically rich text 
understood by the PmWiki application, with the possible exception of the 
weak -- forgive me -- notion of text delimited by anchors.

The textblock can be viewed as an abstract data type: the specification 
of a set of data, and the operations that can be performed on that data.

The implementation of textblocks can take various forms, some of which 
(but not all imaginable variations), are described in your use cases at 
http://www.pmwiki.org/wiki/PmWiki/Comments-UseCases.

Each of these cases would take on specific internal structures, and 
variations of operations performed on that data. For example:

The textblock implementation "comment" is considered to be a small 
atomic textual unit representing an idea related to its textual context. 
You propose several variants of these:

- adding comments to the current page, possibly with associated 
permissions, and placement after entry
- adding comments to a different page, possibly with complex permissions 
in relation to the current page, and identification of target pages and 
page placement.
- adding comments to a standard group page form, possibly with complex 
permissions in relation to the group and pages, in particular in 
relation to creation of new pages. In relation to a common page target, 
behavior relating to new page creation.

You go on to define other possible textblock implementation: item lists, 
specifically blocklist items; collections of votes; and collections of 
RSVPs. These have implied particular specifications of internal 
structures, and presumably specific operations.

In addition we have discussed "section-edit" blocks (defined as 
implicitly bounded by headings), blogs (which can be understood as sets 
of ordered, related, textblocks), end emails.

There is no doubt in my mind whatsoever that this set of implementations 
of the textblock abstraction is just the beginning of what can be 
usefully conceived and implemented. This conclusion has a couple of 
important consequences:

If the concept is properly implemented, the richness and usefulness of 
PmWiki will increase substantially. If not properly implemented, 
substantial opportunity will be lost, with attendant disappointment on 
the part of the community.

Presuming the first is correct (the concept is implemented in such a way 
as to allow for reasonably convenient access to development of variants 
of texblock implementations), then the implementation should be realized 
in such a way as to maximize clarity and usability, and minimize confusion.

My contention is that to implement each variant as though it were 
unique, or to implement variations in only loosely related ways, would 
be to invite the appearance of chaos and overwhelming (read 
intimidating) detail and choice. Yet with the ADT concept, I submit that 
a tidy, consistent, and apparently concise implementation is available, 
as follows:

1. The name of the abstraction (eg "textblock" or "section"), having 
implications for clarity an delineation.
2. The type of implementation (eg. "comment" or "blocklist" or "email"), 
having implications for internal structure and behavior
3. An optional unique identifier, having general implications for 
matching and sorting (this one could be troublesome)
4. A generalized interface, allowing for other parameters (consistent 
with other PmWiki structures: the "parm=value" pair)., having 
implications for development of currently unknown implementations.

Finally, I submit that the natural place for these components is in the 
delimiter (specifically the delimiter header).

Now, on to some use cases and examples:

1. The comment.

The directive (the name and parameters for which I choose arbitrarily -- 
it's another discussion) is placed on the page, say (:comments:), 
causing comments to be added:

First comment on a page:

[[#comment]]
first comment text
[[#commentend]]

Second comment on a page:

[[#comment]]
second comment text
[[#commentend]]

Right away we have broken the HTML rule to have unique anchor names. So...

[[#comment2]]
second comment text
[[#commentend2]]

Where does the ordinal suffix come from? Surely not from the user (it is 
logically arbitrary and unnecessary -- an imposition on the user). Then 
it would have to come from the system, but again for no good reason, 
other than to dodge the HTML rule. And as you know identifiers should be 
non-compound and as devoid of meaning as possible.

Also given that the anchor name is arbitrary, the text author editing 
the full page would have no immediate way of knowing what it is, other 
than the convention of embedding the term "comment" in the page, which 
is difficult to enforce and understand, and violates the rule of 
non-compound non-semantic id's.

With a delimiter:

First comment on a page:

[!textblock comment!]
first comment text
[!textblockend!]

Second comment on a page:

[!textblock comment!]
second comment text
[!textblockend!]

No problems! And simple! And clear!

If an identifier is required (say by some recipe):

(:comments numbered:)

First comment on a page:

[!textblock comment 1!]
first comment text
[!textblockend!]

Second comment on a page:

[!textblock comment 2!]
second comment text
[!textblockend!]

If further information was required by a recipe:

(:comments customcomment:)

[!textblock customcomment 1 time=10/5/06-12:46a author="Henrik Bechmann" 
pwd="132kljqdfpoasf21324;lkaf"!]
first comment text
[!textblockend!]

The placement and edit restrictions would be controlled by policies, but 
that's another story.

2. Votes or RSVP's:

(:comments votes christmasparty:)

[!textblock votelist christmasparty!]
HenrikBechmann, yes
PatrickMichaud, no
[!textblockend!]

(:comments votes article:)

[!textblock votelist article="The Power Of PmWiki"!]
HenrikBechmann, 5
PatrickMichaud, 3
[!textblockend!]

[!textblock votelist article="PmWiki at the Beach"!]
HenrikBechmann, 4
PatrickMichaud, 5
[!textblockend!]

(:comments blocklist:)

[!textblock blocklist!]
<blocklist data>
[!textblockend!]

3. Emails

[!textblock email from=henrik.bechmann at sympatico.ca time=10/5/06-12:46a!]
Cool project!

Best,

- Henrik
[!textblockend!]

I view section edit (as delimited by headings) to be a special case, 
with implied rather than explicit delimiters.

... you get the idea.

I acknowledge that my submission is vulnerable to critique, chiefly (in 
my view) that moving a wiki in the direction of a database program is a 
slippery and possibly perilous slope, and I certainly invite vigorous 
critique. But I think the idea has some merit.

Regarding your notes:

> I think that section-edit should be able to infer sections from
> natural markups within the page (e.g., headings and divs) rather
> than require a markup for each section to be edited.  
>
>   
Agreed. As noted, I think of this as a special case.
> I wasn't planning to allow attributes for anchors but I don't
> see any particular reason it can't be done if we need it:
>
>     [[#anchor abc=xyz]]
>   

OK for single instances, not so good for multiple instances.
> I agree with the notion that "anchors are an HTML construct".  
> The way PmWiki uses [[#anchor]] is to identify specific locations 
> in a page, and pairs of anchors can be used to identify
> full blocks of a document.  The fact that these happen to translate
> into <a id='...'></a> is a significant part of what we're
> doing, but [[#anchor]] already means a lot more to PmWiki than 
> simply "HTML construct".  (The two obvious examples are
> the fmt= parameter to pagelist templates and (:include Page#section:) ).
>   
I would argue that the notion of textblocks is so germane, that it 
warrants explicit treatment. (:include Page!textblockname!identifier:)
>   
> Possibly, but when it makes sense I prefer to re-use existing
> markups as opposed to creating new ones, especially if they're
> closely related.  I think our difference in viewpoints comes
> down to...
>
>   
>> - Delimiters, if named with the standard "section" name ([!section 
>> comment...!] or (:section comment...:)) are explicit and coherent, 
>> whereas it may be hard to differentiate anchors applied to section 
>> blocks from HTML anchors, etc.
>>     
>
> I don't see that differentiation is needed.  I'd need to see
> a clearer example of the markup advantage of 
>
>    (:section comment ...:)
>    alpha beta gamma
>    (:section:)
>
> over
>
>    [[#comment ...]]
>    alpha beta gamma
>    [[#commentend]]
>
>   
I see your point, but this is a specialized and limited example -- only 
one instance

>> - Delimiters form a conceptual coherent delineated balanced pair with 
>> matching directives. 
>>     
In this sentence I meant balancing, ie relating, the directive with the 
delimiter, not the head and tail portions of the delimiters.
> Ultimately I prefer [[#section]] over (:section:) because
>
>   - A url ought to be able to specify a certain section of a page,
>     and the url syntax for that is #section
>   
could add an anchor to a textblock
>> Directives such as (:commentaction parm parm parm:) 
>> provide the behaviour instructions; delimiters with attributes such as 
>> -- (:section comment:) text (:sectionend:) -- provide the clear matching 
>> output.
>>     
>
> I've thought a *lot* about things like (:commentaction parm parm parm:)
> the past week or so (including a test implementation or two), and
> I haven't found that it is simplifying or resolving the authorization
> issues I see, 
see the policies concept (prior email -- needs to be further 
investigated), removing this problem from the markup
> while it is definitely adding some complexity to the
> overall solution space.  

But I submit it simplifies the overall feature set.

------------------------------------

Lastly, a couple of personal remarks: First, my apologies for the length 
of this email. I felt some duty to make this case while you were still 
in beta. Second, I hope you understand that I make this submission with 
the greatest of respect for you, and the greatest admiration and 
affection for your product, PmWiki.

All the best,

- Henrik

-- 

Henrik Bechmann
www.osscommons.ca
www.bechmannsoftware.com
Webmaster, www.dufferinpark.ca