;;; links.skb -- Links and cross-references. ;;; -*- coding: iso-8859-1 -*- ;;; ;;; Copyright 2008, 2012 Ludovic Courtès ;;; 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 . ;*---------------------------------------------------------------------*/ ;* 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* [ --> (skribe-url-index :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: