aboutsummaryrefslogtreecommitdiff
path: root/doc/user/links.skb
blob: ae7301c0945f7a954af199c019ab8d0ef30ced4f (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
;;; links.skb  --  Skribe links
;;;
;;; Copyright 2003, 2004  Manuel Serrano
;;;
;;;
;;; This program 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 2 of the License, or
;;; (at your option) any later version.
;;;
;;; This program 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 this program; if not, write to the Free Software
;;; Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
;;; USA.

;*---------------------------------------------------------------------*/
;*    Links and references                                             */
;*---------------------------------------------------------------------*/
(chapter :title "References and Hyperlinks" [
Skribe supports traditional ,(emph "references") (that is, references to some
part of documents) and ,(emph "hyperlinks") (that is visual marks enriching 
texts that enable interactive browsing). Hyperlinks 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.]))

,(paragraph [In order to use hyperlinks, Skribe 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" 

(p [Skribe proposes only one single function for all the 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.])
	      (: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.])
	      (: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))


(example-produce 
 (example :legend "Some references" (prgm :file "src/links1.skb"))
 (disp (include "src/links1.skb"))))

;*---------------------------------------------------------------------*/
;*    mailto ... @label mailto@                                        */
;*---------------------------------------------------------------------*/
(section :title "Electronic mails"

(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" [
,(p [A ,(emph "Skribe Url Index") (henceforth ,(sc "Sui")) describes the
marks that are available in a Skribe document. It is to be used to
make Skribe marks available to other Skribe documents. The syntax
of a ,(sc "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 [,(sc "Sui") files can be automatically produced by the Skribe compiler.
For instance, in order to produce the ,(sc "Sui") file of this user
manual, one should write:])

,(disp :verb #t [
$ skribe user.skb -o user.sui])]))

;; LocalWords:  Hyperlinks HTML URL url