4. Skribe User Manual -- References and Hyperlinks


main page
top:Skribe User Manual
index:Index
markups:Standard Markups


References and Hyperlinks
4.1Mark
4.2Reference
4.3Electronic mails
4.4Skribe Url Index


Chapters
1Getting Started
2Syntax & Values
3Standard Markups
4References and Hyperlinks
5Indexes
6Bibliography
7Computer programs
8Standard Library
9Engines
10Editing Skribe Programs
11Skribe compiler
12Compiling Texi documents
13List of examples
14Table of contents
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.

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 [:ident] [:class] [:text] mark)
optionenginesdescription
:identhtml latex The node identifier.
:classhtml latex 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

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])
optionenginesdescription
:identhtml latex The node identifier.
:classhtml latex The node class.
:texthtml latex The text that is the visual part the links for engines that support hyperlinks.
:urlhtml latex An URL, that is, a location of another file, such as an HTML file.
:markhtml latex A string that is the name of a mark. That mark has been introduced by a mark markup.
:handlehtml latex A Skribe node handle.
:identhtml latex A reference to a node who has been specified an value.
:figurehtml latex The name of a figure.
:chapterhtml latex The name of a chapter.
:sectionhtml latex The name of a section.
:subsectionhtml latex The name of a subsection.
:subsubsectionhtml latex The name of a subsubsection.
:pagelatex A boolean enabling/disabling page reference.
:bibhtml latex A name or a list of names of Bibliographybibliography entry.
:linehtml latex A reference to a progprogram line number.
:skribehtml 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.
See also
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.

4.3 Electronic mails

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)
optionenginesdescription
:identhtml latex The node identifier.
:classhtml latex The node class.
:texthtml latex The text that is the visual part the links.
argumentdescription
emailThe 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:
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 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


This Html page has been produced by Skribe.
Last update Sat Jan 8 08:18:55 2005.