<p style="Normal"><c props="font-family:Times New Roman; text-decoration:none; color:000000; lang:en-GB; text-position:normal; font-weight:normal; font-style:normal; font-size:12pt">The are many ways of writing HTML and it is impossible to please everyone. The exporter has been extensively rewritten several times in order to provide HTML code as clean as possible and there are a number of options, described below, controlling document export.</c><c props="font-family:Times New Roman; text-decoration:none; color:000000; lang:en-GB; text-position:normal; font-weight:normal; font-style:normal; font-size:12pt"></c></p>
<p style="Normal"><c props="font-family:Times New Roman; text-decoration:none; color:000000; lang:en-GB; text-position:normal; font-weight:normal; font-style:normal; font-size:12pt"></c><c props="font-family:Times New Roman; text-decoration:none; color:000000; lang:en-GB; text-position:normal; font-weight:normal; font-style:normal; font-size:12pt">In addition to the XHTML exporter there is a `Multipart HTML' exporter which converts the XHTML output (possibly consisting of several files, i.e., images, style sheet) into a single MIME-encoded file (traditionally with the extension .mht). Some web browsers save web pages in this format.</c></p>
<p style="Heading 3"><c props="lang:en-GB; display:inline; height:0in; width:0in; homogeneous:1">Export as HTML 4.01</c><c props="lang:en-GB; display:inline; height:0in; width:0in; homogeneous:1"></c></p>
<p style="Normal"><c props="lang:en-GB">AbiWord's HTML exporter has always given the user a choice between HTML and XHTML, the latter being XML and thus easier to handle (and ideally to re-import, although this has been an elusive goal). Some people still prefer the traditional HTML, since some browsers don't understand that XHTML is HTML and not just XML (which can almost anything), but increasingly XHTML is preferred and best-understood.</c><c props="lang:en-GB"></c></p>
<p style="Normal"><c props="lang:en-GB">If exporting as HTML then the document will not be declared as XML and markup in the AWML namespace will not be possible, since these options are specific to XHTML.</c><c props="lang:en-GB"></c></p>
<p style="Heading 3"><c props="lang:en-GB">Export with PHP instructions</c><c props="lang:en-GB"></c></p>
<p style="Normal"><c props="lang:en-GB">This option is seldom (if ever) used but may be of interest. Many websites these days use PHP to give webpages a `corporate look and feel' or to provide a dynamic element to layout. HTML documents have simple </c><c props="lang:en-GB"></c><c style="Code" props="lang:en-GB"><?php</c><c props="lang:en-GB"> (or the older </c><c style="Code" props="lang:en-GB"><?</c><c props="lang:en-GB"> ) instructions embedded at the top and bottom and these replace all the site-specific markup. (Often the resulting document is barely recognisable as HTML!)</c></p>
<p style="Normal"><c props="lang:en-GB">If this option is selected then AbiWord inserts </c><c props="lang:en-GB"></c><c style="Code" props="lang:en-GB"><?php include ...</c><c props="lang:en-GB"> statements in the head and at the beginning and end of the body of the HTML document. NOTE: Since some versions of PHP get confused by other processing instructions, such as </c><c style="Code" props="lang:en-GB"><?xml</c><c props="lang:en-GB"> , it may be necessary to uncheck the `Declare as XML' option.</c></p>
<p style="Normal"><c props="lang:en-GB">Unfortunately this is not very customisable and AbiWord's new XHTML template system, available only through command-line conversion of documents to XHTML, can be used to much greater effect.</c><c props="lang:en-GB"></c></p>
<p style="Heading 3"><c props="lang:en-GB">Declare as XML</c><c props="lang:en-GB"></c></p>
<p style="Normal"><c props="lang:en-GB">XML documents, including XHTML ones, normally start with a line declaring them to be XML. This line is something like:</c><c props="lang:en-GB"></c></p>
<p style="Normal"><c props="lang:en-GB"></c><c props="lang:en-GB">Some (old) web browsers see this and get confused, and some versions of PHP also get confused because </c><c style="Code" props="lang:en-GB"><?</c><c props="lang:en-GB"> used to be regarded as a PHP insertion point.</c></p>
<p style="Normal"><c props="lang:en-GB">If saving as HTML then this option is irrelevant; if as XHTML then uncheck this option to suppress the declaration.</c><c props="lang:en-GB"></c></p>
<p style="Heading 3"><c props="lang:en-GB">Allow extra markup in AWML namespace</c><c props="lang:en-GB"></c></p>
<p style="Normal"><c props="lang:en-GB">This option is specific to XHTML since it uses XML namespaces to add extra information to the HTML document. However, </c><c props="lang:en-GB"></c><c props="font-style:italic; lang:en-GB">this is </c><c props="lang:en-GB; text-decoration:underline; font-style:italic">not</c><c props="font-style:italic; lang:en-GB"> correctly functional at the moment and its use is </c><c props="lang:en-GB; text-decoration:underline; font-style:italic">not</c><c props="font-style:italic; lang:en-GB"> recommended</c><c props="lang:en-GB">.</c></p>
<p style="Normal"><c props="lang:en-GB">AbiWord generates a lot of style-sheet information related to document styles and this can be embedded within the HTML document in a </c><c props="lang:en-GB"></c><c style="Code" props="lang:en-GB"><style><!-- --></style></c><c props="lang:en-GB"> section or saved to an external style sheet (</c><c props="font-style:italic; lang:en-GB">filename</c><c props="lang:en-GB">.html_files/style.css). The former is generally more useful; if an external style sheet is used on the website then it may be best to use the PHP option or, if converting from the command line, an XHTML template.</c></p>
<p style="Heading 3"><c props="lang:en-GB">Embed images in URLs (Base64-encoded)</c><c props="lang:en-GB"></c></p>
<p style="Normal"><c props="lang:en-GB">Images in the AbiWord document are normally saved in a subdirectory (</c><c props="lang:en-GB"></c><c props="font-family:Times New Roman; text-decoration:none; color:000000; lang:en-GB; text-position:normal; font-weight:normal; font-style:italic; font-size:12pt">filename</c><c props="font-family:Times New Roman; text-decoration:none; color:000000; lang:en-GB; text-position:normal; font-weight:normal; font-style:normal; font-size:12pt">.html_files/</c><c props="lang:en-GB">) and referenced by hyperlink (</c><c style="Code" props="lang:en-GB"><img src="filename.html_files/ ... </c><c props="lang:en-GB">) but there is a mechanism for saving images within the HTML file itself (although this is generally frowned upon).</c></p>
<p style="Normal"><c props="lang:en-GB">AbiWord-2.0 has a (still experimental) XHTML template mechanism that can be used when using AbiWord as a command-line tool to convert documents to HTML.</c><c props="lang:en-GB"></c></p>
<p style="Normal"><c props="lang:en-GB">The simplest way to convert a file to HTML using AbiWord, on Unix systems at least, is:</c><c props="lang:en-GB"></c></p>
<p style="Command">AbiWord --to=html file.abw</p>
<p style="Normal">which will import <c props="font-style:italic">file.abw</c><c props="font-style:italic"></c> and export as HTML to <c props="font-style:italic">file.html</c> using default options.</p>
<p style="Normal">It is possible, however, to specify export options on the command line using <c style="Code">--exp-props</c><c style="Code"></c>:</p>
<p style="Normal">The above command specifies that the output is to be HTML 4.01 and not XHTML. All six export options can be specified in this manner: <c style="Code">html4</c><c style="Code"></c>, <c style="Code">php-includes</c>, <c style="Code">declare-xml</c>, <c style="Code">use-awml</c>, <c style="Code">embed-css</c> and <c style="Code">embed-images</c>. Each takes a <c style="Code">yes</c> or <c style="Code">no</c>, and multiple options can specified, e.g.:</p>
<p style="Normal">The <c style="Code">--exp-props</c><c style="Code"></c> argument can be used to define an arbitrary number of property name-value pairs. The above six options are <c props="text-decoration:underline; font-weight:normal; font-style:italic">reserved</c> property names; there are two other reserved property names associated with XHTML templates: <c style="Code">html-template</c> and <c style="Code">href-prefix</c>.</p>
<p style="Normal"><c></c>The XHTML template is a skeleton XHTML document which the exporter first imports and then exports again with modifications. The template contains <c props="font-style:italic">Processing Instructions</c><c props="font-style:italic"></c> which instruct the exporter to insert, e.g., the document title or the document text.</p>
<p style="Normal">All of the exporter's processing instructions have the form <c style="Code"><?abi-xhtml- ... ?></c><c style="Code"></c>, e.g.:</p>
<p style="Command"><?abi-xhtml-insert title?></p>
<p style="Command"><?abi-xhtml-insert meta?></p>
<p style="Command"><?abi-xhtml-insert body?></p>
<p style="Normal">In the output, these instructions are replaced with, respectively, the document's title (from the document properties, as text), the document's metadata (document properties, etc., as HTML <c style="Code"><meta ... /></c><c style="Code"></c>), and the document's content (as HTML, inside of the usual <c style="Code"><body>...</body></c>).</p>
<p style="Normal"><c></c>The template system was written primarily for the AbiWord documentation. The goal was to provide a navigation menu for the AbiWord bundled help documentation. This consists of about 100 AbiWord documents, in several folders, which need to be converted to HTML. The navigation menu needed submenus, and the menu item corresponding to the current webpage needed to be highlighted, etc., and all using only HTML, CSS and relative links between webpages, images and style sheets.</p>
<p style="Normal">To achieve this with a single template an element of flow control is necessary, and this is achieved by defining variables in the <c style="Code">--exp-props</c> argument, e.g.:</p>
<p style="Normal">since the <c style="Code">$$</c> in the processing instruction comment text is replaced by he value (<c style="Code">howto</c>) of the specified property (<c style="Code">active-menu</c>).</p>
<p style="Normal">The principal flow-control mechanism, however, is the use of <c style="Code"><?abi-xhtml-if </c><c style="Code" props="font-style:italic">condition</c><c style="Code">?> ... <?abi-xhtml-fi ?></c> where everything between the two processing instructions is ignored if <c style="Code" props="font-style:italic">condition</c> is false. Unfortunately, the condition syntax is currently very limited (e.g., <c style="Code"><?abi-xhtml-if active-menu==howto?></c>) and is likely to be rewritten. (These should be nestable.)</p>
<p style="Normal">Another processing instruction is <c style="Code"><?abi-xhtml-menuitem ...?></c> which creates a table cell of one sort or another with the specified label text.</p>
<p style="Normal">Finally, to make relative links between resources possible, link addresses which start with a <c style="Code">$</c> (e.g., <c style="Code"><a href="$/about.html"></c> and <c style="Code"><img src="$/images/logo.jpg" /></c>) will have the <c style="Code">$</c> substituted with the value of property <c style="Code">href-prefix</c>, e.g.:</p>
<p style="Normal">This tells Abiword to use the template <c props="font-style:italic">normal.html</c> in the current directory and to prefix all links (marked with an initial <c style="Code">$</c>) with the path <c style="Code">..</c> so <c style="Code"><a href="$/about.html"></c> will change to <c style="Code"><a href="../about.html"></c>, and so on.</p>
<p style="Normal">The best example of XHTML template usage is in AbiWord's abiword-docs CVS module in the directory abiword-docs/ABW/en-US/template/.</p>
