[OPENJDK-1963] document MAVEN_MIRRORS upcasing behaviour #404
Conversation
modules/maven/default/module.yaml
Outdated
| See also: `prefix_MAVEN_MIRROR_ID`; `prefix_MAVEN_MIRROR_OF`; | ||
| `prefix_MAVEN_MIRROR_URL`. |
There was a problem hiding this comment.
Not sure what is meant by prefix_MAVEN_MIRROR_ID. Is it meant to point to a variable, like if MAVEN_MIRRORS=one then prefix becomes ONE_? If so, how about using <prefix>_MAVEN_MIRROR_ID etc. and including the example last, which would tie everything together?
There was a problem hiding this comment.
You're guess is right, that's what it's intended to be used as. There's no tooling that puts in cross-reference hyperlinks, (yet), but it's intended to point the reader at the entry for prefix_MAVEN_MIRROR_URL, elsewhere. Since prefix_ is indeed a placeholder, we could adopt a nomenclature to make that clearer. I'll have to experiment to make sure that the GHA scripts don't choke on chevrons.
There was a problem hiding this comment.
We could use <prefix>_MAVEN_MIRROR_URL without breaking anything.
if we used <<prefix_MAVEN_MIRROR_URL>>, the doc generator would put an internal hyperlink in to a section labelled with the same name. To make the label, we would need the intermediate asciidoctor for the target text to look like [[prefix_MAVEN_MIRROR_URL]]prefix_MAVEN_MIRROR_URL. This could be achieved with
- name: '[[prefix_MAVEN_MIRROR_URL]]prefix_MAVEN_MIRROR_URL'
description: "The URL of the mirror."
example: "http://10.0.0.1:8080/repository/internal"but that's ugly. Alternatively the python script could automatically generate the [[]] anchor part for every row.
This might be clearer with a POC and I'm conflating two things here
- adding cross-references between entries
- replacing
prefix_SOME_THINGto make clearer to humans thatprefix_is a placeholder
rewrite description of MAVEN_MIRRORS to properly document the format of the parameter (uppercase, dashes get replaced with underscores). Signed-off-by: Jonathan Dowland <[email protected]>
jmtd
force-pushed
the
OPENJDK-1963-MAVEN_MIRRORS-case
branch
from
f67fbb8 to
e10b056
Compare
Where we refer to an environment variable with a portion to be substituted, e.g. `prefix_MAVEN_MIRROR_ID` where "prefix" will be substitute by something like APP1, depending on the value of `MAVEN_MIRRORS`, use the convention "<prefix>", to indicate that the value is a placeholder. Signed-off-by: Jonathan Dowland <[email protected]>
|
I've pushed a commit that standardizes on |
rewrite description of MAVEN_MIRRORS to properly document the format of the parameter (uppercase, dashes get replaced with underscores).
https://issues.redhat.com/browse/OPENJDK-1963