Fortran-FOSS-Programmers / Fortran-FOSS-Programmers/ford

Plantuml diagrams with intra-doc links

Open
#370 2 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
458
Forks
138
PR merge metrics
No merged PRs in 30d

Description

Using the markdown extension [`plantuml-markdown`](https://github.com/mikitex70/plantuml-markdown) it's possible to include [plantuml](https://plantuml.com/) diagrams in the markdown pages. These then get incorporated into the HTML output. Plantuml also supports [hyperlinks](https://plantuml.com/link) in the diagrams. I would like to use this feature to link to other parts in the documentation from the diagrams. By specifying SVG output, it's possible to have links in generated diagrams that get incorporated in html.

Suppose we have a markdown page with a plantuml diagram and intra-doc links:

Here's some explanation of [[my_function(function)]].
```plantuml format="svg_inline"
participant my_function [[my_function(function)]]
participant my_other_function
my_function --> my_other_function
```

The first link to my_function will get properly converted but the second link within the plantuml code will not. Plantuml also uses double brackets to signify hyperlinks, so the string `[[my_function(function)]]` will get converted to something like `my_function(function)` in the SVG (and HTML) code. FORD won't recognize this because the double brackets are removed. But even if we could somehow keep the double brackets in the SVG (i.e. `my_function(function)`), this still wouldn't work because FORD assumes a bare string enclosed in double brackets, adds the HTML link stuff (the `` tags, etc.)

At first I thought that this should be solved on the plantuml side so I posted [a question](https://forum.plantuml.net/15098/hyperlinks-with-double-brackets-in-the-url) on the plantuml forum. However, after studying the code I realize this also needs some changes to side in order to intra-doc links that are already in the form of a HTML hyperlink. So it's probably best to handle this completely on the FORD side.

Unfortunately plantuml doesn't like four sets of brackets (`[[[[my_function(function)]]]]`), and will raise a syntax error. A possible solution would be to allow an alternative syntax, e.g. double pipes `||mylink||` and change FORD to handle links like `my_function(function)`. However, this will require FORD to distinguish between the different parts of the hyperlink: the URL, the title, and the hover text. But perhaps there's better solution.

Anyway, if we can decide on an approach, I'd be happy to implement it and submit a PR.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.