From 68dc047208a7f772bef055a6a22c0444d2348d35 Mon Sep 17 00:00:00 2001 From: =?utf8?q?G=C3=A1bor=20K=C3=B6vesd=C3=A1n?= Date: Thu, 23 Aug 2012 17:43:47 +0000 Subject: [PATCH] - Add new documentation --- slides/doc/Makefile | 17 +- slides/doc/slides.xml | 1449 ++++++++++++++++++++++++++++++++++++++--- slides/doc/user.css | 6 + 3 files changed, 1379 insertions(+), 93 deletions(-) create mode 100644 slides/doc/user.css diff --git a/slides/doc/Makefile b/slides/doc/Makefile index 82c61597c..b3b469009 100644 --- a/slides/doc/Makefile +++ b/slides/doc/Makefile @@ -1,14 +1,17 @@ include ../../buildtools/Makefile.incl -VPATH = ../xsl/html -all: index.html param.html +all: index.html s5.html slidy.html + cp ../files ./ + cp ../images ./ index.html: slides.xml - $(XSLT) $< ../../xsl/html/docbook.xsl $@ + $(XSLT) $< ${XSLNS}/slides/xhtml/plain.xsl $@ -param.html: param.xweb - $(MAKE) -C ../xsl/html param.html - cp ../xsl/html/param.html . +s5.html: slides.xml + $(XSLT) $< ${XSLNS}/slides/xhtml/s5.xsl $@ + +slidy.html: slides.xml + $(XSLT) $< ${XSLNS}/slides/xhtml/slidy.xsl $@ clean: rm -f *.html - + rm -rf images files diff --git a/slides/doc/slides.xml b/slides/doc/slides.xml index 0b73712a9..2c0106e76 100644 --- a/slides/doc/slides.xml +++ b/slides/doc/slides.xml @@ -1,86 +1,1363 @@ - - -
- -The Slides Document Type -$Id$ -NormanWalsh -
ndw@nwalsh.com
 - - - -The Slides Document Type is an XML vocabulary derived from -DocBook. It is used to create presentations (slides, foils, whatever -you call them) in HTML or print. - -Presentations are by nature visual and the Slides stylesheets -provide a wide range of options to control how the transformation from -XML to HTML is performed. - -This document is a first attempt at describing what some of -these options are and how to use them. - -
-Choose a Stylesheet - -At the highest level, you can choose one of five stylesheets: - - - -slides.xsl produces basic slides in HTML, one page -per slide. - - - - -frames.xsl produces slides in HTML using frames. - - - - -tables.xsl produces slides in HTML using tables, one page -per slide. - - - - -w3c.xsl produces basic slides in HTML, one -page per slide, using a navigation style similar to that of most W3C -talks. - - - - -fo-plain.xsl produces basic slides, one -page per slide, for print using XSL Formatting Objects. - - - - -
- -
-Choose your Parameters - -The parameter reference summarizes the -parameters that you can set to change the features of the slides. - -Be aware that some features require JavaScript. Some effort has been taken -to assure that these features work across different browsers on different platforms, -but it is possible that older browsers will not render slides that use JavaScript -correctly. - -
- -
-Process the Slides - -Run your slides source through your favorite XSLT processor using the stylesheet -and parameters you selected. - -View the results in your favorite browser. - -
- -
+ + + + + The DocBook Slides Extension + DocBook Slides + + + Gábor + Kövesdán + + + The DocBook Project + + gabor@kovesdan.org + + 3 Aug 2012 + 5.0 + + 2012 + Gábor Kövesdán + + + + + + Introduction + + + DocBook Slides ... + + + + is a multi-namespace schema extension + to the original DocBook + schema. + + + + was originally created by + NormanWalsh. + + + + and was later redesigned for DocBook 5.0 by + GáborKövesdán. + + + + This document serves for two purposes: + + + + To explain DocBook Slides. + + + + To serve itself as a test document to demonstrate how + slides are marked up and how different output formats are + rendered. + + + + + + + Basic Concepts + + + + + DocBook is an XML grammar to mark up + papers and books and then process them with XML-related standards. + It concentrates on structure and semantics, not layout. + + + + DocBook Slides is an extension for DocBook to create + presentation slides. + + + + By nature, layout is part of a presentation but DocBook Slides + still focuses on structure and semantics. + + + + DocBook Slides uses almost the entire DocBook grammar and + provides only a minimal set of layout-controlling elements. + This keeps is simple and easy to use. + + + + And still, you can copy-paste, use XInclude, etc. + + + + + + + Features of DocBook Slides + + + Let's see some features of DocBook + Slides. + + + + Using Namespaces + + + DocBook Slides uses a separate namespace for its elements. + This has various advantages: + + + + It isolates the extension elements and the original + DocBook schema does not have to know anything about them. + + + + It also avoids name clashes and XML processors can easily + distinguish between the two set of elements. + + + + This modular concept makes it easy to extend the official + stylesheets with specific processing. + + + + + + Easy to Learn + + + If you already know and use DocBook, DocBook Slides is for you: + + + + You can use the usual inline and block elements when marking up + your text, you only have to learn a few new markup elements. + + + + Also, you may include DocBook fragments with XInclude. + Imagine an important table that is part of your scientific + paper and you also want to show it on a conference. + You do not have to copy-paste it but you can just have it in + one single file that you later include in both documents. + + + + + + + Development Status + + + + + DocBook Slides - just like DocBook - is an open source product + and it is under constant development and improvement. + + + + The curently supported output formats are + plain XHTML, S5 XHTML , + W3C HTML Slidy and XSL FO . + In the future, support for other important + output formats (e.g. HTML5, EPUB) may be added. + + + + + + + + Tutorial Examples + + + Let's see some basic examples. + + + + A Minimal Markup 1 + + + +<?xml version='1.0'?> +<dbs:slides xmlns="http://docbook.org/ns/docbook" + xmlns:dbs="http://docbook.org/ns/docbook-slides"> + <title>Presentation Title</title> + + + + + The root element with proper namespace declarations. + + + + It contains the title but can have more. + + + + + + + + A Minimal Markup 2 + + + + + <dbs:foil> + <title>Foil Title</title> + <para>Foil content</para> + </dbs:foil> +</dbs:slides> + + + At least one foil obligatory. + + + + A foil can contain any block element from DocBook. + + + + + + + + The Whole Example + + + Let's see the whole markup together: + + +<?xml version='1.0'?> +<dbs:slides xmlns="http://docbook.org/ns/docbook" + xmlns:dbs="http://docbook.org/ns/docbook-slides"> + <title>Presentation Title</title> + <dbs:foil> + <title>Foil Title</title> + <para>Foil content</para> + </dbs:foil> +</dbs:slides> + + + + + + Grouping Foils + + + We can form groups of logical sets of foils and also add some + introductionary text for them. In the rendered forms, these groups + can have a table of contents of the included slides. You can also + see such groups in this presentation. + + + + Group 1 + + This is an introduction. + + + ... + +]]> + + + + + + + Markup Examples + + + Let's see how to create the particular foils with + DocBook Slides. + + + + Info Content + + + You can wrap the title into the <info> element that + comes from the DocBook schema. It also means you can + add the usual authoring information here: + + + + Group 1 + + + + John + Doe + + FooBar Inc. + + + 2012 + ]]> + + + + + + Block Content + + + + + You have access to all of the block content elements in DocBook, + e.g. you can create a simple paragraph with + <para>, just like in DocBook. + + + + Or you can use lists, like <itemizedlist>. + + + + Or <programlisting> with some code or markup inside. + + + + + Inline Content + + + + + Just like block elements, you can also use inline DocBook + elements to mark up your content on your foils. + + + + For example, you can emphasize + something with <emphasis> or you + can mark literal text as such with + <literal>. + + + + By the way, the inline markup citation above is marked up + with <tag>. + + + + Apart from these, feel free to use the rest of + the markup elements. + + + + + + + FAQ Listings + + + + + + What else can I use to make my slides useful + and practical? + + + + You can include some questions and answers with + <qandaset> and related elements to answer some + frequently asked questions. + + + + + + + + References + + + + + Sometimes you need to add some remarks and some + references to your slide content. + + + + For small remarks, you can use the + <footnote> element to insert a footnote + that will appear on the same foil where it is inserted. + + + + Or for references to external content + - books and websites - you can include one or more + bibliography foils in the end. + + + + On these foils, instead of the usual bulleted points, use the + <bibliography> element and you + will get a nicely formatted reference list. + + + + Use <xref> in the content + to generate a link to the reference entry. + + + + + + + Incremental Slides + + + + + If you set the dbs:incremental attribute ... + + + + ... to 1 on a foil, ... + + + + ... then you will get incremental lists, ... + + + + ... like this if they are supported in the output format. (XHTML-based) + + + + + + + Collapsible Lists + + + You can see a collapsible list below (depending on the output + format). Click on the node to expand it. + + + + + + If you set the dbs:collapsible attribute ... + + + + ... to 1 on a foil, ... + + + + ... then you will get collapsible lists, ... + + + + ... like this if they are supported in the output format. (Slidy) + + + + + + + + + Building Blocks + + + + + Slides are layout-oriented documents; formatting + is a crucial part of them. + + + + DocBook aims to separate structure and layout but for + Slides sometimes it is not entirely possible, yet the + layout-related markup is tried to be kept minimal. + + + + You can use the <dbs:block> element + that will be transformed to a container type in the + generated document (e.g. <div> in HTML). + + + + You can also apply the dbs:style attribute + to blocks and you can even embed them into each other. + + + + Use CSS or extend the XSLT stylesheets to control + renering of your custom blocks. + + + + + + + Block Example + + + + This is the left block. + + + + This is the right block. And it is marked incremental. + + + + + + Images and Formulas + + + + Incremental Images + + + This is only supported in XHTML-based output. + + + + + + + + + + + + + + + + + + + + + + + Embedded SVG + + + You can embed SVG + See http://www.w3.org/TR/SVG11/. + code, like this: + + + +]]> + + + + + + + + + Embedded MathML + + + You can embed MathML + See http://www.w3.org/TR/MathML3/. + code, like this: + + + + 10 + 01 + +]]> + + + + 10 + 01 + + + + + + + + Presentation + + + + + Available Formats + + + + + + StylesheetDescription. + + + + + xhtml/plain.xsl + Single plain XHTML file. + + + + xhtml/slidy.xsl + Single XHTL file in W3C HTML Slidy format. + + + + xhtml/s5.xsl + Single XHTML file in S5 format. + + + + fo/plain.xsl + XSL Formatting Objects for printed output. + + + + + + + + + + Plain XHTML + + + + + It is a simple plain XHTML output with + some classes given on the elements. These let you create your + own CSS stylesheet for the rendering. + + + + It is actually quite similar to the + S5 format with + S5-specific + parts removed. The objective with this format was simplicity + and S5 + already achieves that quite well but in case you do not want + to use that framework, you can create your own one. + + + + The stylesheet to choose for this format is + xhtml/plain.xsl. + + + + + + + W3C HTML Slidy + + + + + W3C HTML Slidy + is an XHTML framework for presentations. + + + + It seems mature and well maintained. + + + + HTML Slidy handles well long content. Its formatting + allows more text on a single foil and even if your text + overflows, you can scroll inside the single foil. It also + supports collapsible lists and a JavaScript clock so that you + do not run out of time. + + + + For HTML Slidy, use + xhtml/slidy.xsl. + + + + + + + S5 Format + + + + + S5 + stands for Simple Standards-Based Slide Show System. + + + + It is yet another XHTML-based framework for slideshows, like + HTML Slidy. + + + + Its JavaScript code behaves somewhat differently and it is less + mature. + + + + It supports incremental lists but in general, it is not so + feature-rich as HTML Slidy. + + + + To create your S5 + presentation, pick the + xhtml/s5.xsl stylesheet. + + + + + + + XSL FO Format + + + + + XSL FO is an XML vocabulary to describe how formatted + output is presented. + + + + It is used here as an intermediate format between DocBook Slides + and printable output. + + + + First, generate the XSL FO document. + + + + Then use your XSL FO processor to render your printable + document in PDF, PostScript, etc. depending on the capabilities of + the software you use. + + + + If you need a free processor, take a look at + Apache FOP . + + + + + + + XSLT Parameters + + + + + The provided stylesheets offer XSLT parameters + to adjust some tunables of the output generation. + + + + The parameters are documented in the documentation + that accompanies the DocBook XSL distribution. + + + + All the DocBook Slides stylesheets are extensions of the + original DocBook stylesheets so adjusting their parameters may also + affect your rendered slides. + + + + + + + Customizations + + + Sometimes parameters are not enough and you need to modify + the templates to achieve your goal. Customizations are easy + to create with XSLT. + + + + Just pick up a stylesheet that you want to customize. + + + + Create a new, empty stylesheet that imports the original + one. + + + + Override the original templates that do not work + in the way you desire. + + + + Of course, this requires some knowledge in XSLT and + you will need to read the code to see what to override. + + + + + + + + Authoring with DocBook Slides 5.0 + + + + + Choosing a Validator + + + + + Once you have some slides marked up in DocBook Slides, + you probably want to make sure your markup is valid. Otherwise, + it is not guaranteed that the output will be generated properly. + For this, you need a validator. + + + + The DocBook Slides schema is described in the RELAX-NG grammar language. + + + + The recommended RELAX-NG validator is + jing . + + + + Alternatively, you can use Emacs/nXML + with the supplied locatingrules.xml file. + + + + + The RELAX-NG validation in the xmllint program from libxml2 is known to have + bugs and does not work correctly with DocBook Slides. + + + + + + Validating Slides + + + + + With jing, run: + jing ~/docbook-slides/slides.rng foo.xml. + + + + For Emacs/nXML, you can put the following into + your emacs.conf: + + + (setq rng-schema-locating-files + (append + '("~/docbook-slides/locatingrules.xml"))) + + Or you can do M-x customize-variable rng-schema-locating-files + and then add the absolute path to the file. + + + + + + + Transforming DocBook Slides Documents + + + + + You need an XSLT processor to transform the documents. + For example, you can use either xsltproc from + libxslt , Xalan + or Saxon. + + + + It is recommended to use xsltproc, since + it is significantly faster than the other two and the DocBook Slides + stylesheets were also tested with it. + + + + Pick the proper stylesheet for your chosen output format. + For example, it is xhtml/slidy.xsl for + HTML Slidy. + + + + Type: xsltproc xsl/slides/xhtml/slidy.xsl foo.xml > foo.html + + + + + + + Rendering Printable Output + + + + + First create the XSL FO document with XSLT: + xsltproc xsl/slides/fo/plain.xsl foo.xml > foo.fo + + + + Then use your XSL FO processor to render the final document. + + + + For example, to render a PDF with Apache FOP, type: + fop foo.fo foo.pdf + + + + + + + + DocBook Slides Limitations + + + + + Foil Content + + + Creating slides is quite different from creating + papers and books. + + + + Presentational slide are layout-oriented by nature as opposed to DocBook, which is + structure-oriented. The content of the foil must fit but there + is no easy way to detect this so this should be checked + and controlled manually. + + + + Formatting of slide content is not necessarily consistent but part + of the design of each foil and illustration used in + the presentation, while an important principle of + DocBook is separating content and styling. To achieve + something very unique, you will probably need heavy + customization. + + + + + + + Animations and Sound Effects + + + DocBook was invented for mostly printed or web + content, while slides are rarely presented in a + printed form. + + + + Slides are usually shown on computer screen or + projector and may heavily use animated or audio content + to support the presentations. + + + + Most of the possible output formats are usually + used in printed form or on the web. The first lacks + the possibility of animated and audio content and the + second one lacks good open standards for doing so. + + + + Maybe a future HTML5 or OpenDocument support + can bring in some new features but for now, you cannot + really use animations and sound. + + + + + + + + Frequently Asked Questions + + + + + Compatibility + + + + + + Is DocBook Slides 5.0 stylesheets compatible with + older versions of DocBook Slides or vice versa? + + + + Not at all, since it is heavily redesigned. But + you can find an XSLT transformation in the + tools/ + directory, which can convert your slides to the new + schema. + + + + + + + + Contribution + + + + + + Can I contribute to the schema or to the stylesheets? + + + + Of course, any contribution that can be useful for + other users and fits the concept of DocBook Slides + is more than welcome. + + + + + + What to do with my contribution? + + + + Please first ask review on + the docbook-apps + mailing list and users and other developers will tell you + what to improve and how to submit your work for inclusion. + + + + + + + + Help + + + + + + How can I get help in using the schema and the + accompanying stylesheets? + + + + There is a + docbook-apps + mailing list for general questions on DocBook and related + technologies. There are numerous users and developers subscribed to + this list, so probably you can get help there. + + + + + + + + + Mini-Reference + + + Here you have the short and informal description of the DocBook + Slides elements. It is not meant to be a full and formalized + referenced but rather a cheatsheet to look at. + + + + dbs:slides + + + + + May contain: db:title, db:titleabbrev, + db:subtitle, db:info, dbs:foilgroup, dbs:foil + + + + Usage: It is the root element that encloses the authoring + info and the particular foils that may be grouped to foil + groups. + + + + + + + dbs:foilgroup + + + + + May contain: db:title, db:titleabbev, + db:subtitle, db:info, [block content], dbs:foil, dbs:speakernotes, + dbs:handoutnotes + + + + Usage: It groups together various foils. It can have its own info + section and an optional introductionary text. Depending on your XSLT + parameters, it may generate a table of contents of enclosed foils. + Its usage is not obligatory but may be very useful for grouping together + logically related foils. It may have some speaker notes and handout notes, as well. + + + + + + + dbs:foil + + + + + May contain: db:title, db:titleabbev, + db:subtitle, db:info, [block content], dbs:speakernotes, + dbs:handoutnotes + + + + Usage: It marks up a single foil. Use + DocBook block elements to mark up your content. It may have some speaker + notes and handout notes, as well. + + + + + + + dbs:block + + + + + May contain: [block content] + + + + Usage: It divides the content into layout units + that can later processed in a specific way. + + + + + + + dbs:speakernotes + + + + + May contain: [block content] + + + + Usage: Notes that are not meant to be presented to + the audience but to the speaker. + + + + + + + dbs:handoutnotes + + + + + May contain: [block content] + + + + Usage: Notes that are not to accompany + printed slides. + + + + + + + Attribute dbs:incremental + + + + + Usage: Makes the content incremental. + Allowed on any element and inherited to child elements + but not applicable everywhere and its effect depends on the output + format. + + + + + + + Attribute dbs:collapsible + + + + + Usage: Makes the content collapsible. + Allowed on any element and inherited to child elements + but not applicable everywhere and its effect depends on the output + format. + + + + + + + Attribute dbs:style + + + + + Usage: Classifies the given element + to a specific formatting class. Typically applicable to foils, + foilgroups and mediaobject. Allowed anywhere but not processed + everywhere. In HTML it naturally maps to the class + attribute. + + + + + + + + Related Standards + + + + Related Standards + + + Extensible Markup Language (XML) + + + W3C + + + http://www.w3.org/TR/REC-xml/ + + + + The DocBook Schema Version 5.0 + + + OASIS + + + http://docs.oasis-open.org/docbook/specs/docbook-5.0-spec-os.html + + + + XSL Transformations (XSLT) Version 1.0 + + + W3C + + + http://www.w3.org/TR/xslt + + + + Extensible Stylesheet Language (XSL) Version 1.1 + + + W3C + + + http://www.w3.org/TR/xsl/ + + + + + + + Supported HTML Presentation Frameworks + + + + Supported HTML Presentation Frameworks + + + S<superscript>5</superscript> + A Simple Standards-Based Slide Show System + + http://meyerweb.com/eric/tools/s5/ + + + + HTML Slidy + Slide Shows in HTML and XHTML + + www.w3.org/Talks/Tools/Slidy2/ + + + + + + + Recommended Tools + + + + Recommended Tools + + + Jing RELAX-NG validator + + http://www.thaiopensource.com/relaxng/jing.html + + + + libxslt + The XSLT C library for GNOME + + http://xmlsoft.org/xslt/ + + + + Apache FOP + + http://xmlgraphics.apache.org/fop/ + + + + diff --git a/slides/doc/user.css b/slides/doc/user.css new file mode 100644 index 000000000..a7ae50c04 --- /dev/null +++ b/slides/doc/user.css @@ -0,0 +1,6 @@ +.face_container {margin-left: 4em; position: relative;} +.face_first {position: static; vertical-align: bottom;} +.face_other {position: absolute; left: 0; top: 0;} + +.left {float: left;} +.right {float: right;} -- 2.40.0