Variable interpolation in Kotlin

[MagnusMG]

I added variables to description strings in my Kotlin code, like this:

@Parameters(paramLabel="TARGET", description = ["Any of the following: ${COMPLETION-CANDIDATES}"])

The result in the help text was that no text at all was printed for this parameter. Not even 'Any of the following:'.

After some experimentation I found that I had to escape the $-sign to make it work:

@Parameters(paramLabel="TARGET", description = ["Any of the following: \${COMPLETION-CANDIDATES}"])

This could perhaps be added to the manual.

[remkop]

@MagnusMG oh wow, I did not know about that, thank you for reporting this!

It seems that Kotlin has its own string interpolation, but the docs are a bit minimal. It appears that Kotlin uses the $ character to interpolate a variable and ${} to interpolate an expression. And my guess is that COMPLETION-CANDIDATES not being a valid expression causes the whole string to become... (what exactly?) ... bit strange error handling in my opinion, but okay.

The manual needs updating, agreed.

Do you feel like providing a pull request for this?

[MagnusMG]

As I started looking into changing the documentation, I noticed that the Kotlin code examples already have the dollar signs escaped. I somehow missed that.

That makes me less certain that a change of the manual is needed. Perhaps a short mention just under the first example. (The adoc files, are they for Asciidoctor or some other software?)

[remkop]

AsciiDoctor yes.

Maybe a CAUTION block after the first example in section 20.1 Variable Interpolation Example?

[MagnusMG]

I have installed GitHub Desktop, checked out the source code, created a branch and adjusted the adoc file. However, when I convert index.adoc to html the result does not look quite like the original - the example code sections do not show up as alternatives that you select with a button, but rather they are listed one after the other. I assume I'm doing something wrong. I have tried running ./gradlew build in the root directory, but that does not seem to include the docs.

[remkop]

What is the path of the resulting HTML file you looked at?

The generated docs end up in build/docs/ somewhere (I think in a html5 directory).

[remkop]

The task to just build the docs is:

./gradlew asci 

The button vs sequential samples is a JavaScript plugin for AsciiDoctor. Do you see any errors in the build output?
What browser did you check the results in?

[MagnusMG]

I found the generated HTML file, and it looks fine, so I created a pull request. I haven't used GiutHub or git before, the GitHub documentation reminds me of the "Sea of Talmud", and I was not able to find a relevant guide, but I think I got it right in the end. Tell me otherwise.