doc: Documented `slide-topic' and `slide-subtopic'.

* doc/user/slide.skb (Slide): Renamed to `Slides and Slide Topics'.
  Added the relevant markup documentation.

* doc/user/src/slides.skb: Added an introduction and a slide topic.

git-archimport-id: lcourtes@laas.fr--2005-libre/skribilo--devo--1.2--patch-46

2 files changed, 46 insertions, 14 deletions

diff --git a/doc/user/slide.skb b/doc/user/slide.skb
index ec2186a..a7d5263 100644
--- a/doc/user/slide.skb
+++ b/doc/user/slide.skb
@@ -62,7 +62,7 @@ second one tells Skribe to generate slides for the LaTeX prosper package.])
 ;*---------------------------------------------------------------------*/
 ;*    slide ... @label slide@                                          */
 ;*---------------------------------------------------------------------*/
-(section :title "Slide"
+(section :title "Slides and Slide Topics"
    
    (p [A ,(code "slide") function call creates a slide.])
    
@@ -79,6 +79,32 @@ the vertical space size between the title and the body of the slide.])
 list ,(code "(split blinds box wipe dissolve glitter)").])
 		 (:bg [The background color of the slide.])
 		 (:image [The background image of the slide.]))
+	       :source "skribilo/package/slide.scm")
+   
+    (p [Optionally, one may group slides into ,(emph [topics]) and
+,(emph [subtopics]).  Topics and subtopics are just logical grouping
+under a given title that are meant to provide structure to a set of
+slides.  With their ,(code [:outline?]) option, these two markups can be
+used to automatically produce an outline at the beginning of each new
+(sub)topic, so that the audience knows what the talk is heading to.])
+   
+   (doc-markup 'slide-topic
+	       `((:title [The title of a topic.])
+	         (:outline? [A boolean (i.e., ,(code [#t]) or ,(code
+[#f])) telling whether an outline should be produced at the beginning of
+this topic.  The outline will typically list the titles of the different
+topics, as well as the titles of the slides under the current topic.]))
+	       :source "skribilo/package/slide.scm")
+   
+   (p [The ,(code [slide-subtopic]) markup is similar:])
+
+   (doc-markup 'slide-subtopic
+	       `((:title [The title of a subtopic.])
+	         (:outline? [A boolean (i.e., ,(code [#t]) or ,(code
+[#f])) telling whether an outline should be produced at the beginning of
+this subtopic.  The outline will typically list the titles of the
+different subtopics, as well as the titles of the slides under the
+current subtopic.]))
 	       :source "skribilo/package/slide.scm"))
 
 ;*---------------------------------------------------------------------*/
@@ -87,7 +113,7 @@ list ,(code "(split blinds box wipe dissolve glitter)").])
 (section :title "Pause"
    
    (p [A ,(code "slide-pause") function call introduces a pause in the slide
-projection.])
+projection.  This may not be supported by all engines.])
    
    (doc-markup 'slide-pause
 	       '()
diff --git a/doc/user/src/slides.skb b/doc/user/src/slides.skb
index 1606e91..e5e6896 100644
--- a/doc/user/src/slides.skb
+++ b/doc/user/src/slides.skb
@@ -6,22 +6,28 @@
 	      :address (ref :url "http://www.inria.fr/mimosa/Manuel.Serrano"))
 
    (if (engine-format? "html")
-       (slide :title "Table of contents" :number #f :toc #f
+       (slide :title "Table of Contents" :number #f :toc #f
 	  (toc :chapter #f :section #f :subsection #f :subsubsection #f)))
 ;;;	       :slide #t)))
+  
+   (slide :title "Introduction" :vspace 0.3
+      
+      (p [This is a simple slide, not grouped in any topic.]))
 
-   (slide :title "X11 client" :toc #t :vspace 0.3
+   (slide-topic :title "Interactive Features" :outline? #t
 
-      (itemize
-	 (item "xlock")
-	 (item "xeyes")
-	 (item "xterm")))
+     (slide :title "X11 client" :toc #t :vspace 0.3
 
-   (slide :title "Xclock" :toc #t :vspace 0.3
+	(itemize
+	   (item "xlock")
+	   (item "xeyes")
+	   (item "xterm")))
 
-      (center (sf (underline "The Unix xclock client")))
-      (slide-vspace 0.3)
+     (slide :title "Xclock" :toc #t :vspace 0.3
 
-      (slide-pause)
-      (slide-embed :command "xlock"
-		   :alt (frame "Can't run embedded application"))))
+	(center (sf (underline "The Unix xclock client")))
+	(slide-vspace 0.3)
+
+	(slide-pause)
+	(slide-embed :command "xlock"
+		     :alt (frame "Can't run embedded application")))))