doc/parts/extensions/index.sxml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <?xml-stylesheet type="text/xsl" href="formats/html.xsl"?>
   3
   4 <!-- This file is part of Shapes.                                           -->
   5 <!--                                                                        -->
   6 <!-- Shapes is free software: you can redistribute it and/or modify         -->
   7 <!-- it under the terms of the GNU General Public License as published by   -->
   8 <!-- the Free Software Foundation, either version 3 of the License, or      -->
   9 <!-- any later version.                                                     -->
  10 <!--                                                                        -->
  11 <!-- Shapes is distributed in the hope that it will be useful,              -->
  12 <!-- but WITHOUT ANY WARRANTY; without even the implied warranty of         -->
  13 <!-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the          -->
  14 <!-- GNU General Public License for more details.                           -->
  15 <!--                                                                        -->
  16 <!-- You should have received a copy of the GNU General Public License      -->
  17 <!-- along with Shapes.  If not, see <http://www.gnu.org/licenses/>.        -->
  18 <!--                                                                        -->
  19 <!-- Copyright 2008, 2009, 2014 Henrik Tidefelt                             -->
  20
  21
  22 <book>
  23         <title>Standard extensions</title>
  24         <description>
  25                 <p>Descriptions of the <str-Shapes /> extension files included in standard installations.</p>
  26         </description>
  27         <meta-selflink><part-href name="extensions" /></meta-selflink>
  28         <base href=<!--#expand-next-string-->"$(BASE)" />
  29         <examples-home href=<!--#expand-next-string-->"$(EXAMPLES)" />
  30         <shapes-version number=<!--#expand-next-string-->"$(SHAPES_VERSION)" />
  31         <top>
  32                 <p>A <str-Shapes /> <em>extension</em> is a <str-Shapes /> source that provides functionality that can be used in applications.  An extension should only introduce bindings, and not produce any output by modifying any program states.</p>
  33                 <p>Extensions are usually activated by loading the source using the <inline>##need</inline> scanner directive, see <a part="syntax" id="syntax/include/include" /> for more details.</p>
  34                 <p>A well-organized extension should place all bindings of its public interface inside a single namespace, and this namespace will be referred to as the <em>public namespace</em> of the extension.  The public namespace will be presented separately in the documentation, and will not be repeated for each documented binding.  For example, the <a extension="circle" /> extension places all bindings in the <namespace name="Shapes" /> namespace, so rather than talking about <inline>Shapes..circle</inline> the documentation will simply say <inline>circle</inline>.  Note that it is not even possible to document the bindings as absolute, like <inline>..Shapes..circle</inline>, since the user may wrap the extension inside another namespace to avoid naming collisions.</p>
  35         </top>
  36
  37         <section id="extensions/index">
  38                 <title>Index</title>
  39                 <body>
  40                         <p>The following extensions are contained in the documentation:</p>
  41                         <index-of-books />
  42                 </body>
  43         </section>
  44
  45         <external>
  46         </external>
  47 </book>