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
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:

( 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 .



[
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. 24: 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.



[
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. 25: 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)