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.

prototype
(mark [:text] [:class "mark"] [:ident] mark)
optionenginesdescription
:identhtml lout latex context info xml The node identifier.
:classhtml lout latex context info xml The node class.
:textA text associated with the markup.
argumentdescription
markA 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.

prototype
(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])
optionenginesdescription
:identhtml lout latex context info xml The node identifier.
:classhtml lout latex context info xml The node class.
:texthtml lout latex context info The text that is the visual part the links for engines that support hyperlinks.
:urlhtml lout latex context info xml An URL, that is, a location of another file, such as an HTML file.
:markhtml lout latex context info A string that is the name of a mark. That mark has been introduced by a mark markup.
:handlehtml lout latex context info A Skribe node handle.
:identhtml lout latex context info xml The identifier of a node (which was specified as an value).
:figurehtml lout latex context info The identifier of a figure.
:chapterhtml lout latex context info The title of a chapter.
:sectionhtml lout latex context info The title of a section.
:subsectionhtml lout latex context info The title of a subsection.
:subsubsectionhtml lout latex context info The title of a subsubsection.
:pagelout latex context info A boolean enabling/disabling page reference (for hard copies as produced by the Lout and LaTeX engines).
:bibhtml lout latex context info xml A name or a list of names of bibliographic entry.
:bib-tableThe bibliography where searching the entry.
:sort-bib-refsIn 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.
:linehtml lout latex context info xml A reference to a progprogram line number.
:skribehtml lout latex context info xml 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.
See also
index numref the-bibliography

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:

prototype
(numref [:class] [:separator "."] [:page] [:text ""] [:ident])
optionenginesdescription
:identhtml lout latex context info xml The node identifier.
:classhtml lout latex context info xml The node class.
:textText preceding the reference number.
:identhtml lout latex context info xml The identifier of the node (a chapter, section, subsection, etc.) being referenced.
:pageA boolean enabling/disabling page reference (for hard copies as produced by the Lout and LaTeX engines).
:separatorThe separator between numbers.
See also
ref
[This hyperlink points to the ,(ref :figure "The great Penguin" :text "figure")
of the chapter ,(ref :chapter "Standard Markups") (or also, the
,(ref :ident "std-markups" :text "chapter") about markups). 
In the second example of reference, no ,(code ":text") option is specified: 
,(ref :figure "The great Penguin"). One may use the ,(param ":ident")
field when specified such as: ,(ref :ident "fig1") or ,(ref :figure "fig1").

,(linebreak)
That other one points to a well known 
,(ref :url "http://slashdot.org/" :text "url"). The same without 
,(code ":text"): ,(ref :url "http://slashdot.org/").

,(linebreak)
And one can also refer to sections by number, as in ``see ,(numref :text
[Wonderful Section] :ident "refs")''.

,(linebreak)
With more complex tricks that are explained in Section 
,(ref :section "Resolve"), it is also possible use, for the text of the
reference, a container number such as chapter:
,(resolve (lambda (n e env)
              (let ((s (find1-down (lambda (x)
                                      (and (is-markup? x 'chapter)
                                           (string=? (markup-option x :title)
                                                     "Standard Markups")))
                                   (ast-document n))))
                 (ref :handle (handle s) :text (markup-option s :number))))).]
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: skribilo/documentation/manual.scm:227:], 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.

prototype
(mailto :text [:class "mailto"] [:ident] email)
optionenginesdescription
:identhtml lout latex context info xml The node identifier.
:classhtml lout latex context info xml The node class.
:texthtml lout latex context info The text that is the visual part the links.
argumentdescription
emailThe electronic address.
[It is possible to send a mail by
,(mailto "foo@nowhere.com" :text "clicking") that link. That same
reference without ,(code ":text") options: ,(mailto "foo@nowhere.com").
]
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)