Closed lefou closed 8 years ago
Do other libraries in the asciidoctor ecosystem set a similar attribute?
Yes. E.g. on GitHub, there is env-github
. The asciidoctor plugin for gitbucket sets env-gitbucket
.
Additionally, env=asciidoclet
would be a good idea too.
WDYT?: #58
setting env
has the possibility to collide between libraries btw. Asciidoclet uses Asciidoctorj, which I imagine could set a similar env=asciidoctorj
.
@lefou, Im curious, what is your use-case for this?
asciidoctorj does not set env
attribute, and current usage of the env
attribute in other places (and my conversations with @mojavelinux ) suggest it is meant the way we want it to use it here. Also gitbucket-asciidoctor-plugin is also based on asciidoctorj.
My current use case was reusing the project README.adoc
, which is the entry point documentation on GitHub, also as the overview page in the JavaDoc. Of course some links are different and need to be handled conditionally for each environment. E.g. src/main/java
prefix or not, .java
or .html
file ending, etc.
ifdef::env-github,env-gitbucket[:outfilesuffix: .adoc]
ifndef::env-asciidoclet[:srcdir: src/main/java/]
ifdef::env-asciidoclet[:srcdir:]
ifndef::env-asciidoclet[:javasuffix: .java]
ifdef::env-asciidoclet[:javasuffix: .html]
link:{srcdir}org/example/Main{javasuffix}[`Main`]
Makes sense.
:+1:
Correct. env
is the execution environment, not which implementation of the processor is being used. In other words, it describes where the document is being converted. We set this in plugins such as a static site generator, so it makes a lot of sense to set it here too.
This would ease custom processing for Javadoc, e.g. with
ifdef::
.