home *** CD-ROM | disk | FTP | other *** search
/ GameStar 2005 May / Gamestar_73_2005-05_dvd.iso / Programy / amaya / amaya-WinXP-9.1.exe / doc / html / Transform.html < prev    next >
Encoding:
Extensible Markup Language  |  2003-04-14  |  8.9 KB  |  229 lines
  1. <?xml version="1.0" encoding="iso-8859-1"?>
  2. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  3.     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  4. <html xmlns="http://www.w3.org/1999/xhtml">
  5. <head>
  6.   <meta name="GENERATOR" content="amaya 7.2, see http://www.w3.org/Amaya/" />
  7.   <title>Using the HTML.trans File</title>
  8.   <style type="text/css">
  9.   </style>
  10.   <link href="style.css" rel="stylesheet" type="text/css" />
  11. </head>
  12.  
  13. <body xml:lang="en" lang="en">
  14.  
  15. <table border="0" width="100%" summary="toc">
  16.   <tbody>
  17.     <tr>
  18.       <td><p><img alt="W3C" src="../images/w3c_home" /> <img alt="Amaya"
  19.         src="../images/amaya.gif" /></p>
  20.       </td>
  21.       <td><p align="right"><a
  22.         href="editing_documents/about_merging_elements.html"
  23.         accesskey="p"><img alt="previous" src="../images/left.gif" /></a> <a
  24.         href="Changing.html" accesskey="t"><img alt="top"
  25.         src="../images/up.gif" /></a></p>
  26.       </td>
  27.     </tr>
  28.   </tbody>
  29. </table>
  30.  
  31. <div id="page_body">
  32. <h1>Using the HTML.trans File</h1>
  33.  
  34. <p>This document is an introduction to the structure transformation mechanism
  35. provided by <strong>Amaya</strong>. It describes the syntax of the
  36. transformation language and the way transformations are performed in the
  37. editor.</p>
  38.  
  39. <p>The file <code>amaya/HTML.trans</code> contains the description of
  40. available transformations. This file can be edited during an
  41. <strong>Amaya</strong> session. It is dynamically parsed when the
  42. transformation procedure is called by the editor,so new transformations can
  43. be added during an editing session.</p>
  44.  
  45. <p><strong>Warning</strong>: As the description of transformations may
  46. contain tags, do<strong>not</strong>edit the <code>HTML.trans</code> file
  47. with <strong>Amaya</strong>. You can use any text editor.</p>
  48. <hr />
  49.  
  50. <h2>Syntax of the Amaya transformation language</h2>
  51.  
  52. <p>Comments begin with<code><strong>!</strong></code>and continue until the
  53. end of the line.</p>
  54.  
  55. <p>The file consists of a list of transformation descriptions. Each
  56. transformation is described by three parts :</p>
  57. <ul>
  58.   <li>a <em>name</em>terminated by a colon
  59.   <strong><code>:</code></strong></li>
  60.   <li>a <em>source pattern</em> terminated by a semi-colon
  61.     <strong><code>;</code></strong></li>
  62.   <li>and a list of <em>rules</em> between braces <strong><code>{
  63.     }</code></strong> , each rule terminated by a semi-colon
  64.     <strong><code>;</code></strong></li>
  65. </ul>
  66.  
  67. <p>The name appears in the <strong>Transform</strong> menu and identifies the
  68. transformation for the end-user.</p>
  69.  
  70. <h3>The pattern</h3>
  71.  
  72. <p>The pattern describes a specific organization of the elements to be
  73. transformed. It acts as a filter over the HTML dtd. The purpose of the
  74. pattern is to identify a particular combination of elements to which the
  75. transformation can be applied. In a pattern it is possible to express
  76. conditions on sequence of tags, on the content of a tag and on the existence
  77. and value of attributes.</p>
  78.  
  79. <p>Formally, a pattern contains HTML tags (possibly with attributes) and some
  80. composition operators:</p>
  81.  
  82. <p><strong><code>|</code></strong>for choice</p>
  83.  
  84. <p><strong><code>,</code></strong>for sibling</p>
  85.  
  86. <p><strong><code>+</code></strong>for sequence</p>
  87.  
  88. <p><strong><code>?</code></strong>for option</p>
  89.  
  90. <p><strong><code>( )</code></strong> for grouping nodes</p>
  91.  
  92. <p>The braces <code><strong>{</strong></code> <code><strong>}</strong></code>
  93. define the content of a node.</p>
  94.  
  95. <p>The symbol <strong><code>*</code></strong> is a token that matches any
  96. element type.</p>
  97.  
  98. <p>It is possible to rename a tag by preceding it with a name followed by a
  99. colon (<strong><code>:</code></strong>).</p>
  100.  
  101. <p>The tag may have attributes. If no value is given for an attribute, an
  102. element is matched if the attribute is present. If a value is specified for
  103. the attribute, an element is matched if the attribute is present and have the
  104. specified value.</p>
  105.  
  106. <p><a href="#L235">Examples</a> of patterns are given at the end of the
  107. document.</p>
  108.  
  109. <h3>The rules</h3>
  110.  
  111. <p>A rule expresses how some elements identified in the pattern are
  112. transformed. A rule has two parts separated by the symbol
  113. <strong><code>></code></strong>:</p>
  114. <ul>
  115.   <li>a source tag or a name defined in the pattern,</li>
  116.   <li>a target tag list, giving the tags to be generated, and the place where
  117.     they are inserted when transforming the source element.</li>
  118. </ul>
  119.  
  120. <p>The target tag list is itself divided into two parts separated by a colon
  121. (<strong><code>:</code></strong>):</p>
  122. <ul>
  123.   <li>the generation location path (identifies the place where new tags have
  124.     to be inserted)</li>
  125.   <li>the list of tags to be generated</li>
  126. </ul>
  127.  
  128. <p>The generation location path is searched in the leftmost branch of the
  129. document tree, starting from the parent of the element matching the highest
  130. symbol of the pattern.</p>
  131.  
  132. <p>In the target tag list, the dot symbol (<code><strong>.</strong></code>)
  133. is used for descending in the tree structure.</p>
  134.  
  135. <p>If the special token star (<code><strong>*</strong></code>) ends the list
  136. of tags to be generated, the source element tag is not changed, but it can be
  137. moved to a different place in the destination.</p>
  138.  
  139. <p>If the source tag or the name in the left part of a rules is present more
  140. than once in the pattern, the rule transforms all the elements matching an
  141. occurrence of the tag in the pattern.</p>
  142. <hr />
  143.  
  144. <h2>Transformation process</h2>
  145.  
  146. <p>When the user chooses the <strong>Transform</strong> command from the
  147. <strong>Edit</strong> menu, Amaya parses the <code>HTML.trans</code> (or the
  148. <code>MathML.trans</code>, etc.) file. Then the selected elements are matched
  149. with the pattern of each transformation. The names of the matched
  150. transformations are proposed to the user in a pop-up menu.</p>
  151.  
  152. <p>If several transformations with the same name match the selected elements,
  153. the higher-level matching transformation is proposed to the user. If several
  154. transformations match at the same level, the first one declared in the
  155. <code>HTML.trans</code> file is proposed. As a consequence, it is recommended
  156. to specify the transformations with specific patterns before the more general
  157. ones.</p>
  158.  
  159. <p>Once a transformation has been chosen by the user, the destination
  160. structure is built according to the rules while selected elements are
  161. traversed.</p>
  162.  
  163. <p>Finally, the contents of the source elements (text and pictures, but also
  164. structured elements) are moved into the produced elements.</p>
  165.  
  166. <p>This transformation process for HTML documents is fully described in <a
  167. href="http://opera.inrialpes.fr/opera/papers9696.html"><em>Interactively
  168. Restructuring HTML Documents</em></a>, a paper presented at the <a
  169. href="http://www5conf.inria.fr/">5th international WWW conference</a> in
  170. Paris, May 96, by CΘcile Roisin and StΘphane Bonhomme.</p>
  171. <hr />
  172.  
  173. <h2><a name="L235" id="L235">Examples</a></h2>
  174. <ul>
  175.   <li>The first example merges several consecutive unnumbered lists (UL) into
  176.     an unique list. 
  177.     <pre>Merge Lists: (ul{li+})+;
  178.     { 
  179.     li > ul:li; 
  180.     }</pre>
  181.     <p>The pattern matches a sequence of unnumbered lists (UL), that contain
  182.     a sequence of items (LI).</p>
  183.     <p>The rule expresses that each time an item is encountered when
  184.     traversing the matched elements, a new LI tag is created within an UL.
  185.     When the rule is first applied, the resulting structure is empty, so
  186.     there is no UL element in which the LI can be created. Therefore an UL is
  187.     first created, then the rule can be applied.</p>
  188.   </li>
  189.   <li>The second example transforms a definition list into a table. 
  190.     <pre>Table: dl{(dt|dd)+}; 
  191.    { 
  192.    dt > <table border=1>.tbody:tr.td; 
  193.    dd > <table border=1>.tbody.tr:td; 
  194.    }</pre>
  195.     <p>The pattern matches any Definition List element (dl).</p>
  196.     <p>The rules explain how the table is incrementally built when the
  197.     structure of the selected definition list is traversed :</p>
  198.     <ul>
  199.       <li>Each dt involves the creation of a new row (tr) in the table
  200.       body.</li>
  201.       <li>Each dd involves the creation of a new cell (td) in the last
  202.         existing row of the table. 
  203.         <p></p>
  204.       </li>
  205.     </ul>
  206.   </li>
  207.   <li>The third example removes a table element, keeping its content
  208.     unchanged but extracted from the table. 
  209.     <pre>Remove Table:
  210. table{?caption,?(body:*{(tr{(td{(?cell_content:*)+}|
  211.                              th{(?cell_content:*)+}
  212.                            )})+})+};
  213.      { 
  214.      caption>h3; 
  215.      cell_content>:*;
  216.      }</pre>
  217.     <p>The pattern matches any table and identifies the content of each cell
  218.     of the table (cell_content).</p>
  219.     <p>The second rule expresses that the contents of each cell have to be
  220.     moved to the place of the original table.</p>
  221.   </li>
  222.   <li>See the file <kbd>amaya/HTML.trans</kbd> for more transformation
  223.     examples.</li>
  224. </ul>
  225. </div>
  226. <hr />
  227. </body>
  228. </html>
  229.