err.no Git - sope/blob - sope-xml/STXSaxDriver/README

   1 # $Id$
   2
   3 Note: this is the initial release, it should contain some bugs ;-)
   4
   5 STXSaxDriver
   6 ============
   7
   8 This project contains a skyrix-xml/SaxObjC SAX driver bundle which can process
   9 so called "structured text" files, or in short "STX". The parsing events are
  10 reported as XHTML tags.
  11
  12 Example:
  13 ---snip---
  14 * item A
  15
  16 * item B
  17 ---snap---
  18 will be reported as SAX events similiar to such an HTML file:
  19 ---snip---
  20 <ul>
  21   <li>item A</li>
  22   <li>item B</li>
  23 </ul>
  24 ---snap---
  25
  26 The basis for this driver bundle, the StructuredText framework, was initially
  27 written by Mirko Viviani and Giulio Cesare Solaroli and sponsored by eXtrapola
  28 Srl.
  29 Note that the "original" StructuredText framework is much more capable and
  30 generic than what this SAX driver provides. On the pro side, your applications
  31 do not need to care about the actual tag format if you use SaxObjC. Your
  32 applications can use either, XHTML, HTML, PYX or STX files using the available
  33 SaxObjC drivers without any additional work.
  34
  35 Supported MIME Types
  36 ====================
  37
  38 Not sure what the correct MIME type for structured text is supposed to be, for
  39 now we register this driver for the
  40
  41   "text/structured"
  42
  43 MIME type.
  44
  45 How to try
  46 ==========
  47
  48 Just use the saxxml or domxml tools which are part of skyrix-xml, eg:
  49
  50   saxxml -XMLReader STXSaxDriver data/hhtest1.stx
  51
  52 This will print the XHTML representation of the STX file on stdout.
  53
  54 STX Functionality which is implemented
  55 ======================================
  56
  57 Guilio writes:
  58 ---snip---
  59 Anyway, we used this document as "reference":
  60
  61   http://plone.org/documentation/howto/FrontPage/UsingStructuredText
  62
  63 of the construct defined there, we have skipped just the table construct.
  64
  65 But we have added a few thinks:
  66 - it is possible to use quotes in link url (es: if you have
  67   "Link":http://www.url.com, the comma will end up into the link; to avoid
  68   this, we can parse a string like that: "Link":'http://www.url.com', and the
  69   comma will be left out of the link).
  70 - link target: they are not a first class citizen (specially in XHTML), but
  71   sometime they are very usefull. To define a target, you can add it after a
  72   link: "Link":'http://www.url.com'::'target'. Also the target can be quoted
  73   in order to avoid problems with punctuation.
  74 - Image link: in order to create a link around an image, we have defined the
  75   following sintax:
  76     ["Alt text":http://www.url.com/image.gif]:'http://www.url.com'.
  77   Here too, quoting and target are supported.
  78 ---snap---
  79
  80 Defaults
  81 ========
  82
  83 STXDebugEnabled          YES|NO
  84 STXSaxDriverDebugEnabled YES|NO
  85
  86 Structured Text Links
  87 =====================
  88
  89 http://www.zope.org/Members/millejoh/structuredText
  90 http://plone.org/documentation/howto/FrontPage/UsingStructuredText
  91
  92 Classes
  93 =======
  94
  95   NSObject
  96     STXSaxDriver < SaxXMLReader >
  97
  98   NSObject
  99     StructuredLine
 100     StructuredStack
 101     StructuredText
 102     StructuredTextRenderingDelegate
 103       StructuredTextRenderingDelegate_XHTML
 104
 105   NSString(STX)