[Pmwiki-users] pmwiki.org converted to 2.0.devel27

John Rankin john.rankin
Sun Nov 28 22:18:07 CST 2004


On Saturday, 27 November 2004 9:18 AM, Patrick R. Michaud <pmichaud at pobox.com> wrote:
>Just to let folks know what's going on...
>
...
>The 2.0 documentation is incomplete, but I'll be working on filling in
>and updating pages over the next day or so.  Any help that others can
>provide is greatly appreciated.  If you see a page that looks wrong
>or otherwise needs improvement, you can add "TODO:" and a short description
>to the page, or make an entry in PITS.
>
First, congratulations and a big thank you to Patrick.

I have given a fair bit of thought and experimentation to making
the documentation easier for authors to use; in particular a better
EditQuickReference.

When editing a page, an author wants an easy way to find out
"How do I achieve effect xxx?"

Consider a MarkupQuickReference page showing examples of all markup 
effects, while hiding the markup to produce them.

If an author mouses over a particular effect, the markup to
generate that effect displays as a tool tip. For example, if
an author mouses over superscript (which is rendered as
superscript text), the tooltip is '^superscript^'

In other words, show an author what's possible, but hide the 
detail until it's needed. This makes it possible to put a lot
of effects into a small space, without losing clarity.

I'm thinking that one might put examples of block markups in 
a side bar and links and inline markups in a panel below the
edit box. But I'm still exploring different options.

How is this achieved?

The markup 
    {text:text definition}

generates
    <dfn title='text definition'>text</dfn>

Thus
    {'^superscript^':'^superscript^'}

generates
    <dfn title="'^superscript^'"><sup>superscript</sup><dfn>

In this example, the title text is wrapped in " ... " instead
of ' ... ' because it already contains a ' character. The
code takes care of this automatically.

When action=print, {text:text definition} renders as 
text (text definition).

And if you just write {text:text definition} ie with no leading
markup characters, it generates

    <dfn title='text definition' class='definition'>text</dfn>

The definition class adds a border-bottom: 1px dotted; style.

The code is basically working and I'll put up a demo as soon
as possible -- I'm still testing.

I considered several markups and propose {text:text definition}
for the following reasons:
- it's similar to the {abbr|abbreviation} extension: both
  generate a tool tip

- the : character suggests the :term:definition markup

- using [text|text definition] turns out to be a bad idea
  if you want a tool tip to show how links work


Comments and suggestions welcome.
-- 
JR
--
John Rankin





More information about the pmwiki-users mailing list