Using links and anchors in User Manual

Help User Manual
,
1

Recently @emyoulation and @kmikkels asked me to help translate the Gramps Glossary wikipage into Danish. This led to questions about how we use links in the documentation. So I would like to discuss this subject in details especially with regards to translations.

A link is defined in double square brackets [[ … ]], e.g. [[Gramps_6.0_Wiki_Manual_-_Navigation]] to link to the Navigation chapter or [[Gramps_6.0_Wiki_Manual_-_Navigation#Using_Gramplets]] to link to a specific section in the Navigation chapter.

When we translate we usually add a two letter language code to the chapter name. For the Danish translation the Navigation chapter becomes [[Da:Gramps_6.0_brugsanvisning_-_Navigation]]

An alternative way is to add a language code using /xx, so [[Gramps_6.0_Wiki_Manual_-_Navigation]] would become [[Gramps_6.0_Wiki_Manual_-_Navigation/da]]. As it is today the [[Gramps_6.0_Wiki_Manual_-_Navigation/da]] is a page that redirect to the [[Da:Gramps_6.0_brugsanvisning_-_Navigation]] page.
I think this is the most used method for translated pages. However, I have also seen that some pages are translated directly in the [[Gramps pagename/xx]].

So question - do we have a preferred method for linking to translated pages?

And to make things more complex. A link points to an anchor. The anchor is defined by using any number of equal signs, e.g. === Using Gramplets ===. In the Danish translation this will become === Brug af Gramplets ===. In some situations it is an advantage to keep the English anchor together with the translated anchor. This can be achieved by using the html tag <span>. So surrounding the translated anchor with a span it looks like <span id="Using Gramplets">=== Brug af Gramplets ===</span>. It’s not particular readable, but it make it possible to link to the same section using either the English link with a language code as well as using the translated link.

When translating pages should we always add a span with the English text. It makes it more difficult to maintain the translated pages, but there are some benefits.

I call a link like [[Gramps_6.0_Wiki_Manual_-_Navigation#Using_Gramplets]] a fully qualified link. But if the link is pointing to a section on the same page, there’s a short hand version that can be used: [[#Using_Gramplets]]. From my perspective it makes the page source more readable, but almost all links today pointing to an anchor on the same page are fully qualified links.

Can we agree on using the short hand version whenever possible?

1 Like
2

I am not certain, but I suspect that the headers must be on a line by themselves.

So that should be:

<span id="Using Gramplets">
=== Brug af Gramplets ===
</span>

One side effect of these linebreaks is that the ID is in the previous section when using the section editor. (As opposed to the whole page editor.) And using the section editor is preferred because you have less worry of 2 WikiContributors editing the same document at the same time, undoing each other’s changes.

You could put the open span tag after the header. But the the autoscroll to anchor would have the header text scrolled off the top… and the header text is important for readers re-orienting themselves after a big scroll jump.

3

The shorthand version is preferred to the full pagename version. (Pedantically, a fully qualified could be interpreted as including the domain and possibly the https:// too.) Not only because of the “readability” issue you mention. But also because the anchor-only shorthand uses the cached page without a reload. The other can force a page reload. So… the shorthand version creates less server burden.

Note: if you are linking an anchor without a the bar (| which overrides the default label) parameter, do NOT use the underscore [[#Using Gramplets]]. Otherwise, the underscore will be visible in the hyperlinked text.

4

I have been experimenting a little bit with headings and spans.
I think the best way of including the English anchor in the translated heading is to have the span inside the heading.
This means that the example

<span id="Using Gramplets">
=== Brug af Gramplets ===
</span>

can be written as

=== <span id="Using Gramplets"/> Brug af Gramplets ===

Note that the span tag don’t need an end tag when using a slash as the last character

The span can also be placed after the translated header text, which might be a bit more readable when editing the manual.

=== Brug af Gramplets  <span id="Using Gramplets"/> ===
3 Likes