On 3/3/06, Patrick R. Michaud <<a href="mailto:pmichaud@pobox.com">pmichaud@pobox.com</a>> wrote:<br>> > On Thu, Mar 02, 2006 at 06:00:33PM -0500, Bronwyn Boltwood wrote:<br>> > Assuming that no minor markups have slipped through the cracks,
<br>> > the difference is in the approach. Text Formatting Rules is for<br>> > people like me, who like to read the manual and understand how the<br>> > thing works. Basic Editing is much more a "get the job done"
<br>> > page.<br><br>> Well, the "read the manual and understand how the thing works" pages<br>> are supposed to be the pages listed near the beginning of the<br>> Documentation Index -- the "beginner topics" and "intermediate
<br>> editing topics" pages. Do those not work for this?<br><br>Links and Images are pretty good, though it would help to make the<br>language friendlier and simpler. The same applied to CreatingNewPages<br>before I rewrote it just now. :)
<br><br>I also like the list of intermediate topics in DocumentationList, for<br>the simple reason that it gives new authors a clue of just how much<br>PmWiki can do beyond links and bullets. Some of PmWiki's real power<br>
tools -- like pagelists and conditional markup -- are in there, which<br>makes them more approachable than if they were only in the admin<br>section.<br><br>But to return to BasicEditing and TextFormattingRules, BasicEditing
<br>currently has far more information in there than there ought to be.<br>BasicEditing's purpose is to be the getting-started guide that<br>introduces new authors to the most common markups, and gives them the<br>confidence to go out and use them. That's all that should be in
<br>there, but right now, BasicEditing has almost subsumed<br>TextFormattingRules. This is not good. TextFormattingRules is the<br>full-blown manual. <br><br>One thing I've noticed about the current BasicEditing is that it does
<br>a lot more showing than telling, compared to TextFormattingRules. We<br>should take a cue from that. I'm not offering to rewrite them both<br>right this minute, but I can be convinced to help. :)<br><br>If I did help, I've got two questions:
<br>* Can we please have the table of contents recipe turned on for<br> TextFormattingRules? Having a TOC will make the page much more<br> usable. <br>* is it possible to have a directive that works like markup, but whose
<br> output looks like this:<br><br> |-----------------------------------------------------------------|<br> | example markup | --> | rendered example markup |<br> |-----------------------------------------------------------------|
<br><br> Having a format like that will make it easier to show rather than<br> tell for any markup smaller than a large block.<br><br>Bronwyn