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.

prototype
`(mark [:text] [:class "mark"] [:ident] mark)`
option	engines	description
:ident	html lout latex context xml	The node identifier.
:class	html lout latex context xml	The node class.
:text		A text associated with the markup.
argument		description
`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.

prototype
`(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])`
option	engines	description
:ident	html lout latex context xml	The node identifier.
:class	html lout latex context xml	The node class.
:text	html lout latex context	The text that is the visual part the links for engines that support hyperlinks.
:url	html lout latex context xml	An URL, that is, a location of another file, such as an HTML file.
:mark	html lout latex context	A string that is the name of a mark. That mark has been introduced by a mark markup.
:handle	html lout latex context	A Skribe node handle.
:ident	html lout latex context xml	The identifier of a node (which was specified as an value).
:figure	html lout latex context	The identifier of a figure.
:chapter	html lout latex context	The title of a chapter.
:section	html lout latex context	The title of a section.
:subsection	html lout latex context	The title of a subsection.
:subsubsection	html lout latex context	The title of a subsubsection.
:page	lout latex context	A boolean enabling/disabling page reference (for hard copies as produced by the Lout and LaTeX engines).
:bib	html lout latex context xml	A name or a list of names of bibliographic entry.
: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	html lout latex context xml	A reference to a progprogram line number.
:skribe	html lout latex context 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.
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:

prototype
`(numref [:class] [:separator "."] [:page] [:text ""] [:ident])`
option	engines	description
:ident	html lout latex context xml	The node identifier.
:class	html lout latex context xml	The node class.
:text		Text preceding the reference number.
:ident	html lout latex context xml	The identifier of the node (a chapter, section, subsection, etc.) being referenced.
: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. 21: 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:], 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.

prototype
`(mailto :text [:class "mailto"] [:ident] email)`
option	engines	description
:ident	html lout latex context xml	The node identifier.
:class	html lout latex context xml	The node class.
:text	html lout latex context	The text that is the visual part the links.
argument		description
`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. 22: 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