<div class="gmail_quote">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]<br>
<br>On Fri, Feb 13, 2009 at 10:06 AM, <span dir="ltr"><<a href="mailto:john.rankin@affinity.co.nz">john.rankin@affinity.co.nz</a>></span> wrote:<br><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
>>A case can also be made that this and other "core markup" pages<br>
>>should use *only* functionality defined in Creole. All markup on<br>
>>the page should be an illustration of a Creole function. This is a<br>
>>radical suggestion; it means (:markup:) ... (:markupend:) is not<br>
>>allowed on core markup documentation pages.<br>
...<br>
For me it's a matter of consistency. If one is going to describe a<br>
set of core markup, then I think one should describe the core<br>
markup using only the core markup, so somebody viewing the<br>
page source sees only what the page describes.</blockquote><div><br>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.)<br>
<br>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.<br>
<br>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...]]?<br>
<br>Hah! I just "implemented" it as <a href="http://www.pmwiki.org/wiki/PmWikiCreole/EFNExplained">http://www.pmwiki.org/wiki/PmWikiCreole/EFNExplained</a> and <a href="http://www.pmwiki.org/wiki/PmWikiCreole/EFNByExample">http://www.pmwiki.org/wiki/PmWikiCreole/EFNByExample</a> 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.)<br>
<br>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...<br>
<br>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...?<br>
<br>-Peter<br></div></div><br>