Re: General wiki rules
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.cudba...@freeradius.org
RADIUS - Half the complexity of Diameter
-
List info/subscribe/unsubscribe? See http://www.freeradius.org/list/users.html
Re: General wiki rules
Arran Cudbard-Bell a.cudba...@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 spacespace
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 spacespacehomedown-cursorgoto 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!
-
List info/subscribe/unsubscribe? See http://www.freeradius.org/list/users.html
Re: General wiki rules
On Jul 15, 2011, at 10:30 AM, Alexander Clouter wrote:
Arran Cudbard-Bell a.cudba...@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 spacespace
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 spacespacehomedown-cursorgoto 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.cudba...@freeradius.org
RADIUS - Half the complexity of Diameter
-
List info/subscribe/unsubscribe? See http://www.freeradius.org/list/users.html
Re: General wiki rules
Arran Cudbard-Bell a.cudba...@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. - List info/subscribe/unsubscribe? See http://www.freeradius.org/list/users.html
General wiki rules
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.cudba...@freeradius.org RADIUS - Half the complexity of Diameter - List info/subscribe/unsubscribe? See http://www.freeradius.org/list/users.html
Re: General wiki rules
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 - List info/subscribe/unsubscribe? See http://www.freeradius.org/list/users.html
Re: General wiki rules
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. - List info/subscribe/unsubscribe? See http://www.freeradius.org/list/users.html
Re: General wiki rules
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.cudba...@freeradius.org RADIUS - Half the complexity of Diameter - List info/subscribe/unsubscribe? See http://www.freeradius.org/list/users.html
Re: General wiki rules
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.
-
List info/subscribe/unsubscribe? See http://www.freeradius.org/list/users.html
