How to force verbatim mode for file inclusion in rdoc

Question

I need to include an example program in my rdoc. The example program also needs to be executable so that a user can just run the example from the command line.

I want to show the source code of the program exactly as written in my rdoc formatted documentation.

From what I can see, the only way to trigger verbatim mode is to increase the indent level.

So, how can I get my file to 'include' the example program but not mark it up in any way?

I tried this:

# :include:example_program.rb

But it processes the contents of example_program.rb as non-verbatim until it reaches the first indented code block.

Then, it treats the body of that block as verbatim, then when the block ends, goes back to interpreting markup.

I want it to not interpret any markup for the entire duration of the included file.

Is there some other way of delineating a verbatim section than with indentation?

Answer 1

I figured it out.

I needed to indent the include directive itself:

#!/usr/bin/env ruby
#   :incude:sample_program.rb
# Other commentary that I wish to be marked up by rdoc.

I had been assuming that an include directive in a verbatim block would itself be output verbatim.

Apparently, if the verbatim block consists of only an include directive, it is processed as exactly the solution to my problem.