Initial import of Skribe 1.2d.

Initial import of Skribe 1.2d.


git-archimport-id: lcourtes@laas.fr--2004-libre/skribilo--devel--1.2--base-0

1 files changed, 152 insertions, 0 deletions

diff --git a/doc/user/links.skb b/doc/user/links.skb
new file mode 100644
index 0000000..b454f28
--- /dev/null
+++ b/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