4. Skribilo User Manual — References and Hyperlinks
Contents↑ Skribilo User Manual

Skribilo supports traditional cross-references (that is, references to some part of documents) and hyperlinks (that is, visual marks enriching texts that enable interactive browsing). Hyperlinks and references may point to:

In order to use hyperlinks, Skribilo documents must:

4.1 Mark

The mark function sets a mark in the produced document that can be referenced to with the ref function. Unless a :text option is specified, no visible text in associated with the mark in the generated document.

(mark [:text] [:class "mark"] [:ident] mark)
:ident The node identifier. html lout latex context info xml
:class The node class. html lout latex context info xml
:text A text associated with the markup.
mark A string that will be used in a ref function call to point to that mark.

The Skribe functions chapter, section, subsection, subsubsection Skribe automatically set a mark whose value is the title of the section. The Skribe function figure automatically sets a mark whose value is the legend of the figure.


4.2 Reference

Skribilo proposes a single function that can be used for most references. This same ref function is used for introducing references to section, to bibliographic entries, to source code line number, etc.

(ref [:sort-bib-refs bib-sort-refs/number] [:page] [:skribe] [:line] [:handle] [:mark] [:figure] [:url] [:bib-table (*bib-table*)] [:bib] [:subsubsection] [:subsection] [:section] [:chapter] [:text] [:ident] [:class])
:ident The node identifier. html lout latex context info xml
:class The node class. html lout latex context info xml
:text The text that is the visual part the links for engines that support hyperlinks. html lout latex context info
:url An URL, that is, a location of another file, such as an HTML file. html lout latex context info xml
:mark A string that is the name of a mark. That mark has been introduced by a mark markup. html lout latex context info
:handle A Skribe node handle. html lout latex context info
:ident The identifier of a node (which was specified as an value). html lout latex context info xml
:figure The identifier of a figure. html lout latex context info
:chapter The title of a chapter. html lout latex context info
:section The title of a section. html lout latex context info
:subsection The title of a subsection. html lout latex context info
:subsubsection The title of a subsubsection. html lout latex context info
:page A boolean enabling/disabling page reference (for hard copies as produced by the Lout and LaTeX engines). lout latex context info
:bib A name or a list of names of bibliographic entry. html lout latex context info xml
:bib-table The bibliography where searching the entry.
:sort-bib-refs In case where multiple bibliography entries are referenced, as in (ref :bib '("smith81:disintegration" "corgan07:zeitgeist")), this should be a two-argument procedure suitable for sorting. The default procedure sorts references by number, when the-bibliography uses the number labeling style. If it is #f, then references will not be sorted.
:line A reference to a progprogram line number. html lout latex context info xml
:skribe The name of a Skribe Url IndexSkribe Url Index file that contains the reference. The reference can be a chapter, section, subsection, subsubsection or even a mark located in the Skribe document described by the file sui. html lout latex context info xml

Sometimes, it is useful to produce phrases that refer a section by its number, as in ``See Section 2.3''. This is especially useful on printed documents, as produced by the Lout and LaTeX engines. The numref markup is provided to that end:

(numref [:class] [:separator "."] [:page] [:text ""] [:ident])
:ident The node identifier. html lout latex context info xml
:class The node class. html lout latex context info xml
:text Text preceding the reference number.
:ident The identifier of the node (a chapter, section, subsection, etc.) being referenced. html lout latex context info xml
:page A boolean enabling/disabling page reference (for hard copies as produced by the Lout and LaTeX engines).
:separator The separator between numbers.
See also ref .
Ex. 22: Some references

... produces:

This hyperlink points to the figure of the chapter Standard Markups (or also, the chapter about markups). In the second example of reference, no :text option is specified: 1. One may use the :ident field when specified such as: fig1 or .
That other one points to a well known url. The same without :text: http://slashdot.org/.
And one can also refer to sections by number, as in ``see Wonderful Section 4.2''.
With more complex tricks that are explained in Section [?section Resolve: ./src/links1.skb:19:2:], it is also possible use, for the text of the reference, a container number such as chapter: 3.

4.3 Electronic Mail

The mailto function is mainly useful for electronic output formats that are able to run a mailing agent. The function mailto introduces mail annotation in a Skribe document.

(mailto :text [:class "mailto"] [:ident] email)
:ident The node identifier. html lout latex context info xml
:class The node class. html lout latex context info xml
:text The text that is the visual part the links. html lout latex context info
email The electronic address.
Ex. 23: Mail address reference

... produces:

It is possible to send a mail by clicking that link. That same reference without :text options: foo@nowhere.com.

4.4 Skribe URL Index

A Skribe URL Index (henceforth SUI) describes the marks that are available in a Skribe or Skribilo document. It is to be used to make marks available to other Skribe/Skribilo documents through the :skribe option of the ref markup. The syntax of a SUI file is:

<sui>     --> (skribe-url-index <title>
                :file <file-name>
                (marks <sui-ref>*)
                (chapters <sui-ref>*)
                (section <sui-ref>*)
                (subsection <sui-ref>*)
                (subsubsection <sui-ref>*))
<sui-ref> --> (<string> :file <file-name> :mark <string>)

SUI files can be automatically produced by the Skribilo compiler. For instance, in order to produce the SUI file of this user manual, one should set the emit-sui HTML custom to #t; a user.sui file will then be produced when the manual is compiled to HTML:

skribilo -t html -o user.html user.skb


(made with skribilo)