Links

There are many ways to build a link. The most common found in ICG docs are enumerated in Link Cookbook below. The most prevalent link form uses the :ref: role.

.. prefix: splink

.. _icgsphinxhelp-links:

Links
#####

There are many ways to build a link. The most common found in ICG docs are
enumerated in :ref:`splink-cookbook` below.  The
:ref:`most prevalent link form <splink-masterlink>` uses the ``:ref:`` role.

ICG Usage

anchors

Refer to the document on anchors for usage when setting target text for hyperlinks.

label text + anchor form

A general link takes this form:[1]

:ref:ˋlink includes label <this_is_the_target>ˋ

There are more specific kinds of link (to numbered equations, to commands, keywords, FISH functions, etc.) that use other constructions and are described next in the Cookbook.

Link Cookbook

This is a “how to” on a bunch of different kinds of links that may be needed.

Link to a Command – the :cmd: Role, Part I

Links to commands such as model new are quite common.

Links to commands such as :cmd:`model.new` are quite common.

The :cmd: role used here was built by Itasca (not to be found in docs on Docutils/Sphinx). It is quite simple to use. Put a “.” anywhere in a command where there is normally a space when building links.

Link to a Command Keyword – the :cmd: Role, Part II

Links can be built to keywords of commands: geometry assign-groups structure liner.

Links can be built to keywords of commands:
:cmd:`geometry.assign-groups.structure.liner`.

Add keywords to any length with “.” As long as the ordering of the command words/keywords is correct, links will jump to any desired spot in a command reference document.

Link to a FISH Function – the :func: Role

Functions are, if anything, easier: math.cos.

Functions are, if anything, easier: :func:`math.cos`.

Similar to :cmd:, the :func: role is a customization from ICG, so again it isn’t documented in Docutils/Sphinx. FISH function names come with dots and don’t have keywords, so in all cases just put the function name in the :func: role and voila.

Link to a Web Site

Learn about PFC at the PFC Section of Itasca’s web site or visit https://www.itascacg.com/software/pfc.

Learn about |pfc| at the `PFC Section <https://www.itascacg.com/pfc>`_ of
Itasca's web site or visit https://www.itascacg.com/software/pfc.

A well-formed URL is automatically converted to a hyperlink (the second of the links above), no markup required. However, if the address itself is not consequential, it is preferable to fold links into the surrounding text as in the former case ( ˋlabel <url>ˋ_ ). Don’t forget the underscore at the end on those!

Links for Endnotes & Citations

Endnotes and citations have their own construction rules; links for them are special cases described in the topics on endnotes and citations.

Links that Look Like Command Words

When referring to a group of commands one would like the appearance of a command word (e.g., the c geometry commands). Because markup cannot nest in reST, a special usage has been built for this.

When referring to a group of commands one would like the appearance of a
command word (e.g., the |c| :ref:`geometry <geometry-commands>`
commands). Because markup cannot nest in reST, a special usage has been
built for this.

This is built just like a general link using :ref:, except the substitution |c| put in front of the link causes the link label to be rendered in the code-text font.

Links that are Italicized

Italicization is sometimes needed on links too, such as when referring to a named part of the UI (e.g., a link that takes users to documentation on the i Project panel should be italicized).

Italicization is sometimes needed on links too, such as when referring to
a named part of the UI (e.g., a link that takes users to documentation on
the |i| :ref:`Project <theprojectpane>` panel should be italicized).

This is also a customized usage, but in this case the substitution |i| is used to italicize the label text.

Please Don’t

Please do not use ambiguous language for anchor text like “click here” or see “this figure”. When linking to a specific spot in another document—rather than just to the document itself—make sure to indicate both the location and the document where the link will go.

Links to the next three items (figures, tables, and equations) are where this miscue most commonly arises. Good usage for each item is illustrated below in the last link appearing in their respective excerpts.

Links to Figures

The topic on images and figures gives complete usage for figures and images. Links to figures may take the general form or may refer to the figure’s number in its host document using the :fnum: role (for example: see Figure 2 in the PFC ribbon blender example application problem).

The topic on :ref:`images and figures <icgsphinxhelp-figures>` gives
complete usage for figures and images. Links to figures may take the
:ref:`general form <splink-masterlink>` or may refer to the figure's
number in its host document using the ``:fnum:`` role (for example: see
:fnum:`Figure #exap-ribbon-blenderballs` in the |pfc| ribbon blender
:ref:`example application <ribbonblender>` problem).

The :fnum: role is supplied with an extension to Sphinx. Its basic structure is similar to the general link form, except:

• it uses a leading “#” on the anchor with no corresponding trailing “#” where a general link encloses it with “<>”, and

• it “automagically” inserts the required number after the link’s supplied label text.

Links to Tables

Tables are just like figures above, except the role involved is :tnum: not :fnum:. So, for instance, refer to Table 1 in the topic Stress Sign Conventions to avoid a common pitfall when using Itasca software.

:ref:`Tables <icgsphinxhelp-tables>` are just like figures above, except the
role involved is ``:tnum:``, not ``:fnum:``. So, for instance, refer to
:tnum:`Table #tbl-ssconventions` in the topic :ref:`stresssignconventions`
to avoid a common pitfall when using Itasca software.

Links to Equations

The Math topic covers full usage. The typical link to a numbered equation uses the :eq: role. An example: see Equation (3) in the Mohr-Coulomb model description.

The :ref:`Math <icgsphinxhelp-math>` topic covers full usage. The typical
link to a numbered equation uses the ``:eq:`` role. An example: see Equation
:eq:`modelmohreqs1s2s3general` in the :ref:`Mohr-Coulomb model <modelmohr>`
description.

Endnote

[1]

Though valid, a link that only indicates the anchor text like this

:ref:ˋthis_is_the_targetˋ

will only work if the anchor’s target has content that it can identify as the link label to be used (e.g., it works for a rubric but will fail on image or literalainclude.

Also, this form is a little less readable.