summaryrefslogtreecommitdiff
path: root/doc/user/links.skb
blob: 8793e15c9433577ece1159016f75b65953888723 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
;;; 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: