There are some blog posts that I write for myself, to keep track of information and to save myself the trouble of looking.

Mallard’s most interesting feature is it’s ability to link up pages in a number of ways. It is also pretty bewildering to figure out the syntax for <link> tags sometimes, since you have to pick the right attributes and place the link element in the right place.

When I am adding a <link> attribute I like to imagine the text of the link, in blue, in the location of the link(In the pages rendered by yelp). Especially after Shaun made some clarifications on the IRC, this seems like a nice way to visualise a link.

Links are usually of several types, but the texts displayed as a result of the link, from my limited understanding of Mallard, can only be put in two sections:

(Note that text here refers to text in a page rendered by yelp, and not the text in the editable version of the page.)

1)Title links –
Display the title of the linkee in the linker page.
Lead to the linkee.

2)Inline links
Display text enclosed within the inline link tags.
Lead to the linkee, as known from the reference(xref) attribute inside the inline link tags.

Linked page – linkee
Linker page – linker

Visualising Links

I had some title links(explained in the previous post) in landing pages, that were broken when referred to. This as because I hadn’t specified a “role” attribute for these links. Interestingly, the role attribute for a title link mirrors the page that refers to it and not the other way round. So, if for instance you declared a title link in a guide page, and then referred to it in a topic page, it would have the role of a topic, because it links down, it does not link up, and vice versa for topic links.

Further, links are always two way bridges. If page A links to page B, there will be a link in page B to page A.

This is more easily understood if you read this really nice explanation by Shaun, that is true in most ocassions, but sometimes I can’t wrap my head around it:

Guide links can be thought of as up links or links to pages higher up in the hierarchy, topic links are down links or links to pages lower in the hierarchy or pages in the same level of the hierarchy.

So, while declaring title links you could say:

When a page, say, “down-below” has a guide (up) link to another page, say, “high-up-above”, that means “high-up-above” has a topic (down) link to “down-below”.

As a Mallard user, how do you imagine links?