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?
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.
Related
Context
I am making a script that dynamically inserts include directives in code blocks on an AsciiDoc file and then generates a PDF out of that. A generated AsciiDoc file could look like this:
= Title
[source,java]
---
include::foo.java[]
---
I want the user to be free to include whatever char-based file he or she wants, even other AsciiDoc files.
Problems
My goal is to show the contents as are of these included files. I run into problems when the included file:
is recognized as AsciiDoc beacuse of its extension, an thus any include directives it has are interpreted. I don't want nested includes, just to show the include directive in the code block. Example of undesired behaviour:
contains the code block delimiter ----, as seen on the image above when I end up with two code blocks instead of the intended single one. In this case, it does not matter if the file is recognized as an AsciiDoc file, the problem persists.
My workaround
The script I am writing uses AsciidoctorJ and I am leveraging that I can control how the content of each file is included by using an include processor. Using the include processor I wrap each line of each file with the pass:[] macro. Additionally, I activate macro substitution on the desired code block. A demonstration of this idea is shown in the image above.
Is there a better way to show the exact contents of a file? This works, but it seems like a hack. I would much rather prefer not having to change the read lines as I am currently doing.
EDIT for futher information
I would like to:
not have to escape the block delimiter. I am not exclusively referring to ----, but whatever the delimiter happens to be. For example, the answer by cirrus still has the problem when a line of the included file has .....
not have to escape the include directives in files recognized as AsciiDoc.
In a general note, I don't want to escape (or modify in any way) any lines.
Problem I found with my workaround:
If the last char of a line is a backslash (\), it escapes the closing bracket of the pass:[] macro.
You can try using a literal block. Based on your above example:
a.adoc:
= Title
....
include::c.adoc[]
....
If you use include:: in c.adoc, asciidoctor will still try to find and include the file. As such you will need to replace include:: with \include::
c.adoc:
\include::foo.txt[]
----
----
Which should output the following pdf:
I would like to write a simple download helper script in Ruby.
Download URLs take place in a text file, line by line.
My program should take them one by one, download the referenced file, and then mark the already processed line with some symbol, such as #.
Further problem is that the text file containing the URLs can grow while being processed, because sometimes I would like to add new URLs at the end of the text file, meanwhile it is being processed by the program.
I found this gem, called FileQueue: https://github.com/pezra/filequeue which do something similar: it takes out always the first line, and can push a line at the end of the file, however it removes the already processed lines, and that is a problem, because sometimes I need the URLs after they have been downloaded.
How can I achieve this in clever Ruby way, or maybe does Ruby have a built-in method for this?
I'm trying to represent a short inline span of code with a significant space or two at the end, using Markdown. If I were to put it in a stand-alone code block, it might look like this:
cd
Frustratingly, Markdown transforms `cd ` into <code>cd</code>, deleting the space at the end. How can I do it?
Unfortunately, I'm not aware of a way to do this with backticks in vanilla Markdown. If you need to use your current parser, you can use literal <code> HTML tags to generate correct output:
Normal text. <code>Inline code block with a space: </code> Normal text.
If you're able and interested, switching to a more consistent/expanded parser (such as kramdown, which I've tested, but potentially also MultiMarkdown and others) correctly interprets terminal spaces in code blocks and doesn't truncate them.
I don't believe markdown has anything for that specifically but if you use it will add a non breaking space. In your case replace
`cd `
with
`cd `
and it should work as intended.
I am using Sphinx/reStructuredText to create HTML and PDF docs for a project and am including the output of the argparse help for the command line tools. At the moment I am pasting the output in manually but plan at some point to switch to autogenerated output.
The problem is that while the formatting is fine for named parameters (like -x or --xray) it doesn't work well on positional parameters. It looks like the absence of a leading '-' on the parameter name is confusing it. The output looks like normal text without the neat indentation etc.
So my question is, does there exist markup that would force formatting the positional parameters as if they had leading '-' characters? If not, could someone suggest where in the docs or code I should start looking to put something together myself?
You may use sphinx-argparse extension.
It does not use output of argparse help, but it instead introspects argparse parser itself and provides proper sphinx markup for both positional arguments and options, formatting them as definition list with proper labels.
Sub-commands are also easily handled.
http://sphinx-argparse.readthedocs.org/en/latest/
It will also cover you needs in:
plan at some point to switch to autogenerated output
LaTeX has %, html has <\!-- to denote that a comment folows.
Does textile have anyway of commenting out text? I couldn't find one, and it seems like it would be a nice feature to have.
Not really. It seems you can do a single line HTML escape sequence containing an HTML comment which is passed through. But you probably want something more like the C Preprocessor comments that are simply stripped out completely?
==<!-- html comment -->==
Or you could do this, which outputs a multiline html comment, but I doubt it's what you want either:
notextile. <!-- test
test
test
-->
The TextPattern version of Textile does support comments.
The syntax is to have a line beginning with three hashes and one or two full stops.
###. This line will be treated as a comment.
So will this.
This line will be displayed.
###.. Blank lines are allowed in comments if you use two full stops.
This line is also a comment.
p. Starting a new block will end the comment.
Currently, the RedCloth and Mylyn implementations of Textile do not support these comments.