👨💻 about me home CV/Resume 🖊️ Contact Github LinkedIn I’m a Haskeller 📝 Blog Freedom, privacy, tutorials… 🏆 Best of panda upp Haskell abp pp hCalc bl lapp todo pwd TPG Nextcloud Git BitTorrent
15 Mai 2020
archive: {{name}}-{{version}}.tar.gz
ABP is a Pandoc filter that works on internal Pandoc’s AST.
It provides several interesting features:
Their is no plan to support ABP from now on. ABP is meant to be replaced by a combination of:
Upp and Panda are written in Lua and are way easier to deploy.
ABP is an Open source software. Anybody can contribute on GitHub to:
stack init && stack install
.stack install pandoc
if you need to install Pandoc.This will install abp
and pandoc
in
~/.local/bin
.
ABP is written in Haskell and is built with Stack.
abp
is a Pandoc
filter and is not meant to be called directly.
$ pandoc -F abp ...
A complete example is given as a Makefile in the doc directory.
Syntactic item | Class | Attributes | Description |
---|---|---|---|
any string | {{var}} is replaced by the
value of var if it is defined (variables can be environment
variables or YAML definitions) |
||
div block | comment |
commented block | |
div block | include=file |
replaces the div block with the content of
file (rendered according to its format) |
|
div block | shift=n |
adds n to header levels in an
imported div block |
|
any block | raw |
strings are not expanded in this block | |
code block | meta |
definitions for the string expansion (YAML subset), defined in the code block | |
code block | meta=file |
definitions for the string expansion (YAML
subset), defined in file |
|
any block | ifdef=name |
block emitted only if name is
defined |
|
any block | ifdef=name value=val |
block emitted only if name is
defined and its value is value |
|
any block | ifndef=name |
block emitted only if name is
not defined |
|
code block, inline code | include=file |
replaces the code block content with the
content of file |
|
code block, inline code | fromline=n |
includes a file from line number
n |
|
code block, inline code | toline=n |
includes a file up to line number
n |
|
code block, inline code | cmd="shell command" |
replaces the code block by the result of the shell command | |
code block | render="command" |
replaces the code block by a link to the
image produced by the command (%i is the input file name,
its content is the content of the code block, %o is the
output file name) |
|
code block | img="image path" |
URL of the image produced by
render |
|
code block | out="image path" |
path of the image produced by
render (optional, the default value is
img ) |
|
CSV tables | table |
see Pandoc csv2table filter |
Div blocks with the comment
class are commented:
::: comment
This block is a comment and is discarded by abp. :::
abp
stores variables in an environment used to expand
strings. Variables can be defined by a YAML file (currently a very
limited subset of YAML) with the meta
class. The
meta
attribute can also be used to point to an external
file. Variables can only contain inline elements, not blocks.
The initial environment contains:
abp
given
by pandoc
)Variable names are enclosed between double curly brackets. E.g. Abstract Processor (for Pandoc)
will be replaced with
the document title.
Elements with the raw
class won’t be expanded. E.g.
`Abstract Processor (for Pandoc)`{.raw}
won’t
be replaced with the document title.
E.g.:
```meta
foo: bar (note: this is parsed as **Markdown**)
```
foo is {{foo}}.
```{meta=foo.yaml}
This text is ignored, definitions are in foo.yaml.
```
`foo.yaml` and is {{foo}}. foo is defined in
Blocks can be conditionally kept or omitted. The condition is described with attributes.
:::{ifdef="name" value="value"}
This block is emitted only if the variable "name" is defined
and its value is "value" :::
:::{ifdef="name"}
This block is emitted only if the variable "name" is defined
(whatever its value) :::
:::{ifndef="name"}
This block is emitted only if the variable "name" is **not** defined :::
Fragments of documents can be imported from external files. The
include
attribute contains the name of the file to include.
The content of the file is parsed according to its format (deduced from
its name) and replaces the div block content.
:::{include=file.md}
This text is optional and will be replaced by the content of file.md. :::
The included file can be in a different format (e.g. a markdown file can include a reStructuredText file).
Code examples can be imported from external files. The
include
attribute contains the name of the file to include.
The content of the file replaces the code block content.
```{.c include=foo.c fromline=3 toline=10}
This text is optional and will be replaced by the content of foo.c.
```
The optional fromline
and toline
defines
the first and last lines to be included.
Scripts can be executed by inline or code blocks. The
cmd
attribute defines the command to execute. The content
of the block is in a temporary file which name is added to the command.
If the command contains the %
char, it is replaced by the
temporary file name. If the command does not contain any %
,
the file name is appended to the command. The result replaces the
content of the code block.
Source | Result |
---|---|
|
|
|
Python says Hello from Python! |
Code blocks containing diagrams are replaced with an image resulting from the diagram source code.
The render command is the render
field. The output image
can be a hash computed from the diagram source code or the value of the
img
field. The optional out
field overloads
img
to change the output directory when rendering the
diagram.
In the render
command, %i
is replaced by
the name of the input document (generated from the content of the code
block) and %o
by the name of the output image file
(generated from the img
field).
The file format (extension) must be in the render
field,
after the %o
tag (e.g.: %o.png
), not in the
img
field.
Source | Result |
---|---|
|
Some render commands are predefined:
Diagram | Predefined variable | Render command |
---|---|---|
GraphViz | dot -Tsvg -o %o.svg %i |
dot -Tsvg -o %o.svg %i |
dot -Tsvg -o %o.svg %i |
dot -Tsvg -o %o.svg %i |
|
dot -Tpng -o %o.png %i |
dot -Tpng -o %o.png %i |
|
dot -Tpdf -o %o.pdf %i |
dot -Tpdf -o %o.pdf %i |
|
PlantUML | java -jar {{PLANTUML}} -pipe -charset UTF-8 -tsvg < %i > %o.svg |
java -jar {{PLANTUML}} -pipe -charset UTF-8 -tsvg < %i > %o.svg |
java -jar {{PLANTUML}} -pipe -charset UTF-8 -tsvg < %i > %o.svg |
java -jar {{PLANTUML}} -pipe -charset UTF-8 -tsvg < %i > %o.svg |
|
java -jar {{PLANTUML}} -pipe -charset UTF-8 -tpng < %i > %o.png |
java -jar {{PLANTUML}} -pipe -charset UTF-8 -tpng < %i > %o.png |
|
java -jar {{PLANTUML}} -pipe -charset UTF-8 -tpdf < %i > %o.pdf |
java -jar {{PLANTUML}} -pipe -charset UTF-8 -tpdf < %i > %o.pdf |
|
Asymptote | asy -f svg -o %o.svg %i |
asy -f svg -o %o.svg %i |
asy -f svg -o %o.svg %i |
asy -f svg -o %o.svg %i |
|
asy -f png -o %o.png %i |
asy -f png -o %o.png %i |
|
asy -f pdf -o %o.pdf %i |
asy -f pdf -o %o.pdf %i |
|
blockdiag | blockdiag -a -Tsvg -o %o.svg %i |
blockdiag -a -Tsvg -o %o.svg %i |
blockdiag -a -Tsvg -o %o.svg %i |
blockdiag -a -Tsvg -o %o.svg %i |
|
blockdiag -a -Tpng -o %o.png %i |
blockdiag -a -Tpng -o %o.png %i |
|
blockdiag -a -Tpdf -o %o.pdf %i |
blockdiag -a -Tpdf -o %o.pdf %i |
|
mermaid | mmdc -i %i -o %o.svg |
mmdc -i %i -o %o.svg |
mmdc -i %i -o %o.svg |
mmdc -i %i -o %o.svg |
|
mmdc -i %i -o %o.png |
mmdc -i %i -o %o.png |
|
mmdc -i %i -o %o.pdf |
mmdc -i %i -o %o.pdf |
|
ditaa | java -jar {{DITAA}} --svg -o -e UTF-8 %i %o.svg |
java -jar {{DITAA}} --svg -o -e UTF-8 %i %o.svg |
java -jar {{DITAA}} --svg -o -e UTF-8 %i %o.svg |
java -jar {{DITAA}} --svg -o -e UTF-8 %i %o.svg |
|
java -jar {{DITAA}} -o -e UTF-8 %i %o.png |
java -jar {{DITAA}} -o -e UTF-8 %i %o.png |
|
gnuplot | gnuplot -e 'set terminal svg' -e 'set output "%o.svg"' -c %i |
gnuplot -e 'set terminal svg' -e 'set output "%o.svg"' -c %i |
gnuplot -e 'set terminal svg' -e 'set output "%o.svg"' -c %i |
gnuplot -e 'set terminal svg' -e 'set output "%o.svg"' -c %i |
|
gnuplot -e 'set terminal png' -e 'set output "%o.png"' -c %i |
gnuplot -e 'set terminal png' -e 'set output "%o.png"' -c %i |
Notes:
dot
: GraphViz
support also includes dot
, neato
,
twopi
, circo
, fdp
,
sfdp
, patchwork
and
osage
.
plantuml
: {{PLANTUML}}
can
be defined as an environment variable. Its default value is the
directory of the abp
executable appended with
"plantuml.jar"
.
ditaa
: {{DITAA}}
can be
defined as an environment variable. Its default value is the directory
of the abp
executable appended with
"ditaa.jar"
.
blockdiag
: Blockdiag support also includes
actdiag
, blockdiag
, nwdiag
,
packetdiag
, rackdiag
and
seqdiag
.
renderers without an explicit image format are built differently according to the output document format.
img
fieldE.g.:
Source | Result |
---|---|
|
|
|
Filters can be combined. E.g.: a diagram can be stored in an external
file, included and rendered by abp
.
Source | Result |
---|---|
|
The file
|
|
and is rendered as: |
CSV tables are rendered using the Pandoc csv2table filter. The filter has been included to ABP without any modification.
The table content can be defined in the code block or in an external file.
Source | Result |
---|---|
|
|
It is sometimes useful to build a dependency list on the fly.
abp
can generate a dependency list for make, in the same
vein than the gcc -M
option. The environment variable
ABP_TARGET
must be defined with the target name.
abp
will generate a file named ${ABP_TARGET}.d
containing the dependencies of ${ABP_TARGET}
.
E.g.:
ABP_TARGET=index.html pandoc -F ABP index.md -o index.html
This will produce a file named index.html.d
containing
index.html: ...
.
ABP is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
ABP is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with ABP. If not, see <https://www.gnu.org/licenses/>.
For further information about ABP you can visit
http://cdelord.fr/abp
Some portions of code are based on PP released under the GPL license version 3.
Pandoc csv2table filter is written by Wasif Hasan Baig and has been released under the MIT license.
Your feedback and contributions are welcome. You can contact me at cdelord.fr.