Links in the documentation

[Johan Enell]

I think we should discuss how the links are used in the documentations because there are some inconsistencies. As an example, ​chapter 6.2.

First there is two types of links here. The first one is a typical www link, the link to the menubar. A blue clickable text. The second link is the is to section 5.4.4 which is between parenthesis. It is clickable and it specifies where in the document it goes.

I think the latter one is the preferred way of doing links.

• It works in both the www version and in a printed copy of the pdf.
• It is clear that it is a side track from the main text. It doesn't break the 'flow' when you read the section.

---

Another issue is the (mis)use of links. Is it really necessary to link to the menubar every time it is mentioned in the text? Just because you can make hyperlinks in html doesn't mean that must...

[Martin Svensson]

The first issue is occurring when a link-tag is used instead of xref-tag for internal links in the documentation. Replacing the link-tags and adjusting the text would make this problem go away.

Second issue:
Would it be a good recommendation to only have a link once in each 1st level subsection(x.x)? There will probably be some exceptions in the text but this will be a guideline to keep down the number of links.

[Martin Svensson]

The misuse of links in the documentation is not fixed with this ticket, instead it is up to each writer to change this when it occurs in the text.

[Martin Svensson]

(In [3791]) Fixes #665 Links in the documentation