;;; links.skb -- Links and cross-references.
;;; -*- coding: iso-8859-1 -*-
;;;
;;; Copyright 2008, 2012 Ludovic Courtès <ludo@gnu.org>
;;; Copyright 2003, 2004 Manuel Serrano
;;;
;;;
;;; This file is part of Skribilo.
;;;
;;; Skribilo is free software: you can redistribute it and/or modify
;;; it under the terms of the GNU General Public License as published by
;;; the Free Software Foundation, either version 3 of the License, or
;;; (at your option) any later version.
;;;
;;; Skribilo is distributed in the hope that it will be useful,
;;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;;; GNU General Public License for more details.
;;;
;;; You should have received a copy of the GNU General Public License
;;; along with Skribilo. If not, see <http://www.gnu.org/licenses/>.
;*---------------------------------------------------------------------*/
;* Links and references */
;*---------------------------------------------------------------------*/
(chapter :title "References and Hyperlinks"
(p [Skribilo supports traditional ,(emph [cross-references]) (that
is, references to some part of documents) and ,(emph [hyperlinks]) (that
is, visual marks enriching texts that enable interactive
browsing). Hyperlinks and references may point to:
,(itemize (item [Inner parts of a document, such as a section or a figure.])
(item [Other documents, such as Web documents.])
(item [Other Skribe documents.])
(item [Specific part of other Skribe documents, such as a chapter
of another Skribe document.]))
In order to use hyperlinks, Skribilo documents must:
,(itemize (item [,(emph "Refer to") marks. This is the role of the ,(tt "ref")
Skribe function.])
(item [,(emph "Set") marks. This is the role of the ,(tt "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 ,(emph "explicitly") introduce a mark at the
beginning of these constructions in order to refer to them
with an hyperlink.]))])
;*---------------------------------------------------------------------*/
;* mark ... @label mark@ */
;*---------------------------------------------------------------------*/
(section :title "Mark"
(p [The ,(code "mark") function sets a mark in the produced document
that can be referenced to with the ,(markup-ref "ref")
function. Unless a ,(param :text) option is specified, no visible text
in associated with the mark in the generated document.])
(doc-markup 'mark
'((:text "A text associated with the markup.")
(#!rest mark [A string that will be used in a
,(markup-ref "ref") function call to point to that mark.])))
(p [The Skribe functions
,(map (lambda (x y)
(list (markup-ref x) y))
'("chapter" "section" "subsection" "subsubsection")
'(", " ", " ", " " "))
Skribe automatically set a mark whose value is the title of the section.
The Skribe function ,(markup-ref "figure")
automatically sets a mark whose value is the legend of the figure.]))
;*---------------------------------------------------------------------*/
;* ref ... @label ref@ */
;*---------------------------------------------------------------------*/
(section :title "Reference" :ident "refs"
(p [Skribilo proposes a single function that can be used for most references.
This same ,(code "ref") function is used for introducing references to
section, to bibliographic entries, to source code line number, etc.])
(doc-markup 'ref
`((:text [The text that is the visual part the links for
engines that support hyperlinks.])
(:url [An URL, that is, a location of another file,
such as an HTML file.])
(:mark [A string that is the name of a mark. That mark has
been introduced by a ,(markup-ref "mark") markup.])
(:handle [A Skribe node ,(markup-ref "handle").])
(:ident [The identifier of a node (which was specified
as an ,(param :ident) value).])
(:figure [The identifier of a ,(markup-ref "figure").])
(:chapter [The title of a ,(markup-ref "chapter").])
(:section [The title of a ,(markup-ref "section").])
(:subsection [The title of a ,(markup-ref "subsection").])
(:subsubsection [The title of a ,(markup-ref "subsubsection").])
(:page [A boolean enabling/disabling page reference (for
hard copies as produced by the Lout and LaTeX engines).])
(:bib ,[A name or a list of names of
,(ref :chapter "Bibliographies" :text "bibliographic") entry.])
(:bib-table ,[The
,(ref :chapter "Bibliographies" :text "bibliography") where
searching the entry.])
(:sort-bib-refs ,[In case where multiple bibliography
entries are referenced, as in ,(code [(ref :bib
'("smith81:disintegration" "corgan07:zeitgeist"))]),
this should be a two-argument procedure suitable
for sorting. The default procedure sorts references
by number, when ,(markup-ref "the-bibliography") uses
the ,(code [number]) labeling style. If it is
,(code [#f]), then references will not be sorted.])
(:line [A reference to a ,(ref :mark "prog" :text "program")
line number.])
(:skribe [The name of a
,(ref :section "Skribe Url Index" :text "Skribe Url Index")
,(var "file") that contains the reference. The
reference can be a ,(tt "chapter"), ,(tt "section"),
,(tt "subsection"), ,(tt "subsubsection") or even
a ,(tt "mark") located in the Skribe document
described by the ,(var "file") ,(sc "sui").]))
:force-args '(:url :bib :line :skribe)
:see-also '(index numref the-bibliography))
(p [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
,(code "numref") markup is provided to that end:])
(doc-markup 'numref
`((:text [Text preceding the reference number.])
(:ident [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))
(example-produce
(example :legend "Some references" (prgm :file "src/links1.skb"))
(disp (include "src/links1.skb"))))
;*---------------------------------------------------------------------*/
;* mailto ... @label mailto@ */
;*---------------------------------------------------------------------*/
(section :title "Electronic Mail"
(p [The ,(code "mailto") function is mainly useful for electronic
output formats that are able to run a mailing agent. The function ,(tt "mailto")
introduces mail annotation in a Skribe document.])
(doc-markup 'mailto
'((:text [The text that is the visual part the links.])
(#!rest email [The electronic address.])))
(example-produce
(example :legend "Mail address reference" (prgm :file "src/links2.skb"))
(disp (include "src/links2.skb"))))
;*---------------------------------------------------------------------*/
;* Skribe Url Index ... */
;*---------------------------------------------------------------------*/
(section :title "Skribe URL Index"
:ident "sui"
(p [A ,(emph "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
,(param :skribe) option of the ,(markup-ref "ref") markup. The syntax
of a SUI file is:])
(disp :verb #t :bg *prgm-skribe-color* [
<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>)])
(p [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 ,(ref :ident "html-engine" :text [,(tt
[emit-sui]) HTML custom]) to ,(tt [#t]); a ,(tt [user.sui]) file will
then be produced when the manual is compiled to HTML:]
(disp :verb #t
[skribilo -t html -o user.html user.skb])
)))
;;; LocalWords: Hyperlinks HTML URL url
;;; Local Variables:
;;; ispell-local-dictionary: "american"
;;; End:
