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@freeradius.org RADIUS - Half the complexity of Diameter
On 2011/07/14 07:09 PM, Arran Cudbard-Bell wrote:
Ok heres the deal.
There are three formats we use on the wiki:
1. markdown 2. restructuredtext 3. mediawiki
I spent about 1/2 hour a while ago trying to get a basic "guide" to either markdown or restructuredtext. Google was unhelpful, are there any good tutorials? -- Johan Meiring Cape PC Services CC Tel: (021) 883-8271 Fax: (021) 886-7782 -------------------- Before acting on this email or opening any attachments you should read Cape PC Service's email disclaimer at: http://www.pcservices.co.za/disclaimer.html
Johan Meiring wrote:
I spent about 1/2 hour a while ago trying to get a basic "guide" to either markdown or restructuredtext.
Google was unhelpful, are there any good tutorials?
restructuredtext cheat sheet http://docutils.sourceforge.net/docs/user/rst/quickref.html Alan DeKok.
On Jul 14, 2011, at 7:37 PM, Johan Meiring wrote:
On 2011/07/14 07:09 PM, Arran Cudbard-Bell wrote:
Ok heres the deal.
There are three formats we use on the wiki:
1. markdown 2. restructuredtext 3. mediawiki
I spent about 1/2 hour a while ago trying to get a basic "guide" to either markdown or restructuredtext.
Google was unhelpful, are there any good tutorials?
See here http://wiki.freeradius.org/New-Wiki#Helping+out for links... Thats the best I could find. -Arran Arran Cudbard-Bell a.cudbardb@freeradius.org RADIUS - Half the complexity of Diameter
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.
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@freeradius.org RADIUS - Half the complexity of Diameter
Arran Cudbard-Bell <a.cudbardb@freeradius.org> wrote:
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.
I think that's Phil's point. The code he is cutting and pasting in is no doubt already indented. However, what it probably has is either: * no initial indentation (start <tab> or <space>) * that indential probably is a <tab> rather than <space><space> I love dokuwiki for documentation, but it is a right ballache to find that when you cut and paste in your configuration snippet I *then* have to go through <space><space><home><down-cursor><goto 10> before it is usable. Sure it seems not a biggy, but it is a right turnoff and makes us all less inclinded to put in the effort.
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?
That would be pretty schweet. I would not 'pre-process' the text, I would make sure those <pre>/{{{/whatever remains intact so you do not suffer indentation pain when editing existing content. Cheers -- Alexander Clouter .sigmonster says: I'm having a MID-WEEK CRISIS!
On Jul 15, 2011, at 10:30 AM, Alexander Clouter wrote:
Arran Cudbard-Bell <a.cudbardb@freeradius.org> wrote:
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.
I think that's Phil's point. The code he is cutting and pasting in is no doubt already indented. However, what it probably has is either: * no initial indentation (start <tab> or <space>) * that indential probably is a <tab> rather than <space><space>
Hmm re-reading the RST spec it seems that any indentation will work (i.e. one space before each line, or one tab). "To just include a chunk of preformatted, never-to-be-fiddled-with text, finish the prior paragraph with "::". The preformatted block is finished when the text falls back to the same indentation level as a paragraph prior to the preformatted block. For example: An example:: Whitespace, newlines, blank lines, and all kinds of markup (like *this* or \this) is preserved by literal blocks. Lookie here, I've dropped an indentation level (but not far enough) no more example" Is that any better? I mean you don't *have* to edit the wiki page in situ, usually I copy the text out of the webpage into BBEdit the paste it back... What we could do for the very active Git savy contributors would be to enable commit access to the wiki's repo, then you could work on the documents in gvim, vim, emacs... whatever at which point indenting blocks of code becomes very easy. Also lets you work on pages offline.
I love dokuwiki for documentation, but it is a right ballache to find that when you cut and paste in your configuration snippet I *then* have to go through <space><space><home><down-cursor><goto 10> before it is usable.
Sure it seems not a biggy, but it is a right turnoff and makes us all less inclinded to put in the effort.
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?
That would be pretty schweet. I would not 'pre-process' the text, I would make sure those <pre>/{{{/whatever remains intact so you do not suffer indentation pain when editing existing content.
But that'd mean i'd have to do the reverse when displaying the src, and I actually like viewing the src with indented code blocks compared to <pre> tags *sigh*. I could add a javascript function mapped to a key combo, that indents selected lines by one tab (more universal than spaces)? -Arran Arran Cudbard-Bell a.cudbardb@freeradius.org RADIUS - Half the complexity of Diameter
Arran Cudbard-Bell <a.cudbardb@freeradius.org> wrote:
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
I get that, and your efforts are much appreciated. My point was as Alex clarified - it's a pain to indent lines with space/tab in a browser text box. So much so that it will put me off contributing. There are loads of possible solutions - permit <pre>, convert it as per your suggestion, offer a button that uses javascript to indent the current selection... Personally I find the argument for plaintext docs weakens with every passing year; I routinely read the ISC bind ARM with links in a terminal. But if you're going to use plaintext, and to rule against certain plaintext markup forms, "hit space a lot" is not for me a compelling alternative :o) -- Sent from my phone. Please excuse brevity and typos.
participants (5)
-
Alan DeKok -
Alexander Clouter -
Arran Cudbard-Bell -
Johan Meiring -
Phil Mayers