[pmwiki-users] Using descriptions more systematically

christian.ridderstrom at gmail.com christian.ridderstrom at gmail.com
Sun May 28 13:48:24 CDT 2006

On Sun, 28 May 2006, Patrick R. Michaud wrote:

> christian.ridderstrom at gmail.com wrote:
>> It looks promising so far, although I'm having some problems because it 
>> is not possible to place anything in a description. Or possibly, 
>> because it's not possible to show anything using just {$Description}. 
>> Take a look at these two pages for instance:
>> 	http://pmwiki.org/wiki/TestDescription/ComplicatedDescription0
>> 	http://pmwiki.org/wiki/TestDescription/ComplicatedDescription5
>> Any thoughts on how the situation can improved for these specific
>> problems?
> The (:description:), (:keywords:), and (:title:) tags don't allow 
> embedded markup.  They are really intended for use to generate <meta 
> name='description' content='...' /> tags or values for various web 
> feeds, and of course markup isn't allowed in them there.

I knew that pmwiki markup isn't allowed there, but you do mean that HTML 
isn't allowed either?

Anyway, I wrote the rest of this post first and then I realised it was 
getting rather long so I went up back here to the beginning. I'll leave 
the long stuff at the end for reference, and instead write my thoughts on 
what I think I need. Some of this might only be relevant to my user case, 
and I don't suggest these solutions are good for everbody.

I do however think that many (most?) of the wikis would benefit from a 
more structured and organised approach to page descriptions. Being able to 
automatically generate page maps with page descriptions seem like one very 
useful thing for instance.

* Page descriptions should be easily seen by the reader, especially
   since most of my readers will not have seen any of the pages before.
   They therefore need the description to quickly understand what the page
   is about. Not all of the description may have to be visible at once,
   something like a popup text might be useful to save screen area.

* I'll use ''description area''' to denote the area (or popup) on the
   web page where the page description is shown.

* The description area should be relatively prominent, and stay in a
   consistent location (i.e. the same location for different pages).

* It's very imporotant that authors are encouraged to write descriptions.
   It should therefore be very easy to create/modify the description.

* I'll use the description of a group's home page to describe the group.

* It should be possible to generate page listings that extract the
   page description. This then lets you generate a sort of site map.

* It should be possible to extract the page description for a single
   page automatically, thus making it easy to create an index page for
   trails where each item describes the corresponding page. This is
   just what John Rankin's teasers let you do today.

As for solutions, I've tried a few over these last few years and I discuss 
them below. Here are the conclusions so you don't actually have to read it 
all below:

* Using anchors and other "complicated" stuff in order to define the
   description isn't very good. Descriptions tend to not get written,
   or anchors are subtly mis-spelled.

* Using (:include:) to insert a description can cause spectacular
   problems when the ending anchor is incorrect.

So I think I'd really like to try a solution where the authors can edit 
the description in a separate field. It could be located above the edit 
area for instance. Any thoughts on how to achieve this?

Especially as I need to be able to store the description somewhere, as 
well as retreive and insert it into the page template (or GroupHeader).

It might still be possible to store the page description within anchors in 
a wiki page. Then it's a matter of adding a separate area to the edit page 
that only lets you edit what's inside the anchors.  I guess this is sort 
of similar to section editing?

Ok, now back to Patrick's reply to my idea about using (:description:) 
as the mechanism to add descriptions to pages:

> This is a case where I think that anchors might make more sense than 
> tags -- i.e.,

Your solutions below don't feel so good for various reasons, but maybe you 
can help me work around the problems. Many of the problems are common for 
all the solutions. Let me start with describing a few solutions I've 
already tried:

* John's teaser without anchor, i.e. I introduce the convention
   that the first line of the page describes the page. Eg.
 	This is the page's first line, easily extracted with (:para:)

This is a good solution in the sense that no extra typing is required. It 
is also good since the description is easily seen when editing the page. 
Unfortunately it is not obvious that you should place a page description 
on a single line first on a page... That might OTOH be helped by adding 
instructions to the edit page in a very large font...

A big drawback here is that sometimes you don't want the description shown 
there. In fact, sometimes you don't want the description to be shown at 
all *inside* the wiki page area. (I haven't tested showing the description 
in some dedicated are of the web page yet, but I think that'd be fine with 
all pages).

One reason that you don't want the description shown could be that it will 
look strange coming just before the actual page content. The language of 
the description doesn't fit with the rest. Or that some pages are actually 
included into other pages, and doesn't make much sense on their own. They 
still deserve a description though.

Yet another drawback is the limitation to a single line. This can probably 
be fixed by using the first line and everything up to a blank line.

Besides these problems, I've found John's teasers useful. Being able to 
use them for creating trails with 'T* [[page]]' is very convenient. The 
only problem there is that the markup is very unintuitive for new authors.

* John's teaser with an anchor, i.e. use the convention that a specific
   anchor identifies a line as the description of the page.
 	[[#teaser]]This line is a teaser, easily extracted with (:para:)

This is like a teaser placed on the very first line, except that now it's 
marked with an anchor and can be placed anywhere in the page's source, 
(i.e. not in an included page). Being able to place it anywhere can be an 
advantage, and another advantage is that adding a descriptive anchor like 
"[[#teaser]]" or "[[#description]]" makes it easier for an author editing 
an existing page to understand that the line is a description.

On the other hand, the author now has to type more stuff. Especially if 
you don't want the description shown where it's defined, i.e.

 	(:if false:)
 	[[#teaser]]This is the teaser...

Getting authors to write all this is difficult of course... and with more 
to write, they are more likely to spell something wrong among all the 
strange and scary characters.. oops, sorry. Got off track there. Anyway, 
this approach was too "complicated" for some of my co-workers.

* Placing tags around the whole description, i.e. use the convention that
   text within certain anchors define the page description.
>    [[#description]]
>    This is the description of the page, which\\
>    can contain [[markup]] and other features.
>    [[#description-end]]

I've used this alternative before, and it is similar to the teaser 
alternatives above. There is even more that can go wrong here of course. 
Especially with (:if false:) to keep it hidden.

There is also a big problem when the anchor is written incorrectly and 
(:include:) is used. You can end up with the entire page inside the 
description. This is the biggest problem IMO with this approach.

* Using div to mark the description combined with anchors, i.e. use the
   convention that certain anchors within a <div> define the description.

>    >>description<< [[#description]]
>    This is the description of the page, which\\
>    can contain [[markup]] and other features.
>    >><< [[#description-end]]

This one I haven't actually tried. It's even more to type (bad), but on 
the other hand it could at the same time be configured to be hidden. Then 
it's placement in the page's source doesn't matter.

It still has the same problem with (:include:) v.s. the end anchor 


Christian Ridderström, +46-8-768 39 44               http://www.md.kth.se/~chr

More information about the pmwiki-users mailing list