[pmwiki-users] TextFormattingRules and BasicEditing

[Bronwyn Boltwood]

On 3/3/06, Patrick R. Michaud <pmichaud at pobox.com> wrote:
> > On Thu, Mar 02, 2006 at 06:00:33PM -0500, Bronwyn Boltwood wrote:
> > Assuming that no minor markups have slipped through the cracks,
> > the difference is in the approach.  Text Formatting Rules is for
> > people like me, who like to read the manual and understand how the
> > thing works.  Basic Editing is much more a "get the job done"
> > page.

> Well, the "read the manual and understand how the thing works" pages
> are supposed to be the pages listed near the beginning of the
> Documentation Index -- the "beginner topics" and "intermediate
> editing topics" pages. Do those not work for this?

Links and Images are pretty good, though it would help to make the
language friendlier and simpler.  The same applied to CreatingNewPages
before I rewrote it just now. :)

I also like the list of intermediate topics in DocumentationList, for
the simple reason that it gives new authors a clue of just how much
PmWiki can do beyond links and bullets.  Some of PmWiki's real power
tools -- like pagelists and conditional markup -- are in there, which
makes them more approachable than if they were only in the admin
section.

But to return to BasicEditing and TextFormattingRules, BasicEditing
currently has far more information in there than there ought to be.
BasicEditing's purpose is to be the getting-started guide that
introduces new authors to the most common markups, and gives them the
confidence to go out and use them.  That's all that should be in
there, but right now, BasicEditing has almost subsumed
TextFormattingRules.  This is not good.  TextFormattingRules is the
full-blown manual.

One thing I've noticed about the current BasicEditing is that it does
a lot more showing than telling, compared to TextFormattingRules.  We
should take a cue from that.  I'm not offering to rewrite them both
right this minute, but I can be convinced to help. :)

If I did help, I've got two questions:
* Can we please have the table of contents recipe turned on for
  TextFormattingRules?  Having a TOC will make the page much more
  usable.
* is it possible to have a directive that works like markup, but whose
  output looks like this:

  |-----------------------------------------------------------------|
  | example markup           | --> | rendered example markup        |
  |-----------------------------------------------------------------|

  Having a format like that will make it easier to show rather than
  tell for any markup smaller than a large block.

Bronwyn
-------------- next part --------------
An HTML attachment was scrubbed...
URL: /pipermail/pmwiki-users/attachments/20060303/df7c3d79/attachment.html