asciidoctor-foodogsquared-e.../lib/asciidoctor/swhid-include-processor/README.adoc

= SWHID include processor
:toc:


This is an include processor extension for easily fetching SWHIDs, only with the `cnt` schema type.


== Synopsis

[source, asciidoc]
----
\include::$SWHID[]
----

Where `$SWHID` is a link:https://docs.softwareheritage.org/devel/swh-model/persistent-identifiers.html[SWHID].
This could accept SWHIDs with qualifiers.

Take note this include processor will only give the raw content with the `cnt` schema type.
Anything else will be skipped and log a warning instead.


== Extra notes

[source, asciidoc]
----
= doctitle
:swhid-gpl3: swh:1:cnt:94a9ed024d3859793618152ea559a168bbcbb5e2

\include::{swhid-nixpkgs}[]
----

This include processor also respects the safe mode setting.
This means in order to permit including by SWHID, you have to permit link:https://docs.asciidoctor.org/asciidoc/latest/directives/include-uri/[includes by URIs].

Lastly, this include processor uses the Software Heritage API which includes a limitation.
You could create authorized requests by setting `SWH_API_BEARER_TOKEN` environment variable with a token.


== Example usage

- SWHID with a bare core identifier: `include::swh:1:cnt:94a9ed024d3859793618152ea559a168bbcbb5e2[]`.

- SWHID with full contextual information: `include::swh:1:cnt:4c6ad635164b25b9bc2ebe17d2c3b7c0835f6035;origin=https://github.com/NixOS/nixpkgs;visit=swh:1:snp:6ea7d28dfd4789609e0be2b64179fc9c12931beb;anchor=swh:1:rev:7f5639fa3b68054ca0b062866dc62b22c3f11505;path=/README.md`.
Add SWHID include processor 2023-03-11 08:34:12 +00:00			`= SWHID include processor`
			`:toc:`


			This is an include processor extension for easily fetching SWHIDs, only with the `cnt` schema type.


			`== Synopsis`

			`[source, asciidoc]`
			`----`
			`\include::$SWHID[]`
			`----`

			Where `$SWHID` is a link:https://docs.softwareheritage.org/devel/swh-model/persistent-identifiers.html[SWHID].
			`This could accept SWHIDs with qualifiers.`

			Take note this include processor will only give the raw content with the `cnt` schema type.
			`Anything else will be skipped and log a warning instead.`



			`== Extra notes`

			`[source, asciidoc]`
			`----`
			`= doctitle`
			`:swhid-gpl3: swh:1:cnt:94a9ed024d3859793618152ea559a168bbcbb5e2`

			`\include::{swhid-nixpkgs}[]`
			`----`

			`This include processor also respects the safe mode setting.`
			`This means in order to permit including by SWHID, you have to permit link:https://docs.asciidoctor.org/asciidoc/latest/directives/include-uri/[includes by URIs].`

			`Lastly, this include processor uses the Software Heritage API which includes a limitation.`
Revise notes for custom Asciidoctor extensions 2023-03-12 02:07:38 +00:00			You could create authorized requests by setting `SWH_API_BEARER_TOKEN` environment variable with a token.
Add SWHID include processor 2023-03-11 08:34:12 +00:00

			`== Example usage`

			- SWHID with a bare core identifier: `include::swh:1:cnt:94a9ed024d3859793618152ea559a168bbcbb5e2[]`.

			- SWHID with full contextual information: `include::swh:1:cnt:4c6ad635164b25b9bc2ebe17d2c3b7c0835f6035;origin=https://github.com/NixOS/nixpkgs;visit=swh:1:snp:6ea7d28dfd4789609e0be2b64179fc9c12931beb;anchor=swh:1:rev:7f5639fa3b68054ca0b062866dc62b22c3f11505;path=/README.md`.