mirror of
https://github.com/foo-dogsquared/asciidoctor-foodogsquared-extensions.git
synced 2025-01-30 22:57:56 +00:00
Restructure modules again
This commit is contained in:
parent
fdcdeb1747
commit
95e7bc12ec
@ -1,115 +0,0 @@
|
||||
= Chat block processor
|
||||
:toc:
|
||||
|
||||
|
||||
A link:https://docs.asciidoctor.org/asciidoctor/latest/extensions/block-processor/[block processor] that adds a a dialog box style to the block.
|
||||
Exclusive to the HTML backend.
|
||||
|
||||
|
||||
== Synopsis
|
||||
|
||||
....
|
||||
[chat, $AVATARNAME, $AVATARSTATE, $ATTRS...]
|
||||
====
|
||||
$CONTENT
|
||||
====
|
||||
....
|
||||
|
||||
The avatar name is the name of the folder to be retrieved from the `avatarsdir` attribute.
|
||||
The directory enforces a certain structure which can be seen in <<extra-notes>>.
|
||||
|
||||
Both the avatar name and the state are to be converted to snake case (e.g., `El Pablo` to `el_pablo`) for the image path.
|
||||
|
||||
|
||||
== Attributes
|
||||
|
||||
* `avatarsdir` is the folder containing the avatars' stickers.
|
||||
This is explained in detail from the <<extra-notes>> section.
|
||||
|
||||
* `avatarstype` is similar to `icontype` attribute except this is used for the avatar stickers.
|
||||
The default value is `webp`.
|
||||
|
||||
* `state` is the sticker to be retrieved from the avatars directory.
|
||||
It has a default value of `default`.
|
||||
You could also use this attribute instead of the `$AVATARSTATE` positional argument for whatever reason.
|
||||
|
||||
* `name` is the canonical name of the avatar.
|
||||
This is used for titles and alts in the internal image block.
|
||||
By default, this is the same as the given avatar.
|
||||
|
||||
|
||||
[#extra-notes]
|
||||
== Extra notes
|
||||
|
||||
This component has some prerequisites for this to fully work specifically with `avatarsdir` attribute that contains a list of avatars and their stickers.
|
||||
By default, this value is at the `avatars` subdirectory of the `iconsdir` attribute.
|
||||
It is recommended to set this value yourself.
|
||||
+
|
||||
--
|
||||
This enforces a certain structure where the root directory contains a list of folders representing the avatar with each of the folder containing stickers which represents their state.
|
||||
For example, here's what `avatarsdir` could contain following the expected structure.
|
||||
|
||||
[source]
|
||||
----
|
||||
./static/icons/avatars/
|
||||
├── ezran/
|
||||
│ ├── crisis.webp
|
||||
│ ├── default.webp
|
||||
│ ├── sad.webp
|
||||
│ └── shocked.webp
|
||||
└── foodogsquared/
|
||||
├── crisis.webp
|
||||
├── default.webp
|
||||
├── sad.webp
|
||||
└── shocked.webp
|
||||
----
|
||||
--
|
||||
|
||||
|
||||
== Example usage
|
||||
|
||||
Let's assume `avatarsdir` is set to the `static/icons/avatars` with the following file structure.
|
||||
|
||||
[source]
|
||||
----
|
||||
./static/icons/avatars/
|
||||
├── ezran/
|
||||
│ ├── crisis.webp
|
||||
│ ├── default.webp
|
||||
│ ├── sad.webp
|
||||
│ └── shocked.webp
|
||||
├── el-pablo/
|
||||
│ ├── crisis.webp
|
||||
│ ├── default.webp
|
||||
│ ├── ghastly.webp
|
||||
│ ├── melodramatic.webp
|
||||
│ ├── sad.webp
|
||||
│ └── shocked.webp
|
||||
└── foodogsquared/
|
||||
├── crisis.webp
|
||||
├── default.webp
|
||||
├── sad.webp
|
||||
└── shocked.webp
|
||||
----
|
||||
|
||||
- The following block should get the default image for `foodogsquared` which is in `./static/icons/avatars/foodogsquared/default.webp`.
|
||||
+
|
||||
....
|
||||
[chat, foodogsquared]
|
||||
====
|
||||
Hello there!
|
||||
====
|
||||
....
|
||||
|
||||
- The following block should contain El Pablo's melodramatic dialog state.
|
||||
Take note of the resulting path for the image which is in kebab-case.
|
||||
+
|
||||
....
|
||||
[chat, El Pablo, state=melodramatic]
|
||||
====
|
||||
What tragedy is happening here!
|
||||
I couldn't take it.
|
||||
|
||||
__Please__.
|
||||
====
|
||||
....
|
||||
@ -5,26 +5,25 @@ require 'asciidoctor/extensions'
|
||||
|
||||
require_relative 'helpers'
|
||||
|
||||
require_relative 'man-inline-macro/extension'
|
||||
require_relative 'swhid-inline-macro/extension'
|
||||
require_relative 'swhid-include-processor/extension'
|
||||
require_relative 'github-inline-macro/extension'
|
||||
require_relative 'github-include-processor/extension'
|
||||
require_relative 'gitlab-inline-macro/extension'
|
||||
require_relative 'gitlab-include-processor/extension'
|
||||
require_relative 'chat-block/extension'
|
||||
require_relative 'git-blob-include-processor/extension'
|
||||
require_relative 'wikipedia-inline-macro/extension'
|
||||
require_relative 'package-indices-macro/extension'
|
||||
require_relative 'fdroid-inline-macro/extension'
|
||||
require_relative 'musicbrainz-inline-macro/extension'
|
||||
require_relative 'flathub-inline-macro/extension'
|
||||
require_relative 'repology-inline-macro/extension'
|
||||
require_relative 'ietf-rfc-inline-macro/extension'
|
||||
require_relative 'extensions/man-inline-macro'
|
||||
require_relative 'extensions/swhid-inline-macro'
|
||||
require_relative 'extensions/swhid-include-processor'
|
||||
require_relative 'extensions/github-inline-macro'
|
||||
require_relative 'extensions/github-include-processor'
|
||||
require_relative 'extensions/gitlab-inline-macro'
|
||||
require_relative 'extensions/gitlab-include-processor'
|
||||
require_relative 'extensions/chat-block'
|
||||
require_relative 'extensions/git-blob-include-processor'
|
||||
require_relative 'extensions/wikipedia-inline-macro'
|
||||
require_relative 'extensions/package-indices-macro'
|
||||
require_relative 'extensions/fdroid-inline-macro'
|
||||
require_relative 'extensions/musicbrainz-inline-macro'
|
||||
require_relative 'extensions/flathub-inline-macro'
|
||||
require_relative 'extensions/repology-inline-macro'
|
||||
require_relative 'extensions/ietf-rfc-inline-macro'
|
||||
|
||||
include Asciidoctor::Foodogsquared::Extensions
|
||||
Asciidoctor::Extensions.register do
|
||||
|
||||
inline_macro ManInlineMacro
|
||||
inline_macro IETFRFCInlineMacro
|
||||
block ChatBlock if @document.basebackend? 'html'
|
||||
|
||||
@ -1,36 +0,0 @@
|
||||
= F-droid link inline macro
|
||||
:toc:
|
||||
|
||||
|
||||
An inline macro as a shorthand for F-droid links.
|
||||
|
||||
|
||||
== Synopsis
|
||||
|
||||
[source, asciidoc]
|
||||
----
|
||||
fdroid:$APP_ID[$CAPTION]
|
||||
----
|
||||
|
||||
Where...
|
||||
|
||||
- `$APP_ID` is the application ID of the program (e.g., `org.moire.ultrasonic`).
|
||||
|
||||
- `$CAPTION` is the link text.
|
||||
By default, it will use the display name of the application from its link:https://gitlab.com/fdroid/fdroiddata/[metadata repository].
|
||||
In other words, it will create an additional network request.
|
||||
|
||||
|
||||
== Attributes
|
||||
|
||||
- `lang` is the language page to be linked.
|
||||
By default, it links to the English page of `en`.
|
||||
|
||||
|
||||
== Example usage
|
||||
|
||||
- `fdroid:org.moire.ultrasonic[]` should link to the link:https://f-droid.org/en/packages/org.moire.ultrasonic/[F-Droid page for Ultrasonic] with the link text 'Ultrasonic'.
|
||||
|
||||
- `fdroid:org.moire.ultrasonic[Hello there]` is the same as previous item but with the link text replaced with 'Hello there'.
|
||||
|
||||
- `fdroid:org.moire.ultrasonic[lang=it]` is the same as the first list item but links to the link:https://f-droid.org/it/packages/org.moire.ultrasonic/[Italian page].
|
||||
@ -1,28 +0,0 @@
|
||||
= Flathub link inline macro
|
||||
:toc:
|
||||
|
||||
|
||||
A shorthand for linking applications from link:https://flathub.org[FlatHub].
|
||||
|
||||
|
||||
== Synopsis
|
||||
|
||||
[source, asciidoc]
|
||||
----
|
||||
flathub:$APP_ID[$CAPTION]
|
||||
----
|
||||
|
||||
Where...
|
||||
|
||||
- `$APP_ID` is the application ID of the program on Flathub.
|
||||
|
||||
- `$CAPTION` is the link text to be used.
|
||||
By default, it will get the appstream metadata from FlatHub and use the display name.
|
||||
Take note it creates an additional network request to get the name.
|
||||
|
||||
|
||||
== Example usage
|
||||
|
||||
- `flathub:org.gnome.design.IconLibrary[]` links to the link:https://flathub.org/apps/org.gnome.design.IconLibrary[FlatHub page of GNOME Icon Library] with `Icon Library` as the link text.
|
||||
|
||||
- `flathub:org.gnome.design.IconLibrary[GNOME Icon Library]` is the same as the previous list item but with its link text replaced with `GNOME Icon Library`.
|
||||
@ -1,57 +0,0 @@
|
||||
= Git blob include processor
|
||||
:toc:
|
||||
|
||||
|
||||
An include processor that includes content from the current Git repo.
|
||||
The use case for this is specifically for creating dedicated branches for certain content.
|
||||
|
||||
|
||||
== Synopsis
|
||||
|
||||
[source, asciidoc]
|
||||
----
|
||||
include::git:$REVSPEC[]
|
||||
----
|
||||
|
||||
Where `$REVSPEC` is a revision as specified in link:https://manpages.debian.org/gitrevisions.7[gitrevisions.7].
|
||||
Take note this include processor only accepts a blob object's content to be extracted.
|
||||
This is meant to be used with other attributes.
|
||||
See <<Attributes>> for more details.
|
||||
|
||||
If the resulting operation ends in an error (i.e., non-existing revision, file, something went wrong), it should log a warning and transclude an error.
|
||||
|
||||
|
||||
== Attributes
|
||||
|
||||
- `gitrepo` is the path to the Git repo.
|
||||
By default, it is the base directory of the document.
|
||||
|
||||
- `path` is the filepath to be retrieved from the revision.
|
||||
When used with `diff`, it changes into a semicolon-delimited (`;`) list of files to make diffs with multiple files.
|
||||
|
||||
- `context-lines` is the number of surrounding lines for the diff.
|
||||
This is only effective if `diff` option is given.
|
||||
|
||||
- `other` is the other commit to be compared with.
|
||||
This is only effective if `diff` option is given.
|
||||
|
||||
- `lines` get the specified lines from the path.
|
||||
It uses the same parser as the line specifier from link:https://docs.asciidoctor.org/asciidoc/latest/verbatim/highlight-lines/[highlighting select lines] so the syntax is the same.
|
||||
|
||||
There's also a couple of link:https://docs.asciidoctor.org/asciidoc/latest/attributes/options/[options] for this component.
|
||||
You can give the following options through `opts` attribute (i.e., `opts="diff,reverse"`).
|
||||
|
||||
- `diff` will show the difference in link:https://en.wikipedia.org/wiki/Diff[diff] format.
|
||||
|
||||
- `reverse` reverses the sides to be compared.
|
||||
|
||||
|
||||
== Example usage
|
||||
|
||||
- `include::git:HEAD[path=shell.nix]` should transclude the current iteration of `shell.nix`.
|
||||
|
||||
- `include::git:v1.0.0[opts="diff", path=Gemfile]` should include a diff of the Gemfile from `content/posts/sample` branch (assuming that Gemfile has changed).
|
||||
|
||||
- `include::git:non-existing-rev[opts="diff"]` should result in a warning with the non-existing revision.
|
||||
|
||||
- `include::git:{doccontentref}[path=README, lines=2..5]` should transclude the README file from lines 2-5.
|
||||
@ -1,40 +0,0 @@
|
||||
= GitHub raw content include processor
|
||||
:toc:
|
||||
|
||||
|
||||
This is a link:https://docs.asciidoctor.org/asciidoctor/latest/extensions/include-processor/[include processor] for easily including files from GitHub.
|
||||
Take note this will only include files.
|
||||
For directories, submodules, or symlinks: they will not be processed and a warning will be issued.
|
||||
|
||||
This extension honors the link:https://docs.asciidoctor.org/asciidoctor/latest/safe-modes/[safe mode setting] and link:https://docs.asciidoctor.org/asciidoc/latest/directives/include-uri/[the prerequisites for permitting includes with URI].
|
||||
|
||||
The following is the basic form of using this include processor.
|
||||
|
||||
[source, asciidoc]
|
||||
----
|
||||
\include::github:$OWNER/$REPO[]
|
||||
----
|
||||
|
||||
|
||||
== Extra notes
|
||||
|
||||
The include processor will use GitHub API.
|
||||
It can create authorized requests by setting a token in `GITHUB_API_BEARER_TOKEN` environment variable.
|
||||
For instructions on how to get a token, you can refer to link:https://docs.github.com/en/rest/guides/getting-started-with-the-rest-api?apiVersion=2022-11-28#authenticating[respective documentation].
|
||||
|
||||
|
||||
== Attributes
|
||||
|
||||
- `path` for the path of the file to be included.
|
||||
This is practically required as the root entry of the repository is a directory.
|
||||
|
||||
- `rev` is the name of the commit/tag/branch to be checked out.
|
||||
|
||||
|
||||
== Example usage
|
||||
|
||||
- `include::github:asciidoctor/asciidoctor[path=README.adoc, rev=v2.0.0]` will include the Asciidoc file from the link:https://github.com/asciidoctor/asciidoctor/[Asciidoctor GitHub repo] from the point of `v2.0.0`.
|
||||
|
||||
- `include::github:NixOS/nixpkgs[path=shell.nix]` will get the latest revision of `shell.nix` from link:https://github.com/NixOS/nixpkgs[nixpkgs repository].
|
||||
|
||||
- `include::github:foo-dogsquared/nixos-config[]` should not be processed considering it points to the root directory of the repository.
|
||||
@ -1,49 +0,0 @@
|
||||
= GitHub link inline macro
|
||||
:toc:
|
||||
|
||||
|
||||
An inline macro that easily links repositories from GitHub.
|
||||
|
||||
|
||||
== Synopsis
|
||||
|
||||
[source, asciidoc]
|
||||
----
|
||||
github:$OWNER/$REPO[$CAPTION]
|
||||
----
|
||||
|
||||
If caption is missing, the link text will be the namespace (i.e., `$OWNER/$REPO`) of the repo.
|
||||
|
||||
|
||||
== Attributes
|
||||
|
||||
There are optional attributes for this macro.
|
||||
|
||||
- `rev` is the commit/branch/tag of the repo to be linked.
|
||||
When given no caption, it will update the default caption with `$OWNER/$REPO@$REV`.
|
||||
|
||||
- `path` is the filepath to be linked within the repo.
|
||||
|
||||
- `issue` accepts the issue number to be linked in the GitHub repo.
|
||||
Take note `issue` is exclusive to other attributes and has more precedence.
|
||||
For example, if `issue` and `rev` are both present, the link for issue will be the result.
|
||||
+
|
||||
When given no caption, it will update the default caption with `$OWNER/$REPO#$ISSUE`.
|
||||
|
||||
You can also change certain behaviors with the link:https://docs.asciidoctor.org/asciidoc/latest/attributes/options/[options attribute].
|
||||
|
||||
- `repo` sets the default link text with only the repo.
|
||||
Pretty useful to quickly refer to the name of the software.
|
||||
|
||||
|
||||
== Example usage
|
||||
|
||||
- `github:foo-dogsquared/website[]` will link to link:https://github.com/foo-dogsquared/website[my website repository] with the link text `foo-dogsquared/website`.
|
||||
|
||||
- `github:NixOS/nixpkgs[nixpkgs nixos-unstable branch, rev=nixos-unstable]` should link to the link:https://github.com/NixOS/nixpkgs/tree/nixos-unstable[NixOS unstable branch of nixpkgs] with a caption of `nixpkgs nixos-unstable branch`.
|
||||
|
||||
- `github:errata-ai/vale[Vale v2.3.0 README, path=README.md, rev=v2.3.0]` should link to the link:https://github.com/errata-ai/vale/blob/v2.3.0/README.md[README of Vale v2.3.0].
|
||||
|
||||
- `github:neovim/neovim[Neovim cannot open large files properly, issue=614]` should link to https://github.com/neovim/neovim/issues/614[an issue of Neovim] with `Neovim cannot open large files properly` as the link text.
|
||||
|
||||
- `github:neovim/neovim[Neovim cannot open large files properly, issue=614, rev=master]` should still link to https://github.com/neovim/neovim/issues/614[an issue of Neovim] since `issue` has more precedence over `rev`.
|
||||
@ -1,44 +0,0 @@
|
||||
= GitLab raw content include processor
|
||||
:toc:
|
||||
|
||||
|
||||
It's a link:https://docs.asciidoctor.org/asciidoctor/latest/extensions/include-processor/[include processor] for easily including raw content from GitLab repositories.
|
||||
|
||||
|
||||
== Synopsis
|
||||
|
||||
[source, asciidoc]
|
||||
----
|
||||
include::gitlab/$OWNER/$REPO[rev=$COMMIT, path=$FILEPATH]
|
||||
----
|
||||
|
||||
|
||||
== Extra notes
|
||||
|
||||
A link:https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#personal-access-tokens[personal access token] is most likely required.
|
||||
Get one and place the value in an environment variable `GITLAB_API_PERSONAL_ACCESS_TOKEN`.
|
||||
|
||||
|
||||
== Attributes
|
||||
|
||||
There are some attributes required to be passed.
|
||||
|
||||
- `rev` is the commit to be checked out.
|
||||
- `path` is the file path to be included.
|
||||
|
||||
Aside from the required attributes, there are optional attributes to configured further.
|
||||
|
||||
- `domain` is the domain of the GitLab instance.
|
||||
By default, it points to the `gitlab.com` official instance.
|
||||
|
||||
- `version` is the version string of the API to be used.
|
||||
By default, it uses version `v4`.
|
||||
|
||||
|
||||
== Example usage
|
||||
|
||||
- `include::gitlab:gitlab-org/gitlab[rev=master, path=README.md]` should include the README content from the master branch of link:https://gitlab.com/gitlab-org/gitlab/[GitLab source code].
|
||||
|
||||
- `include::freedesktop-sdk/freedesktop-sdk[rev=bcb3e0de957519e87a4c7b8c0e40af9876e531e7, path=.gitlab-ci.yml]` should transclude the GitLab CI configuration from link:https://gitlab.com/freedesktop-sdk/freedesktop-sdk[Freedesktop SDK].
|
||||
|
||||
- `include::World/warp[domain=gitlab.gnome.org, rev=v0.5.2, path=meson_options.txt]` includes `meson_options.txt` from link:https://gitlab.gnome.org/World/warp/[Warp source code] at v0.5.2.
|
||||
@ -1,40 +0,0 @@
|
||||
= GitLab link inline macro
|
||||
:toc:
|
||||
|
||||
|
||||
An inline macro for easily linking objects from GitLab instances.
|
||||
|
||||
|
||||
== Synopsis
|
||||
|
||||
[source, asciidoc]
|
||||
----
|
||||
gitlab:$OWNER/$REPO[$CAPTION]
|
||||
----
|
||||
|
||||
|
||||
== Attributes
|
||||
|
||||
- `domain` is the base domain of the GitLab instance.
|
||||
By default, it points to the official instance of `gitlab.com`.
|
||||
|
||||
- `rev` is the commit of the repo.
|
||||
By default. it doesn't point to anything which should be in the default branch of the repository.
|
||||
|
||||
- `path` is the filepath to be linked.
|
||||
|
||||
- `issue` is the issue to be linked from the repo.
|
||||
Take note issue has higher precedence so once `domain` and `issue` are both set, it will still link to an issue.
|
||||
|
||||
There are settings that is enabled with the link:https://docs.asciidoctor.org/asciidoc/latest/attributes/options/[options attribute].
|
||||
|
||||
- `repo` sets the default caption to be the repo part.
|
||||
|
||||
|
||||
== Example usage
|
||||
|
||||
- `gitlab:gitlab-org/gitlab[]` will link to link:https://gitlab.com/gitlab-org/gitlab[the GitLab's source code with the default domain].
|
||||
|
||||
- `gitlab:gitlab-org/gitlab[rev=0c9f77389424b6c5fd8e96b227e9125a13a07cb3, path=README.md]` should link to the link:https://gitlab.com/gitlab-org/gitlab/-/blob/0c9f77389424b6c5fd8e96b227e9125a13a07cb3/README.md[GitLab's README from 3 years ago].
|
||||
|
||||
- `gitlab:GNOME/mutter[domain=gitlab.gnome.org, rev=df653b95adf6462fc731998eb53b0860baa7253c, path=meson.build]` should link to link:https://gitlab.gnome.org/GNOME/mutter/-/blob/df653b95adf6462fc731998eb53b0860baa7253c/meson.build[Mutter v44.beta `meson.build` from GNOME GitLab instance].
|
||||
@ -1,27 +0,0 @@
|
||||
= Flathub link inline macro
|
||||
:toc:
|
||||
|
||||
|
||||
A shorthand for linking link:https://datatracker.ietf.org/[IETF RFCs].
|
||||
|
||||
|
||||
== Synopsis
|
||||
|
||||
[source, asciidoc]
|
||||
----
|
||||
rfc:$RFC[$CAPTION]
|
||||
----
|
||||
|
||||
Where...
|
||||
|
||||
- `$RFC` is the RFC number.
|
||||
|
||||
- `$CAPTION` is the link text to be used.
|
||||
By default, it will be `RFC$RFC`.
|
||||
|
||||
|
||||
== Example usage
|
||||
|
||||
- `rfc:2136[]` links to the link:https://datatracker.ietf.org/doc/html/rfc2136[RFC2136 (dynamic update)] with the caption `RFC2136`.
|
||||
|
||||
- `rfc:2136[Dynamic DNS updates]` is the same as the previous list item but with the caption text `Dynamic DNS updates`.
|
||||
@ -1,51 +0,0 @@
|
||||
= Man inline macro
|
||||
:toc:
|
||||
|
||||
|
||||
It's a link:https://docs.asciidoctor.org/asciidoctorj/latest/extensions/inline-macro-processor/[inline macro] that easily links manual pages from an online manpage service like link:https://manpages.debian.org/[Debian Manpages].
|
||||
|
||||
|
||||
== Synopsis
|
||||
|
||||
[source, asciidoc]
|
||||
----
|
||||
man:$MANPAGE[$VOLNUM]
|
||||
----
|
||||
|
||||
|
||||
== Attributes
|
||||
|
||||
There are optional attributes that can be passed.
|
||||
|
||||
- `volnum` expects the section number where the manual page belongs to.
|
||||
This attribute is another way to indicate the section in case you start to use more attributes.
|
||||
The value from `volnum` attribute has higher precedence.
|
||||
When both the positional argument and `volnum` attribute is passed, the `volnum` attribute will be used.
|
||||
|
||||
- `service` is the domain of the online manpage service.
|
||||
Take note this attribute is only used in `html` backend.
|
||||
+
|
||||
--
|
||||
This is an attribute that expects certain values:
|
||||
|
||||
- `debian` uses https://manpages.debian.org.
|
||||
This is also the default service when no value is given.
|
||||
|
||||
- `archlinux` uses https://man.archlinux.org.
|
||||
|
||||
- `opensuse` uses https://manpages.opensuse.org.
|
||||
|
||||
- `voidlinux` use https://man.voidlinux.org.
|
||||
|
||||
- `none` uses none at all. :)
|
||||
This is useful if the reference is not found anywhere.
|
||||
|
||||
Any invalid value raises an error.
|
||||
--
|
||||
|
||||
|
||||
== Example usage
|
||||
|
||||
- `man:crontab[5]` will link to the default manpage service with `crontab(5)` manual page.
|
||||
|
||||
- `man:man[volnum=1, service=archlinux]` will link to the link:https://man.archlinux.org/man/man.1[man manpage] from link:https://man.archlinux.org/[man.archlinux.org].
|
||||
@ -1,45 +0,0 @@
|
||||
= Musicbrainz link inline macro
|
||||
:toc:
|
||||
|
||||
|
||||
An inline macro for easily linking objects from link:https://musicbrainz.org/doc/MusicBrainz_Database[Musicbrainz database].
|
||||
|
||||
|
||||
== Synopsis
|
||||
|
||||
[source, asciidoc]
|
||||
----
|
||||
musicbrainz:$ID[$CAPTION, $TYPE]
|
||||
----
|
||||
|
||||
- `$ID` is the database identifier for that object (e.g., `9adcff14-7dba-4ccf-a6a6-298bcde3dd46`).
|
||||
|
||||
- `$CAPTION` is the link text.
|
||||
By default, it will be the name of the database object (if valid).
|
||||
Take note it will use the MusicBrainz API to query the title/name of the object.
|
||||
In other words, it costs an additional network request.
|
||||
|
||||
- `$TYPE` is the database object type.
|
||||
It defaults to 'Release' object type.
|
||||
|
||||
|
||||
== Attributes
|
||||
|
||||
The macro can also accept some attributes.
|
||||
|
||||
- `caption` is the link text to be used.
|
||||
This can be used instead of the first positional attribute.
|
||||
|
||||
- `type` is the database object type to be queried.
|
||||
This can be used instead of the second positional attribute.
|
||||
|
||||
|
||||
== Example usage
|
||||
|
||||
- `musicbrainz:9adcff14-7dba-4ccf-a6a6-298bcde3dd46[]` should have a link to the link:https://musicbrainz.org/release/9adcff14-7dba-4ccf-a6a6-298bcde3dd46[Musicbrainz page for The Bindings of Isaac Rebirth] with 'The Bindings of Isaac: Rebirth' as the link caption.
|
||||
|
||||
- `musicbrainz:9adcff14-7dba-4ccf-a6a6-298bcde3dd46[Ridiculon's Rebirth soundtrack]` same as above but with the link text replaced with 'Ridiculon's Rebirth Soundtrack'.
|
||||
|
||||
- `musicbrainz:b7c7f603-4c42-45a4-b364-3ddba82da412[type=release-group]` links to the link:https://musicbrainz.org/release-group/b7c7f603-4c42-45a4-b364-3ddba82da412[Musicbrainz page for The Bindings of Isaac Rebirth release group] with 'The Bindings of Isaac: Rebirth' as the link text.
|
||||
|
||||
- `musicbrainz:f07c6afe-ee84-4cd5-9b11-5c541d1dff3b[type=artist]` links to link:https://musicbrainz.org/artist/f07c6afe-ee84-4cd5-9b11-5c541d1dff3b[Musicbrainz page for Ridiculon] with their name as the caption.
|
||||
@ -1,27 +0,0 @@
|
||||
= Repology link inline macro
|
||||
:toc:
|
||||
|
||||
|
||||
An inline macro for shorthands Repology links.
|
||||
|
||||
|
||||
== Synopsis
|
||||
|
||||
[source, asciidoc]
|
||||
----
|
||||
repology:$PROJECT[$CAPTION]
|
||||
----
|
||||
|
||||
Where...
|
||||
|
||||
- `$PROJECT` is the project name listed in link:https://repology.org/projects/[Repology's project list].
|
||||
|
||||
- `$CAPTION` is the link text to be used.
|
||||
By default, it will use the project name.
|
||||
|
||||
|
||||
== Example usage
|
||||
|
||||
- `repology:beets[]` should link to the link:https://repology.org/project/beets/[Beets project page in Repology] with `beets` as the link text.
|
||||
|
||||
- `repology:beets[widely available in Linux distributions]` is the same as the previous item but with the link text replaced to `widely available in Linux distributions`.
|
||||
@ -1,26 +0,0 @@
|
||||
= SPDX link inline macro
|
||||
:toc:
|
||||
|
||||
It's an inline macro for easily creating licenses from SPDX license data.
|
||||
|
||||
|
||||
== Synopsis
|
||||
|
||||
[source, asciidoc]
|
||||
----
|
||||
spdx:$LICENSE_ID[$CAPTION]
|
||||
----
|
||||
|
||||
Where...
|
||||
|
||||
* `$LICENSE_ID` is the identifier for the license.
|
||||
|
||||
* `$CAPTION` is the link caption to be used.
|
||||
By default, it will use the name of the license.
|
||||
|
||||
|
||||
== Example usage
|
||||
|
||||
* `spdx:MIT[]` will result to the link:https://spdx.org/licenses/MIT.html[MIT license page on SPDX] with the caption `MIT License`.
|
||||
|
||||
* `spdx:MIT[the MIT license]` is the same as the previous example but with a different caption of `the MIT license`.
|
||||
@ -1,44 +0,0 @@
|
||||
= 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`.
|
||||
@ -1,54 +0,0 @@
|
||||
= SWHID inline macro extension
|
||||
:toc:
|
||||
|
||||
|
||||
An inline macro for easily linking link:https://docs.softwareheritage.org/devel/swh-model/persistent-identifiers.html[SWHIDs].
|
||||
|
||||
|
||||
== Synopsis
|
||||
|
||||
[source, asciidoc]
|
||||
----
|
||||
swh:$SWHID[$CAPTION]
|
||||
----
|
||||
|
||||
If no caption is given, the link text will be the core identifier of the SWHID.
|
||||
|
||||
|
||||
== Attributes
|
||||
|
||||
You can configure certain behavior of the macro with the link:https://docs.asciidoctor.org/asciidoc/latest/attributes/options/[options attribute].
|
||||
Here's a list of them...
|
||||
|
||||
- `full` will make the entire SWHID as the default link text.
|
||||
|
||||
|
||||
== Extra notes
|
||||
|
||||
You would use like in the following form `swh:swh:1:snp:6ea7d28dfd4789609e0be2b64179fc9c12931beb[]` but you could also cut off `swh:` from the SWHID if you want to (i.e., `swh:1:snp:6ea7d28dfd4789609e0be2b64179fc9c12931beb[]`) to make it aesthetically pleasing.
|
||||
|
||||
Whatever your preference is, the best practice for dealing with linking SWHIDs with this macro is setting attributes containing the SWHIDs.
|
||||
|
||||
[source, asciidoc]
|
||||
----
|
||||
= doctitle
|
||||
:swhid-nixpkgs: swh:1:dir:2885ecf76632a83610d8e95f0eb3383109a7c90a
|
||||
|
||||
{swhid-nixpkgs}[this revision of nixpkgs]
|
||||
or
|
||||
swh:{swhid-nixpkgs}[that revision of nixpkgs]
|
||||
----
|
||||
|
||||
|
||||
== Example usage
|
||||
|
||||
This should work with the following types of SWHIDs.
|
||||
|
||||
- A SWHID with only the core identifier: `swh:1:snp:6ea7d28dfd4789609e0be2b64179fc9c12931beb[]`.
|
||||
|
||||
- A SWHID with only one qualifier with a link caption: `swh:1:cnt:ce4dd1988d2d5dfcec48252757a6fea94339ac38;lines=3-4[some code text]`
|
||||
|
||||
- A SWHID with full contextual information.
|
||||
This is as depicted from the recommended practice for writings (i.e., blog posts, technical documentation, research papers) when referring to one of the objects in the archive.
|
||||
+
|
||||
`swh:1:dir:2885ecf76632a83610d8e95f0eb3383109a7c90a;origin=https://github.com/NixOS/nixpkgs;visit=swh:1:snp:6ea7d28dfd4789609e0be2b64179fc9c12931beb;anchor=swh:1:rev:b7ee21d0ced814d07b7d5aca334dfe018ceafaa5[]`
|
||||
@ -1,30 +0,0 @@
|
||||
= Wikipedia inline macro
|
||||
:toc:
|
||||
|
||||
|
||||
An inline macro for easily creating Wikipedia links (i.e., `wikipedia.org`).
|
||||
|
||||
|
||||
== Synopsis
|
||||
|
||||
[source, asciidoc]
|
||||
----
|
||||
wikipedia:PAGE[$CAPTION]
|
||||
----
|
||||
|
||||
Where if `$CAPTION` is present, it will be used as the link text.
|
||||
Otherwise, it will just be the page.
|
||||
|
||||
|
||||
== Attributes
|
||||
|
||||
- `lang` is the language domain to be linked into.
|
||||
By default, it is set to `en`.
|
||||
|
||||
|
||||
== Example usage
|
||||
|
||||
- `wikipedia:Diff[]` should link to the link:https://en.wikipedia.org/wiki/Diff[Diff page on English Wikipedia].
|
||||
- `wikipedia:Diff[lang=ja]` should link to the link:https://ja.wikipedia.org/wiki/Diff[Diff page on Japanese Wikipedia].
|
||||
- `wikipedia:Photosynthesis[lang=simple]` should link to the link:https://simple.wikipedia.org/wiki/Photosynthesis[Photosynthesis page on Simple English Wikipedia].
|
||||
- `wikipedia:Diff[diff in Japanese Wikipedia, lang=ja]` should link to the link:https://ja.wikipedia.org/wiki/Diff[Diff page on Japanese Wikipedia] with the `diff in Japanese Wikipedia` as the link text.
|
||||
Loading…
Reference in New Issue
Block a user