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

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