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