Allow text to change along with selected snippet alternative

[ktoso]

In order to totally move away from page-per-language we'd need something like the below (pseudo code):

So this is some thing, we'll explain how to use it... Lorem ipsum, lorem ipsum, lorem ipsum,
lorem ipsum, lorem ipsum, lorem ipsum, lorem ipsum, lorem ipsum, lorem ipsum...

@@snip-text[example-snippet, Scala]
In scala the thing is provided via an implicit parameter, yay!
@@snip-text

@@snip-text[example-snippet, Java]
In java you gave to get the thing via Get.getTheThing, simple.
@@snip-text


Scala
:   @@snip [example-snippet](/../../../build.sbt) { #setup_example }
Java
:   @@snip [example-snippet](../../../pom.xml) { #setup_example }

If you see what I'm getting at. This way for either language the text would "feel right".
Just putting the text into the snippet does not feel right, we'd randomly have bits inside the tab and others not.

[ktoso]

Refers to akka/akka-http#527

[jonas]

By leveraging the @@@div directive (#58), I believe this and the ability to switch all tabs on a page (#11) can be handled entirely via the theme. For example:

So this is some thing, we'll explain how to use it... Lorem ipsum, lorem ipsum, lorem ipsum,
lorem ipsum, lorem ipsum, lorem ipsum, lorem ipsum, lorem ipsum, lorem ipsum...

@@@ div { .scala }
In scala the thing is provided via an implicit parameter, yay!
@@@

@@@ div { .java }
In java you gave to get the thing via Get.getTheThing, simple.
@@@

Scala
:   @@snip [example-snippet](/../../../build.sbt) { #setup_example }
Java
:   @@snip [example-snippet](../../../pom.xml) { #setup_example }

And you could probably also group the snippets under the div if that was desired.

[ktoso]

So this is needed if Akka HTTP is to switch to a "single tree".
I'm not quite sure what's to be done here - is this a large effort @jonas?

[jonas]

Doing it via JavaScript should be straightforward. If Paradox will support PDF output in the future then there will likely need to be some sort of or preprocessing involved but I suggest to not worry about that now.

[ktoso]

I agree, let's not think about the PDF for now at least.

[2m]

Another usecase for this that should not be forgotten is to switch between scaladoc and javadoc links. That is a user looking at java documentation would like to get a link to a corresponding javadoc and if she is browsing scala documentation, clicking on a link on a type should open a scaladoc page.

[pvlugter]

Text switching added in #107. Should be possible to at least wrap scaladoc/javadoc in the new scala/java group directives. Makes sense to generate the switching wrappers automatically for api links though.

[richardimaoka]

Hi, where should I put JavaScript code to handle CSS classes like below which @jonas suggested?

@@@ div { .scala }
In scala the thing is provided via an implicit parameter, yay!
@@@

I wanted to work on on merging Akka's Scala and Java docs, but found Akka doc has Scala-specific sections like this (AnyVal is only for Scala), which we don't want to show when the Java group (in paradox) is selected.

I think switching for multi-line text, including things like @@@ note directives, is needed, which @scala[], @java[] directives for in-line text do not cover.

[2m]

It is already supported by giving a container a specific group class:

@@@ div { .group-scala }
In scala the thing is provided via an implicit parameter, yay!
@@@

@@@ div { .group-java }
In java no implicits.
@@@

[richardimaoka]

Ah, I didn't realize that. Thank you very much!!

[2m]

Fixed in #116