summaryrefslogtreecommitdiff
path: root/skribe/doc/user/links.skb
diff options
context:
space:
mode:
Diffstat (limited to 'skribe/doc/user/links.skb')
-rw-r--r--skribe/doc/user/links.skb152
1 files changed, 152 insertions, 0 deletions
diff --git a/skribe/doc/user/links.skb b/skribe/doc/user/links.skb
new file mode 100644
index 0000000..b454f28
--- /dev/null
+++ b/skribe/doc/user/links.skb
@@ -0,0 +1,152 @@
+;*=====================================================================*/
+;* serrano/prgm/project/skribe/doc/user/links.skb */
+;* ------------------------------------------------------------- */
+;* Author : Manuel Serrano */
+;* Creation : Thu Sep 11 06:10:44 2003 */
+;* Last change : Thu Feb 26 20:56:48 2004 (eg) */
+;* Copyright : 2003-04 Manuel Serrano */
+;* ------------------------------------------------------------- */
+;* Skribe links */
+;*=====================================================================*/
+
+;*---------------------------------------------------------------------*/
+;* 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 [A reference to a node who has been specified
+ an ,(param :ident) value.])
+ (:figure [The name of a ,(markup-ref "figure").])
+ (:chapter [The name of a ,(markup-ref "chapter").])
+ (:section [The name of a ,(markup-ref "section").])
+ (:subsection [The name of a ,(markup-ref "subsection").])
+ (:subsubsection [The name 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