<?xml version="1.0" encoding="UTF-8"?>
<!--
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You under the Apache License, Version 2.0
  (the "License"); you may not use this file except in compliance with
  the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">

<document>
  <header>
    <title>AsciiArtSVGGenerator in Cocoon</title>
    <version>0.9</version>
    <type>Technical document</type>
    <authors>
      <person name="Bernhard Huber" email="huber.at.apache.org"/>
    </authors>
    <abstract>This document describes the AsciiArtSVGGenerator of Cocoon.</abstract>
  </header>
  <body>
    <s1 title="AsciiArtSVGGenerator">
      <table>
        <tr>
          <td>NAME</td><td>asciiart-svg</td>
        </tr>
        <tr>
          <td>WHAT</td><td>The <code>AsciiArtSVGGenerator</code> component is used 
            to serve ascii art text as SVGserve data.
          </td>
        </tr>
        <tr>
          <td>TYPE</td><td>Generator, Sitemap Component</td>
        </tr>
        <tr>
          <!-- choose Core, the block name, or Scratchpad 
            depending on where AsciiArtSVGGenerator sources live
          -->
          <td>BLOCK</td><td>Block-Mail/Scratchpad</td>
        </tr>
        <tr>
          <td>CLASS</td><td>org.apache.cocoon.generation.asciiart.AsciiArtSVGGenerator</td>
        </tr>
        <!-- uncomment folling tr iff AsciiArtSVGGenerator is deprecated -->
        <!--tr>
          <td>DEPRECATED</td><td>Cocoon 2.0, 2.1</td>
        </tr-->
        <tr>
          <td>SINCE</td><td>Cocoon 2.1</td>
        </tr>
        <tr>
          <td>CACHEABLE</td><td>yes</td>
        </tr>
      </table>
    </s1>
    <s1 title="Description">
      <p>
        The <code>AsciiArtSVGGenerator</code> reads a plain ascii text document
        and generates SVG/XML SAX events.
      </p>
    </s1>
    <s1 title="Usage">
      <p>
        The <code>AsciiArtSVGGenerator</code> can be used to serve
        figural information in a quick, and simple way. 
      </p>
      <p>
        The following snippet represents an ascii art which can be served
        by <code>AsciiArtSVGGenerator</code>
      </p>
      <source><![CDATA[
 +==============+  
 |  Mail_Header |  
 |  +========+  |  
 |  | Body   |  |  
 |  +==+==+==+  |  
 |  |a |a |a |  |  
 |  |1 |2 |3 |  |  
 |  +==+==+==+  |  
 +==============+  
]]></source>
      <p>
        Storing this as <code>image/asciiart/mail.txt</code>, and using
        the matching snippet below, the mail ascii art can get embedded
        in your document as
      </p>
      <source><![CDATA[
<p> Talking about mail ....</p>
<figure alt="Mail Structure" src="image/asciiart/mail.png"/>
      ]]></source>

      <s2 title="Sitemap pipeline examples">
        <p>
          The snippet below matches URI of the format
          <code>image/asciiart/*.png</code>, and 
          serves them from ascii art files from the directory
          <code>resources/asciiart/*.txt</code>.
        </p>
        <source><![CDATA[
<map:match pattern="image/asciiart/*.png">
  <map:generate type="asciiart-svg" 
    src="resources/asciiart/{1}.txt">
    <!-- option sitemap parameters -->
  </map:generate>
  <map:serialize type="svg2png"/>
</map:match>
        ]]></source>
      </s2>
      
      <s2 title="Sitemap component configuration example">
        <p>
          The snippet below declares the <code>AsciiArtGenerator</code>
          in the sitmap components section.
        </p>
        <source><![CDATA[
<map:generators...
  <map:generator name="asciiart-svg" 
    src="org.apache.cocoon.generation.AsciiArtSVGGenerator"
    logger="sitemap.generator.asciiart-svg" 
  />
    <!-- optional generator configuration -->
    ...
</map:generators>
...
]]></source>
      </s2>
      <s2 title="Configuration">
        <p>
          The <code>AsciiArtGenerator</code> has no configurational options.
        </p>
      </s2>
      <s2 title="Setup">
        <p>
          Setting up the <code>AsciiArtGenerator</code> is simply specifying
          the plain ascii text source.
        </p>
        <p>
          Moreover following sitemap parameters are accepted
        </p>
        <table>
          <tr><th>Parametername</th><th>Default</th><th>Comment</th></tr>
          <tr><td>line-attribute</td><td><![CDATA[stroke:black; stroke-width:1.5]]></td>
            <td>Style of generated SVG lines</td></tr>
          <tr><td>text-attribute</td><td><![CDATA[font-size: 12; font-family:Times Roman; fill:blue;]]></td>
            <td>Style of generated SVG text</td></tr>
          <tr><td>x-grid</td><td>10</td>
            <td>X Grid size</td></tr>
          <tr><td>y-grid</td><td>12</td>
            <td>Y Grid size</td></tr>
        </table>
      </s2>
      <s2 title="Effect on Object Model and Sitemap Parameters">
        <p>
          The <code>AsciiArtGenerator</code> has no side effects on the
          objectModel, or other sitemap parameters.
        </p>
      </s2>
    </s1>
    <s1 title="Bugs/Caveats">
      <p>
        The <code>AsciiArtGenerator</code> is a quick shot, and 
        does not handle all characters visually consistently.
      </p>
    </s1>
    <s1 title="History">
      <p>
        01-05-02: initial creation
      </p>
    </s1>
    <s1 title="See also">
      <p>
        Read more information about 
        <link href="http://www.w3.org/TR/SVG/">SVG</link>,
        and about 
        <link href="http://cocoon.apache.org/2.1/userdocs/svg-serializer.html">SVG Serializer</link>
        family.
      </p>
    </s1>
  </body>
</document>

