General wiki rules

[Arran Cudbard-Bell]

On Jul 14, 2011, at 9:57 PM, Phil Mayers wrote:

> 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.

Ok. I'm not saying these things to be an asshole. The point of moving to Gollum was that users would be able to contribute to the bundled documentation. The wiki now serves as a repository for server docs (or will do once we figure out subtrees), it just also happens to render those documents into HTML.

If you were rewriting server documentation which you knew was going to be read in plaintext format, would you start adding random HTML markup? The point of RST is that while it can be rendered up into another format such as HTML document, it should be just as easy to read and understand in its raw form.


>> 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.

If they're pasting into a virtual server instance they're going to need to indent at least one set of tabs if they want to keep the config looking pretty. If they don't care then not having the code indented won't matter to them either way..

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

There is no better alternative. You need to indent code blocks for them to be easily legible, as it breaks them out of the normal flow of the document.

If it's going to be a huge issue I could probably add something to gollum which converts <pre> tags into the appropriate white space scheme before committing the text to the repository. Would you still have an issue with this?

-Arran

Arran Cudbard-Bell
a.cudbardb at freeradius.org

RADIUS - Half the complexity of Diameter