Skribilo User Manual

Contents

Mark
Reference
Electronic Mail
Skribe URL Index

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:

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, Skribilo 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.

(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. 22: 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. 23: 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