[pmwiki-users] Re-thinking Intro to markup pages

Peter Bowers pbowers at pobox.com
Wed Feb 18 03:07:19 CST 2009


I think that the new EditingForNewcomers page is a *great* resource...
Thanks for putting the time & energy into initially planning it and now
implementing it, John!  [polite applause in the background]

On Fri, Feb 13, 2009 at 10:06 AM, <john.rankin at affinity.co.nz> wrote:

> >>A case can also be made that this and other "core markup" pages
> >>should use *only* functionality defined in Creole. All markup on
> >>the page should be an illustration of a Creole function. This is a
> >>radical suggestion; it means (:markup:) ... (:markupend:) is not
> >>allowed on core markup documentation pages.
> ...
> For me it's a matter of consistency. If one is going to describe a
> set of core markup, then I think one should describe the core
> markup using only the core markup, so somebody viewing the
> page source sees only what the page describes.


I think I'm going to vote in favor of clarity over elegance on this
particular issue.  I think the EditingForNewcomers page as it stands has
*great* content -- a good balance of being minimalist while still showing
enough to be helpful -- "just what you need"...  My only concern with the
page as it now stands is that it is difficult to differentiate the structure
of the page from the markup examples themselves.  (You've already alluded to
this, John, in your desire for the dotted-line-box-frames.)

May I suggest that perhaps there is room for 2 completely parallel pages in
this category?  This could allow for both the clarity and the elegance.  One
might be EditingForNewcomers and (at the risk of getting too long)
EditingForNewcomersByExample.  The former could (:include ...:) from the
latter to ensure consistency between the 2 of them.  My thought is that in
this way you could have one page that is viewer-centric (the former) which
makes use of the markup markup and etc. to make sure it is very clear to the
person reading it.  Then you could have another page which is source-centric
which makes use of only the available markup and etc as you've been
suggesting, John.  At the top of EditingForNewcomers could be an
attention-getting comment in the source that tells people if they are trying
to learn pmwiki markup by looking at source they would be better going to
the ByExample page.

The only difficulty with this setup is that if we are to (:include ...:)
from EditingForNewcomersByExample then sections will have to be specified in
the source of that page ... which kind of (?) defeats the purpose of that
page.  We could do the include by line number, but that's a nightmare for
maintenance...  Maybe another source-level comment at the top of
EditingForNewcomersByExample which tells newbies to ignore anything that
looks like [[#EFN...]]?

Hah!  I just "implemented" it as
http://www.pmwiki.org/wiki/PmWikiCreole/EFNExplained and
http://www.pmwiki.org/wiki/PmWikiCreole/EFNByExample just to put feet to my
words.  Now you have a wonderful page with all kinds of wonderful examples
of the markup (:include ...:) with NO examples of any other kind of markup.
[sound of snickering at self followed by a deep sigh at the thought of 20
wasted minutes]  OK, so maybe the 2 pages would have to be kept in sync
manually rather than through includes...  (And that resolves the issue of
the [[#EFN...]] section markers in the ByExample page.)

Unless ... does anybody else see a need for a "meta-include" markup which
would occur at the very beginning of the rule set?  Perhaps simply
(:include! ...:) which would be *identical* to (:include ...:) except it is
executed before [=...=] and [@...@] and markup markup and etc?  Just a tho't
and I suppose pretty off-topic by this point...

Back on topic ... does the idea of 2 pages clarify things?   (Assuming it
was implemented in a way that actually works.)  I'm thinking these pages
won't get updated very often at all and so the potential issues of (1)
keeping them in sync and (2) having two pages to update are probably pretty
moot points...?

-Peter
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://www.pmichaud.com/pipermail/pmwiki-users/attachments/20090218/71a2ebb9/attachment.html 


More information about the pmwiki-users mailing list