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] [:text] mark ) |
:ident | html latex | The node identifier. |
:class | html latex | 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] [:url] [:figure] [:mark] [:handle] [:line] [:skribe] [:page]) |
:ident | html latex | The node identifier. |
:class | html latex | The node class. |
:text | html latex | The text that is the visual part the links for
engines that support hyperlinks. |
:url | html latex | 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 | 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 | A name or a list of names of
Bibliographybibliography entry. |
:line | html latex | A reference to a progprogram
line number. |
:skribe | html latex | 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. It is not
contained by the current document. If no
skribe argument is provided, the
reference is located in the current document. |
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 Markups (or also, the
chapter about markups).
In the second example of reference, no :text option is specified:
The great Penguin. One may use the :ident
field when specified such as: fig1 or fig1.
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], 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] email ) |
:ident | html latex | The node identifier. |
:class | html latex | 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
|
|
|