Hyperlinks with double brackets in the URL

0 votes
asked Dec 1, 2021 in Question / help by mbraakhekke (120 points)

I'm using a python-based Fortran source code documentation generator (FORD; https://github.com/Fortran-FOSS-Programmers/ford) which outputs html files, similar to sphinx. FORD allows you to include markdown files which can contain links to certain parts in the documentation. These links are specified with double brackets (e.g. [[myfunction]]). In the html code created from the md files, these links are then replaced by the appropriate URL by FORD.

I would like to include plantuml diagrams, which is possible with the plantuml-markdown python extension. But adding links is problematic since both plantuml and FORD use double brackets to specify links. I was hoping that I could simply use four sets of brackets ([[[[myfuncion]]]]). Plantuml would then remove the outer set, creating a link [[myfunction]] in the html output and  FORD would replace that by the correct URL. But this doesn't work: plantuml complains about incorrect syntax (e.g. participant parcip [[[[parcip]]]] ). I also tried escaping the inner brackets (participant parcip [[\[\[parcip\]\]]]) but this doesn't work either.

Would it be possible to create hyperlinks with double brackets in the URL in plantuml?

This question is similar to this one https://forum.plantuml.net/1170/how-can-i-escape-double-square-brackets?show=1170#q1170 but the difference is that the poster wants the label of the link to have double brackets while I want this for URL.

1 Answer

+1 vote
answered Dec 1, 2021 by plantuml (294,960 points)
Maybe we could propose a secondary syntax for hyperlinks to avoid syntax clash.
Using 4 brackets would impact readability, I think.

In addition of the square bracket syntax:
[[http://foo]]
[[http://foo{tooltip} text]]

Maybe we could propose:

Solution 1:
{{http://foo}}
{{http://foo{tooltip} text}}

Solution 2:
||http://foo||
||http://foo{tooltip} text||

Solution 3:
!!http://foo!!
!!http://foo{tooltip} text!!

The real issue here is to avoid syntax clash with all other creole syntax.

We have a preference for solution 1.
Any though?
commented Dec 1, 2021 by mbraakhekke (120 points)

Thanks for the fast reply and the proposed solution! I don't have any specific preference for any syntax. As long as it's possible to do something like this:

{{[[mylink]]}}

which then gets parsed to a hyperlink with URL (including the square brackets):

[[mylink]]
commented Dec 1, 2021 by plantuml (294,960 points)

Plantuml would then remove the outer set, creating a link [[myfunction]] in the html output and  FORD would replace that by the correct URL

Now I'm confused :-)

First, PlantUML never generates HTML output. It generate SVG or PNG output. I guess that you are using SVG, but I'm not sure now.

What we propose is:

{{link}}

that would be get parsed to a hyperlink in the SVG file.

I though that you wanted hyperlinks documented in the PlantUML source of the markdown comment in your Fortran source to be ignored by FOSS.

Can you post here a simple example of some Fortran source so that we better understand what you are trying to achieve ?

Thanks!

commented Dec 2, 2021 by mbraakhekke (120 points)
Sorry for the confusion. Yes, the diagrams are rendered as SVG.
I don't think sending a concrete example would be helpful but I'll try to explain things more clearly.

As I wrote earlier, the plantuml-markdown Python extension allows one to include plantuml code in markdown files (see example below). Creating documentation with FORD involves three processing steps:
1. plantuml processes the diagram part to an svg image, possibly including hyperlinks
2. python-markdown converts the the markdown file, including svg image, to html
3. FORD further processes the html code and replaces any strings in the form [[myfunction]] by the appropriate url

Suppose we have a markdown file with a plantuml diagram like this:

Here's some explanation of [[MyClass]].
```plantuml format="svg_inline"
participant MyClass [[MyClass]]
MyClass --> MyClass
```
Some more explanation.

The first [[MyClass]] string is correctly handled. But the second one in the plantuml diagram gets converted to something like: <a href="MyClass">MyClass</a> in the svg (and html) code by plantuml. Thus the double brackets are removed and in the 3rd step FORD no longer recognizes it as a intra-doc link and leaves it as is, resulting in a broken link.

I thought that this could be solved on the plantuml side. However, after further studying the inner workings of FORD, I now realize that it needs to be handled on the FORD side (I won't go into the details). So I'll take it up with the FORD developers. I'm hoping we can come to a solution that won't require any changes to plantuml, which would be preferable, I think.
commented Dec 2, 2021 by plantuml (294,960 points)

The first [[MyClass]] string is correctly handled. But the second one in the plantuml diagram gets converted to something like: <a href="MyClass">MyClass</a> in the svg (and html) code by plantuml. Thus the double brackets are removed and in the 3rd step FORD no longer recognizes it as a intra-doc link and leaves it as is, resulting in a broken link.

Ok, thanks for the explanation. I better understand the issue now.
Indeed, whatever the syntax we choose in PlantUML, the link will still be converted to to something like: <a href="MyClass">MyClass</a> in the svg.
Trying to generate something like <a href="MyClass">[[MyClass]]</a> is not a good solution, I think.


I thought that this could be solved on the plantuml side. However, after further studying the inner workings of FORD, I now realize that it needs to be handled on the FORD side (I won't go into the details). So I'll take it up with the FORD developers. I'm hoping we can come to a solution that won't require any changes to plantuml, which would be preferable, I think.

I agree, I think this should be handled on the FORD side.
However, if there is something we could do on our side, do not hesitate to ask.
Keep us informed!

...