1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
|
= Asciidoctor Include Extension
:source-language: shell
// custom
:gem-name: asciidoctor-include-ext
:gh-name: jirutka/{gem-name}
:gh-branch: master
:codacy-id: 45320444129044688ef6553821b083f1
ifdef::env-github[]
image:https://github.com/{gh-name}/workflows/CI/badge.svg[CI Status, link=https://github.com/{gh-name}/actions?query=workflow%3A%22CI%22]
image:https://api.codacy.com/project/badge/Coverage/{codacy-id}["Test Coverage", link="https://www.codacy.com/app/{gh-name}"]
image:https://api.codacy.com/project/badge/Grade/{codacy-id}["Codacy Code quality", link="https://www.codacy.com/app/{gh-name}"]
image:https://img.shields.io/gem/v/{gem-name}.svg?style=flat[Gem Version, link="https://rubygems.org/gems/{gem-name}"]
image:https://img.shields.io/badge/yard-docs-blue.svg[Yard Docs, link="http://www.rubydoc.info/github/{gh-name}/{gh-branch}"]
endif::env-github[]
This project is a reimplementation of the http://asciidoctor.org[Asciidoctor]’s built-in (pre)processor for the http://asciidoctor.org/docs/user-manual/#include-directive[include::[\]] directive in extensible and more clean way.
It provides the same features, but you can easily adjust it or extend for your needs.
For example, you can change how it loads included files or add another ways how to select portions of the document to include.
== Why?
You may ask why I _reimplemented_ something that is already in the Asciidoctor core.
Well…
Code for decision if the include is allowed, parsing attributes for partial selection, reading the file to be included, filtering its content according to `lines` or `tags` attribute, handling errors… all of this is implemented directly in a single 210 lines long method https://github.com/asciidoctor/asciidoctor/blob/911d0bd509f369e9da15d2bb71f81aecb7c45fec/lib/asciidoctor/reader.rb#L824-L1034[Asciidoctor::Reader#preprocess_include_directive] with really horrible perl-like spaghetti code. :spaghetti: :hankey:
How can you adjust it or reuse outside of the Asciidoctor codebase?
For example, what if you can’t read documents directly from file system?
Then you’re out of luck.
There’s no way how to do that without reimplementing this whole mess on your own (monkey-patching `Kernel.open` and `File.file?` is not a sensible option…).
I wrote this extension to allow implementing a complete support of `include::[]` directive in GitLab.
And also to open doors for adding some custom _selectors_, e.g. selecting lines using regular expression in addition to ranges of line numbers and tags.
== Installation
To install (or update to the latest version):
[source, subs="+attributes"]
gem install {gem-name}
or to install the latest development version:
[source, subs="+attributes"]
gem install {gem-name} --pre
WARNING: Versions *prior 0.4.0* are vulnerable for Command Injection (see https://github.com/{gh-name}/commit/c7ea001a597c7033575342c51483dab7b87ae155[c7ea001] for more information). If you use an older version, update to 0.4.0 immediately!
== Usage
Just `require '{gem-name}'`.
If you invoke Asciidoctor from command-line, use option `-r` to load the extension:
[source, subs="+attributes"]
asciidoctor -r {gem-name} README.adoc
If you don’t want the extension to be automatically registered in Asciidoctor, don’t _require_ `{gem-name}`, but `asciidoctor/include_ext/include_processor`.
IMPORTANT: Bundler automatically _requires_ all the specified gems.
To prevent it, use `gem '{gem-name}', require: false`.
== License
This project is licensed under http://opensource.org/licenses/MIT/[MIT License].
For the full text of the license, see the link:LICENSE[LICENSE] file.
|
