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

score 3 · Accepted Answer · answered Nov 18 '10 at 12:52

3

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]

answered Nov 18 '10 at 12:52

Aaron Janes

304
3
11

1

Indenting is correct since you are showing a coding sample. It should be indented and display in a fixed-width font since that is the accepted convention. – the Tin Man Nov 28 '10 at 06:20
Go ahead and accept your answer to this question. That way it will show as having been answered in SO's interface. – the Tin Man Nov 28 '10 at 06:22

score 2 · Answer 2 · answered Sep 13 '15 at 15:43

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]

answered Sep 13 '15 at 15:43

David Runger

765
6
13

score 1 · Answer 3 · answered Aug 03 '12 at 19:26

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 _..._).

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

3 Answers3