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:
Related
I have done some experiments with writing programs that are also at the same time valid documentation that can be rendered as README's by e.g. Github - this ensures that code snippets are up to date and valid - and had some very interesting findings with Markdown. Unfortunately that format does not support having an automatically generated table of contents, so we looked into AsciiDoc which does.
I managed to copy an example using :toc: macro (to be able to place it after the opening summary), and then went on to make it valid Java, which essentially mean that you have to start the file with the /* characters but then I cannot make the table of contents appear any more.
The snippet starts with:
= Asciidoctor PDF Theming Guide
Dan Allen <https://github.com/mojavelinux[#mojavelinux]>
// Settings:
:idprefix:
:idseparator: -
:toc: macro
:experimental:
ifndef::env-github[:icons: font]
ifdef::env-github[]
:outfilesuffix: .adoc
:!toc-title:
:caution-caption: :fire:
:important-caption: :exclamation:
:note-caption: :paperclip:
:tip-caption: :bulb:
:warning-caption: :warning:
endif::[]
:window: _blank
// Aliases:
:conum-guard-yaml: #
ifndef::icons[:conum-guard-yaml: # #]
ifdef::backend-pdf[:conum-guard-yaml: # #]
:url-fontforge: https://fontforge.github.io/en-US/
:url-fontforge-scripting: https://fontforge.github.io/en-US/documentation/scripting/
:url-prawn: http://prawnpdf.org
////
Topics remaining to document:
* line height and line height length (and what that all means)
* title page layout / title page images (logo & background)
////
[.lead]
The theming system in Asciidoctor PDF is used to control the layout and styling of the PDF file
... blurb removed ...
/* (Experiment with asciidoc)
= Dagger 2 Hello World
// (Important: As an experiment Main.java is also a valid markdown file copied unmodified to README.md, so only edit Main.java)
This project is a single file Hello World Dagger-2 Maven project for
Java 8 and later, while also being its own documentation written in AsciiDoc.
toc::[]
My gut feeling is that the TOC does only work as expected if the file starts with lines parsed by AsciiDoc where this is set up and configured. If any output is generated before the configuration bits (like the Java comment) then the TOC is silently empty.
Hence I would like to know how I should do this correctly. All I want is a functional toc::[] macro in a file starting with /*
Asciidoc markup files are not Java source files. While I understand that this would be a compelling combination of the formats, that capability does not exist.
To keep source files up-to-date, your Asciidoc source files can use the include directive to include a source file. See: https://asciidoctor.org/docs/user-manual/#include-directive
To include, say, a single method, you can use tags to mark the start and end of the method's implementation, and then you can include that tag-delimited code section like this:
[source,java]
----
include::path/to/source.java[tag="method-x"]
----
Note that if the path to the Java source that you want to include is outside of the current directory, you may have to change the safe mode accordingly: https://asciidoctor.org/docs/user-manual/#running-asciidoctor-securely
In our read the docs project we have a use case where we need to show some specific docs on multiple pages in the same version of docs. As of now, we do this either by one of the following ways
Copy-pasting the content to each page's rst file
Write it in one of the concerned files with a label and use :std:ref: in rest of the files to redirect it to the main file
I would want to achieve something like writing content only in one file and then showing it (without any redirection for user) in each of the files. Is it possible?
Use the include directive in the parent file.
.. include:: includeme.rst
Note that the included file will be interpreted in the context of the parent file. Therefore section levels (headings) in the included file must be consistent with the parent file, and labels in the included file might generate duplicate warnings.
You can use for this purpose the include directive.
Say that you write the text in dir/text.rst.
The following will include in other documents:
..include :: /dir/text.rst
where the path is either relative (then, with no slash) or absolute which is possible in sphinx (doc)
in Sphinx, when given an absolute include file path, this directive
takes it as relative to the source directory
Is there a way to include plain text in a doxygen file
Hello Wold
----------
#include helloworld.txt
without it ending up in a fragment like:
I dont want this
I wanted it to end up like the other text I write in a .markdown file:
I want this
I'm sorry to say I don't think there's an easy way to do this as of May 2016 - what you really need is a mdinclude command to match htmlinclude.
The problem is that Markdown is processed as a pre-processing step and the output from that then run through the normal Doxygen processing detecting generated HTML and special commands.
So, unless you want to make a submission to Doxygen, the only way I can think of is to do your own pre-processing for this particular include.
You could do that in a build step where you use some Unix commands or a script to merge in a file at the include stage.
If you wanted this driven by Doxygen you could use a custom file extension and write your own filter, as described in this SO answer
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.
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