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

1 files changed, 28 insertions, 2 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
 	       '()