linking
Planet Earth

Earth is the third planet from the Sun and the fifth largest.

Planet Profile

        orbit:    149,600,000 km (1.00 AU) from Sun
        diameter: 12,756.3 km
        mass:     5.972e24 kg

History of Earth

Earth is the only planet whose English name does not derive from Greek/Roman mythology. The name derives from Old English and Germanic. There are, of course, hundreds of other names for the planet in other languages. In Roman Mythology, the goddess of the Earth was Tellus - the fertile soil (Greek: Gaia, terra mater - Mother Earth).

It was not until the time of Copernicus (the sixteenth century) that it was understood that the Earth is just another planet.

Earth, of course, can be studied without the aid of spacecraft. Nevertheless it was not until the twentieth century that we had maps of the entire planet. Pictures of the planet taken from space are of considerable importance; for example, they are an enormous help in weather prediction and especially in tracking and predicting hurricanes. And they are extraordinarily beautiful.

The Earth is divided into several layers which have distinct chemical and seismic properties (depths in km):

         0-  40  Crust
        40- 400  Upper mantle
       400- 650  Transition region
       650-2700  Lower mantle
      2700-2890  D'' layer
      2890-5150  Outer core
      5150-6378  Inner core

Links with different syntax

Doxygen manual

Inline Links

For an inline link the link text is followed by a URL and an optional link title which together are enclosed in a set of regular parenthesis. The link title itself is surrounded by quotes.

Examples:

[The link text](http://example.net/)
[The link text](http://example.net/ "Link title")
[The link text](/relative/path/to/index.html "Link title")
[The link text](somefile.html)

In addition doxygen provides a similar way to link a documented entity:

[The link text](@ref MyClass)

Reference Links

Instead of putting the URL inline, you can also define the link separately and then refer to it from within the text.

The link definition looks as follows:

[link name]: http://www.example.com "Optional title"

Instead of double quotes also single quotes or parenthesis can be used for the title part.

Once defined, the link looks as follows

[link text][link name]

If the link text and name are the same, also

[link name][]

or even

[link name]

can be used to refer to the link. Note that the link name matching is not case sensitive as is shown in the following example:

I get 10 times more traffic from [Google] than from
[Yahoo] or [MSN].

[google]: http://google.com/        "Google"
[yahoo]:  http://search.yahoo.com/  "Yahoo Search"
[msn]:    http://search.msn.com/    "MSN Search"

Link definitions will not be visible in the output.

Like for inline links doxygen also supports @ref inside a link definition:

[myclass]: @ref MyClass "My class"

Actual Results

Provided below, the code = its result ?= expected/desired result

  1. Native "\ref"
    1. \ref iron = Iron Element ?= Iron Element
    2. \ref iron "ferrum" = ferrum ?= ferrum
  2. Markdown inline
    1. [ferrum](\ref iron) = ferrum ?= ferrum
    2. [ferrum](\ref iron "Iron Element") = ferrum ?= ferrum
  3. Markdown Reference
    1. Definition [iron]: \ref iron
    2. [ferrum][iron] = ferrum ?= ferrum
    3. [iron][] = iron ?= iron
    4. [iron] = iron ?= Iron Element
  4. Markdown Reference 1
    1. Definition [iron-1]: \ref iron "ferrum"
    2. [latin ferrum][iron-1] = latin ferrum ?= latin ferrum
    3. [iron-1][] = iron-1 ?= iron-1
    4. [iron-1] = ferrum ?= ferrum
  5. Markdown Reference 2
    1. Definition [iron-2]: \ref iron (ferrum)
    2. [latin ferrum][iron-2] = Iron Element (ferrum) "latin ferrum"
    3. [iron-2][] = Iron Element (ferrum) "iron-2"
    4. [iron-2] = Iron Element (ferrum) "iron-2"
  6. Markdown Reference 3
    1. Definition [iron-3]: \ref iron 'ferrum'
    2. [latin ferrum][iron-3] = Iron Element 'ferrum' "latin ferrum"
    3. [iron-3][] = Iron Element 'ferrum' "iron-3"
    4. [iron-3] = Iron Element 'ferrum' "iron-3"
  7. Markdown Reference 4
    1. Definition [iron-4]: \ref iron.
    2. [latin ferrum][iron-4] = Iron Element. "latin ferrum"
    3. [iron-4][] = Iron Element. "iron-4"
    4. [iron-4] = Iron Element. "iron-4"

Comment

The syntax [iron]: \ref iron supports only the [iron-1]: \ref iron "ferrum" double-quoted form for link text, compliant with \ref command specification.

In my opinion the name given to a page is not really meant to be a "human descriptive text", but more a "machine variable", I think Doxygen should replace the variable with its content: the title instead of the page id. This behaviour is already implemented for the \ref command.

Instead markdown syntax tends to use the page name without any possibility to retrieve automatically the title. Pretend I have many markdown links to iron page, where the page title is replicated in each occurrences: [Iron Element][iron]. If I change the page title, I need to go through all its references to update the link text. I think we need Doxygen to use the page title if a link text is not specified, instead of the page name itself as it is doing now.

To summarize, like for the \ref: if a link text is not specified, the page title is used instead. The same applies to group. If a title is given of course.

In details