diff options
Diffstat (limited to 'skribe/doc/user/links.skb')
| -rw-r--r-- | skribe/doc/user/links.skb | 152 |
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 |