General wiki rules

[Phil Mayers]

On 07/14/2011 06:09 PM, Arran Cudbard-Bell wrote:

> 1. HTML tags like '<pre>' will not be parsed by all renderers, just
> because it works in Gollum, doesn't mean it will work with a proper
> renderer for that markup format.
>
> For markdown its 3 spaces or a tab in front of every line, for RST
> it's double colon, return, 4 spaces indent in front of every line.

I strongly, strongly, strongly dislike (i.e. hate) this mode of doing 
"code" or config files.

Why? Because if you use <pre> or MoinMoin style {{{ you can just 
copy/paste straight from the config file(s) you're pulling the examples 
from without having to prepend whitespace.

If you make me indent using whitespace to get preformatted text, then 
you've lost me I'm afraid; I just won't bother. Those few seconds push 
the cost too high.

> 2. The main reason for moving to Gollum was so that users could
> contribute directly to documentation without needing to learn GIT.
> The end goal is to distribute the entire wiki with the server tar
> ball, which means people will be reading just the plaintext source.

In which case, my argument holds the other way; people will want to 
copy/paste straight out of the examples.

You need to come up with something better for preformatted code IMHO. 
Your choice of course.