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..:)
Related
I have a couple of examples (all with titles) and I'd like to create an index/list out of them automatically.
An example can be seen in the chunked AsciiDoc User Guide table of contents (or beneath):
The asciidoc source of the AsciiDoc User Guide does not show anything specific to me for Asciidoc itself, I could find the following hint to Docbook:
DocBook toolchains will normally automatically number examples and generate a 'List of Examples' backmatter section.
I'm looking for the (asciidoctor?) standard html5 rendering, but I'm open for different suggestions.
Adding the :doctype: book attribute alone does not do it. So I merely hit dead ends not knowing if it is possible at all. Also I'm new to Asciidoc so I might just miss some pointers, too.
The Python Asciidoc repo includes the a2x tool, which is a wrapper around a DocBook toolchain. It is DocBook that is producing these entries in the table of contents. Neither Python Asciidoc, nor asciidoctor, can do this out of the box.
You would need to curate the lists manually, or create a macro that does the curation for you. This thread might prove helpful: https://github.com/asciidoctor/asciidoctor-extensions-lab/issues/111
Is there a way I can rename or alias latexmath in an AsciiDoc document?
In an ideal world, I'd like to set up an AsciiDoc such that $...$ is interpreted as LaTeX math, and
$$...$$ is interpreted as a block equation. In general, I'm just trying to reduce the number of characters involved in defining a math block since
where $c$ is the speed of light and $m_0$ is the rest mass
is significantly more readable (to someone who's used LaTeX for years) than
where latexmath:[$c$] is the speed of light and latexmath:[$m_0$] is the rest mass
The use case I have is that I'm writing technical documentation for upload to a GitLab repository. I'd like to be able to exploit GitLab's ability to automatically render AsciiDoc format files. However, these documents are math heavy, so I find the large numbers of latexmath:[...] blocks hard to read while editing.
latexmath is the name of the macro that handles parsing the LaTeX markup. If you don't specify latexmath, asciidoctor doesn't know to pass control to an alternate parser.
You could achieve what you're after by writing a pre-processing step that identifies contiguous blocks of LaTeX markup and wraps that markup in latexmath:[...]. The updated markup can then be processed by Asciidoctor like normal (assuming that your LaTeX markup identification is accurate). How you go about implementing that is up to you.
Another way, assuming you have some Ruby skills, would be to modify the extension that implements the latexmath macro such that it was called, say, L. Then your markup would be the more concise:
where L:[$c$] is the speed of light and L:[$m_0$] is the rest mass
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]
I have an application that needs to parse a subset of Markdown. I basically only want to support inline elements (bold, italic, links, etc), not block level elements (p, h1, h2, etc).
There are a lot of different libraries, so I need some help narrowing it down (and a code sample would be helpful). I started using RedCarpet until I realized that I can't specify which elements I want to parse.
What Ruby Markdown library can I use to achieve this?
I haven't found a library that allows you to specify on a granular level what parts of Markdown syntax are allowed. RDiscount has some configurability, however it doesn't take into account block level elements.
You could also give Sanitize a try (I know, parsing twice isn't exactly an ideal solution) and strip out the elements you don't want afterward.
I am using git-wiki for my personal note storage. It works very well, except that WikiWords are converted to links before the markdown parsing stage, using a regular expression. This messes up scores of things, for instance links that point to outside wiki pages, or block quotes (if I am quoting something, I do not want a WikiWord to be changed into a link).
Are there ruby-based Markdown parsers that understand WikiLinks?
The best parser around is the C-based one (upskirt/sundown), whose ruby iteration is red carpet:
https://github.com/tanoku/redcarpet
It is better for performance and security reasons.
For the wiki links, pre-process them before sending your text to the markdown parser.