| References and Hyperlinks |
|---|
|
|
|
Skribe supports traditional references (that is, references to some
part of documents) and hyperlinks (that is visual marks enriching
texts that enable interactive browsing). Hyperlinks may point to
- Inner parts of a document, such as a section or a figure.
- Other documents, such as Web documents.
- Other Skribe documents.
- Specific part of other Skribe documents, such as a chapter
of another Skribe document.
In order to use hyperlinks, Skribe documents must:
- Refer to marks. This is the role of the ref
Skribe function.
- Set marks. This is the role of the mark
function. However, most Skribe functions that introduce text
structures (e.g., chapters, sections, figures, ...)
automatically introduce marks as well. So, it is
useless to explicitly introduce a mark at the
beginning of these constructions in order to refer to them
with an hyperlink.
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 [:ident] [:class "mark"] [:text] mark) |
| ident | html latex xml | The node identifier. |
| class | html latex xml | The node class. |
| 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.
Skribe proposes only one single function for all the references.
This same ref function is used for introducing references to
section, to bibliographic entries, to source code line number, etc.
| prototype |
|---|
(ref [:class] [:ident] [:text] [:chapter] [:section] [:subsection] [:subsubsection] [:bib] [:bib-table (default-bib-table)] [:url] [:figure] [:mark] [:handle] [:line] [:skribe] [:page]) |
| ident | html latex xml | The node identifier. |
| class | html latex xml | The node class. |
| text | html latex | The text that is the visual part the links for
engines that support hyperlinks. |
| url | html latex xml | An URL, that is, a location of another file,
such as an HTML file. |
| mark | html latex | A string that is the name of a mark. That mark has
been introduced by a mark markup. |
| handle | html latex | A Skribe node handle. |
| ident | html latex xml | A reference to a node who has been specified
an value. |
| figure | html latex | The name of a figure. |
| chapter | html latex | The name of a chapter. |
| section | html latex | The name of a section. |
| subsection | html latex | The name of a subsection. |
| subsubsection | html latex | The name of a subsubsection. |
| page | latex | A boolean enabling/disabling page reference. |
| bib | html latex xml | A name or a list of names of
bibliographic entry. |
| bib-table | | The
bibliography where
searching the entry. |
| line | html latex xml | A reference to a progprogram
line number. |
| skribe | html latex 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. |
index |
Example:
[This hyperlink points to the ,(ref :figure "The great Penguin" :text "figure")
of the chapter ,(ref :chapter "Standard Markups") (or also, the
,(ref :ident "Standard 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)
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. 20: Some references
Produces:
This hyperlink points to the figure
of the chapter Standard Markups3 (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/.
With more complex tricks that are explained in Section
[?section Resolve: user/src/links1.skb:678], it is also possible use, for the text of the
reference, a container number such as chapter:
3. |
|
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 [:ident] [:class "mailto"] email) |
| ident | html latex xml | The node identifier. |
| class | html latex xml | The node class. |
| text | html latex | The text that is the visual part the links. |
email | The electronic address. |
Example:
[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. 21: Mail address reference
Produces:
A Skribe Url Index (henceforth Sui) describes the
marks that are available in a Skribe document. It is to be used to
make Skribe marks available to other Skribe documents. 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 Skribe compiler.
For instance, in order to produce the Sui file of this user
manual, one should write:
$ skribe user.skb -o user.sui
|
|
|