I have a document with many similar tables. I thought it is possible to set this table cols and header as attribute
:table-params: width="100%",cols="12%,21%,67%",options="header"
:table-header: |this |is |header
.table
[{table-params}]
|====
{table-header}
but its get en error: table missing leading separator. Looks like asciidoc can't post-render attribute values. pass macro also didn't help
I found a solution with include macro with tag
.table-1
|====
// tag::table-header[]
|this |is |header
// end::table-header[]
.table-2
|====
include::example.adoc[tag=table-header]
Maybe I have missed something. What is a most elegant way to reuse marked-up parts across document?
Attributes effectively define string values that can be re-used throughout a document's content. However, a table's attribute definition requires a list of arguments, not a string that looks like a list of arguments.
The most elegant re-use for markup is the include:: macro, which operates as if it injects the specified content at the location of the include:: macro.
See the docs for more details: https://docs.asciidoctor.org/asciidoc/latest/directives/include/
To avoid repetition, I would use the Jamal preprocessor.
https://github.com/verhas/jamal/
Jamal is a free, Apache v2.0 licensed tool that I wrote in the past few years to solve precisely the types of problems like yours.
With Jamal, you can define macros and use them in the code afterward, like:
{%#define tableParams= width="100%",cols="12%,21%,67%",options="header"%}
{%#define tableHeader=|this |is |header%}
.table
[{%tableParams%}]
|====
{%tableHeader%}
which will look in IntelliJ like the following:
Related
I'm rather new to Sphinx and ReST and I've "inherited" a big project.
The documentation consists of hundreds of pages with how to's, etc. There are several files (one for each class) where the respective functions are described using the ".. py:function::" directive.
So each of these pages is basically like this:
Some description text explaining the class
py:function:: class.myFunction(param1, param2)
parameter description
code example, ...
py:function:: class.myFunction2
parameter description
code example, ...
Now, I'd like to list all functions of all different pages in one single XML file, if possible grouped by their class, but without the descriptions and examples. Is this possible with some built-in Sphinx parser or do I have to write my own? Or is there any other directive or config option that may be helpful?
The XML file should be like this:
<class1>
<function1>
<param1>
<param2>
...
<function2>
...
<class2>
<function1>
...
I found ViewLists and the Parsing directive in the Sphinx documentation but i'm not sure how to correctly use them and if that's the solution to my problem.
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.
In markdown I can write:
[example1][myid]
[example2][myid]
[myid]: http://example.com
so I don't have to retype the full external link multiple times.
Is there an analogous feature in AsciiDoc? Specially interested in the Asciidoctor implementation.
So far I could only find:
internal cross references with <<>>
I think I saw a replacement feature of type :myid:, but I can't find it anymore. And I didn't see how to use different texts for each link however.
Probably you mean something like this:
Userguide Chapter 28.1. Setting configuration entries
...
Attribute entries promote clarity and eliminate repetition
URLs and file names in AsciiDoc3 macros are often quite long — they break paragraph flow and readability suffers. The problem is compounded by redundancy if the same name is used repeatedly. Attribute entries can be used to make your documents easier to read and write, here are some examples:
:1: http://freshmeat.net/projects/asciidoc3/
:homepage: http://asciidoc3.org[AsciiDoc3 home page]
:new: image:./images/smallnew.png[]
:footnote1: footnote:[A meaningless latin term]
Using previously defined attributes: See the {1}[Freshmeat summary]
or the {homepage} for something new {new}. Lorem ispum {footnote1}.
...
BTW, there is a 100% Python3 port available now: https://asciidoc3.org
I think you are looking for this (and both will work just fine),
https://www.google.com[Google]
or
link: https://google.com[Google]
Reference:
Ascii Doc User Manual Link
Update #1: Use of link along with variables in asciidoc
Declare variable
:url: https://www.google.com
Use variable feature using format mentioned above
Using ' Link with label '
{url}[Google]
Using a relative link
link:{url}[Google]
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]
In Sphinx, is it possible to automatically define labels for headings? I've found that my documents end up looking a lot like this:
.._doing stuff:
Doing Stuff
-----------
You might also want :ref:`other stuff`.
.._other stuff:
Other Stuff
-----------
No, you want :ref:`doing stuff`.
And it would be nice to remove that duplication.
Within same document, you can always use the traditional reference:
Doing Stuff
-----------
You may want to try `Doing Stuff`_ -section again.
But as mentioned, this method does not work across the document files.
Sphinx 1.4 added sphinx.ext.autosectionlabel which supports this. It includes an option that will prefix the document name to the label to avoid cross-document clashes.