I'm trying to create a simple macro to render a text item in red in asciidoctor.
The following does not work:
:redtext: [red]#some important text in red that occurs a lot#
{redtext}
or for an even simpler example:
:redcross: [red]#✘#
I am not clear on the rules for what can and cannot be substituted by a macro. The asciidoctor manual has a blank space for macros at present (http://asciidoctor.org/docs/user-manual/#macros). The asciidoc manual (http://www.methods.co.nz/asciidoc/chunked/ch21.html) isn't that clear either but may not apply to asciidoctor anyway.
A related unanswered question is Resuable markup fragments with Asciidoctor.
A related question to that suggests using includes which is overkill for this.
What are the limitations of macros?
What you have defined is not a macro, it's an attribute. (When you use it, it's called an attribute reference).
You can perform substitution eagerly in the definition of an attribute using the inline pass macro. In the target position, it accepts a comma-separated list of substitution names (or substitution letters).
In your case, you can write:
:redtext: pass:q[[red]#some important text in red that occurs a lot#]
The relevant part is:
pass:q[...]
See substitutions in an attribute entry for details.
I think includes work well enough. We have a single glossary.asciidoc file to contain all the re-usable snippets, for example:
tag::redtext[]
[red]#some important text in red that occurs a lot#
end::redtext[]
In index.asciidoc you can add a little helper:
:g: glossary.asciidoc
Then wherever you need this snippet:
include::{g}[tag=redtext]
Related
For example, when the goal is to represent several lines of a program's source code, then the AsciiDoc block markup choices are using
a literal block (....), which is converted to the literallayout DocBook tag
a listing block (----), which is converted to the screen DocBook tag
These are solid defaults, but the proper semantic markup would be programlisting in this case.
Using passthrough blocks is one solution, but at the cost of polymorphism (or convenience, if I decide to pepper my documents with ifdefs / ifndefs):
WARNING
Using passthroughs to pass content (without substitutions) can couple your content to a specific output format, such as HTML. In these cases, you should use conditional preprocessor directives to route passthrough content for different output formats based on the current backend.
I don't mind using the conditionals, but simply wondering if I am missing something obvious or straightforward? Such as passing semantic tag names to a block attrlist or something. Read through the entire AsciiDoc manual, the asciidoctor man page, the Generate DocBook from AsciiDoc article, and tried keyword searches, but couldn't find a thing. (It is highly probably though that I missed it..:)
Prefixing the link with an ! suppresses the creation of a reference (e.g. :ref:`!no link` will be simply rendered as no link):
If you prefix the content with !, no reference/hyperlink will be created.
However, I can't think of any practical usage of this. Why should I first create a reference and then don't want to use it - it would be far easier to write plain text from the very beginning.
So - what is a typical use case of such a suppressed reference?
(Sphinx itself for instance doesn't use it in its docs.)
I can't think of any practical usage of this.
The use I can think of is before a build if you wanted to "turn of" hyperlink generation for one given cross-reference (that appears multiple times) how would you do it?
Well, the simplest way might be using some text editor's "find and replace", and arguably the least invasive way would be to add or remove a single character !. That way the length and structure of the cross-reference is kept in the source (and the title is still rendered in place). This could be convenient in several places, like a table where removing the whole cross-reference could misalign the source.
The most economical change possible would be turning this:
:ref:`a very long title <an.extremely.long.link.target>`
into this:
:ref:`!a very long title <an.extremely.long.link.target>`
The same could possibly be achieved programmatically using the Sphinx API, but a lot of Sphinx users are likely to prefer a text editing solution over a programmatic one.
I see a lot of examples like
:ref:`code <target to code>`
in the Sphinx documentation, but I can't find where it defines what code and <target to code> mean. Perhaps one of them is an implicit or explicit target and the other is the path to a file??
If someone can give me examples of how to cross reference a title in a specific .rst file?
From Adding a cross-reference to a subheading or anchor in another page I know how to use the :any role, but not how to do a :ref: to a specific file.
From the documentation for Cross-referencing syntax:
Cross-references are generated by many semantic interpreted text roles. Basically, you only need to write
:role:`target`
and a link will be created to the item named target of the type indicated by role. The link’s text will be the same as target.
There are some additional facilities, however, that make cross-referencing roles more versatile:
You may supply an explicit title and reference target, like in reST direct hyperlinks:
:role:`title <target>`
will refer to target, but the link text will be title.
Note that sometimes title is also called label, depending on context.
Is it possible to get Sphinx to generate the index based on existing labels and :ref: in the text? Say if you have a label:
.. _my_label:
My Section
and later refer to it through multiple :ref:`my_label` , is there a way to get the equivalent of an automatic generation of:
.. index:: My Section
where the label is, and the same before the paragraph where the :ref: lives?
The official doc does not list labels or :ref: as index-generating markup and I could not find any extension doing it. But maybe there is one?
There's an official list of Sphinx extensions, and there are a few lists of unoffical extensions on Github but none of them implement the functionality specified in the question.
The closest approach to the problem specified in the question would be using autosectionlabel to automatically create a target label having the section name, and place an :index: or .. index:: adjacent to the reST section to place it in the index. However, this would only save having to declare the label, declaring the index entry would still be necessary.
The functionality (directive) you ask for provides little tangible gain beyond writing one less line or block of reST code (the .. index:: directive or :index: role), be it for sections or targets.
Sphinx being open source would allow implementing a custom directive for this, however using a non-standard directive having as only aim shortening standard syntax by a single construct would stand to create more difficulty than gain for readers of your source code.
Is there a way to create links or anchors within SPSS syntax? Something like linking to a bookmark.
I am making changes and additions to a syntax file, and document these changes at the bottom of the file as comments. In these comments I would like to link to the part of the syntax that was changed. Now I just write the line number, but that changes as I add more syntax, so the reference becomes incorrect.
Bookmarks were the closest thing I found to what I want to do, but I can't turn them into a link. Moreover, I can only create a maximum of 9 bookmarks, which is not enough.
Trying to think creatively here:
instead of bookmarking all the changes, you could break up your syntax into many small syntaxes - each of which contains one of the parts where a change was made.
you can name and number the small syntaxes accordingly.
Then you create one syntax which contains a series of INSERT commands, which calls each of the small syntaxes in turn. You can add titles and remarks between the insert commands, so other users can follow the process and study the relevant small syntax that they need separately.
The Statistics Syntax Editor supports bookmarks - you can have up to 10. Generate a few in the SE and save the syntax file to see how these are represented (hint: look at the COMMENT BOOKMARK lines.