General wiki rules

[Arran Cudbard-Bell]

Ok heres the deal.

There are three formats we use on the wiki:

1. markdown
2. restructuredtext
3. mediawiki

Mediawiki pages contain content from our old mediawiki instance. Feel free to convert these to RST or Markdown, the wiki cloth renderer sucks so they probably won't render quite right in mediawiki format anyway.

restructuedtext pages either came from the docs directory in the server, or were created in RST because the author thought they might one day be included in the server docs. If you're editing a page in restructured text DO NOT CHANGE THE FORMAT. RST is the preferred format for all new pages.
 
markdown pages are intended to exist exclusively on the wiki, we only really allow markdown because the syntax is easier than RST and there are cute little buttons to do basic formatting so it makes it easier for wiki novices to contribute.

HTML tags in wiki content are bad. DO NOT USE THEM EVER! Instead use the proper code formatting system for the format you're using. 

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.

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. Having HTML tags everywhere is ugly, having properly indented code examples is pretty.


-Arran


Arran Cudbard-Bell
a.cudbardb at freeradius.org

RADIUS - Half the complexity of Diameter