|
|
Hyperlinks and References
|
|
Scribe enables 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 Scribe documents.
- Specific part of other Scribe documents, such as a chapter
of another Scribe document.
In order to use hyperlinks, Scribe documents must:
- Refer to marks. This is the role of the ref
Scribe function.
- Set marks. This is the role of the mark
function. However, most Scribe 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.
This function sets a mark that can be referenced to in
a hyperlink. The argument id must be a string. This string
will be used in a ref function call to point to that mark.
The Scribe functions chapter, section, subsection, subsubsection
automatically set a mark whose identifier is the title of the section.
It is possible to refer to figures introduced by the Scribe
function figure using their
:legend value. If the figure was passed a :id argument
then the value of that argument must be used instead of the
:legend one.
| (ref [:url #f] [:id #f] [:mark #f] [:chapter #f] [:section #f] [:subsection #f] [:subsubsection #f] [:bib #f] [:bib+ '()] [:number #f] [:scribe #f] . body) | Scribe function |
Here is a description of the arguments to ref:
| argument | description |
|---|
| :url |
An URL, that is, a location of another file, such as an HTML file. |
| :id |
A reference whose label is :id. This reference can be a
chapter, section, subsection,
subsubsection or a mark |
| :chapter |
The name of a chapter. |
| :mark |
The name of a mark. That mark has been introduced by a
mark function call. |
| :section |
The name of a section. |
| :subsection |
The name of a subsection. |
| :subsubsection |
The name of a subsubsection. |
| :bib |
The name of a bibliography entry. |
| :bib+ |
A list of names of bibliography entry. |
| :number |
If #t the chapter, section, subsection, and
subsubsection number are included in the rendering of the
reference. |
| :scribe |
The name of a Scribe Url Index
file
that contains the reference. The reference can be a chapter,
section, subsection, subsubsection or even
a mark located in the Scribe document described by
the file Sui. It is not contained by the current
document. If no scribe argument is provided, the
reference is located in the current document. |
| body | A Scribe expression that is the visual part of the
hyperlink. If the value the value of body
is #t an automatic text is computed. This text depends on
the back-end. For instance, the HTML back-end, uses the title for
references to chapters and sections while the TeX back-end uses there number.
If not provided or if it is #f the automatic text is prefixed with
the kind of the reference, such as "Section" or "Chapter". |
The example:
[This hyperlink points to the ,(mmark :mark "daemon" "figure")
of the chapter ,(ref :chapter "Standard Library").
,(linebreak)
That other one points to a well known ,(ref :url "http://slashdot.org/" "url").] |
produces:
| (mailto [:email #f] body) | Scribe function |
The function mailto introduces mail annotation in a Scribe
document.
The example:
[It is possible to send a mail ,(mailto :email "foo@nowhere.com" "clicking")
that link.] |
produces:
| It is possible to send a mail clicking
that link. |
A Scribe Url Index (henceforth Sui) describes the
marks that are available in a Scribe document. It is to be used to
make Scribe marks available to other Scribe documents. The syntax
of a Sui file is:
<sui> --> (scribe-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 Scribe compiler.
For instance, in order to produce the Sui file of this user
manual, one should write:
$ scribe user.scr -o user.sui |
|