How do I represent square brackets ([]) in RDoc?

Question

I am trying to document some rake tasks I've written using RDoc comments in my class and am running into trouble representing square brackets. I want to add some examples of how to run my rake tasks with parameters and so have an rdoc line like so:

# eg. rake build[MyProject]

The problem is that the RDoc parser convert creates a link instead of printing the square brackets. I have tried all sorts of escape sequences: [ ; [[ ; #{[MyProject]} ; [MyProject] but nothing seems to work.

Is there any way to escape these square brackets so they don't convert to a link?

Thanks, Aaron

Answer 1

Well with further experimentation I discovered a way to do it. If I put two spaces in front of each line, RDoc treats the line as pre formatted text and renders the brackets. Good enough for me.

The resulting RDoc line is:

#  eg. rake build[MyProject]

Answer 2

The <tt> tag will escape the link-text[hyperlink] syntax (and also put the text in a monospace font).

So this rdoc

# eg. <tt>rake build[MyProject]</tt>

will produce this documentation:

eg. rake build[MyProject]

Answer 3

Sometimes the solution is easy.

Code like text[par] creates text with a link to par. But if you put a space between text and [par] you get par with square brackets.

A short overview of different versions with []:

* [par] labeled list
* x[par] x is linked with par
* x [par] Text as is (space between x and par)
* []  brackets disapear
* x _[par]_  Content between[] disapears.

If you want to make the text with the text<space>[par]-solution in italic, you must use the <em>...</em> variant (not the underscore variant _..._).