linking
|
Earth is the third planet from the Sun and the fifth largest.
orbit: 149,600,000 km (1.00 AU) from Sun diameter: 12,756.3 km mass: 5.972e24 kg
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
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)
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"
Provided below, the code = its result ?= expected/desired result
\ref iron
= Iron Element ?= Iron Element\ref iron "ferrum"
= ferrum ?= ferrum[iron-1]: \ref iron "ferrum"
[latin ferrum][iron-1]
= latin ferrum ?= latin ferrum[iron-1][]
= iron-1 ?= iron-1[iron-1]
= ferrum ?= ferrum[iron-2]: \ref iron (ferrum)
[latin ferrum][iron-2]
= Iron Element (ferrum) "latin ferrum"[iron-2][]
= Iron Element (ferrum) "iron-2"[iron-2]
= Iron Element (ferrum) "iron-2"[iron-3]: \ref iron 'ferrum'
[latin ferrum][iron-3]
= Iron Element 'ferrum' "latin ferrum"[iron-3][]
= Iron Element 'ferrum' "iron-3"[iron-3]
= Iron Element 'ferrum' "iron-3"[iron-4]: \ref iron.
[latin ferrum][iron-4]
= Iron Element. "latin ferrum"[iron-4][]
= Iron Element. "iron-4"[iron-4]
= Iron Element. "iron-4"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
[](\ref iron)
to produce Iron Element. But it does make sense since the simpler \ref iron
does the job.[iron][]
means [iron][iron]
. The rendering is compliant\ref iron
). Actually the definition line [iron]: \ref iron
states the equivalence