[pmwiki-users] PmWiki DocumentationGuidelines

[Patrick R. Michaud]

On Sat, Mar 11, 2006 at 08:05:06PM +0000, Hans wrote:
> PmWiki.DocumentationGuidelines looks good.
> 
> In addition I would like guidance on some points about text layout:
> 
> When do we use [@ ....  @] and when @@ ... @@ ?
> 
>      (I usually use [@ ... @] for all markup documentation,
>       but have not given the other any thought)

Use [@...@] when you want PmWiki to not interpret any of the
content as markup, or when it's important to preserve newlines
and spacing.  Use @@...@@ when you just need monospace text
(i.e., <code>...</code>).  

Originally [@...@] was just a shortcut for @@[=...=]@@, although
that's no longer the case.

> Shall blocks of code be indented with
> ->[@
> ..
> @]
> 
> and sometimes
> -->[@
> 
> rather than doing character indents like
>         [@ .....

I'm thinking that ->[@ is likely to be more consistent.

> Shall placeholders for variable values be written out as an example
> value rather than symbolic as <value> ?
> 
>      (I much prefer example values, names etc.)

I prefer example values as well (this is what all of the *Variables
pages have done).  I tend to be a learn-by-example sort of person.

Pm