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
[email protected]
RADIUS - Half the complexity of Diameter
-
List info/subscribe/unsubscribe? See http://www.freeradius.org/list/users.html
