src/documentation/content/xdocs/hssf/hacking-hssf.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!--
   3    ====================================================================
   4    Licensed to the Apache Software Foundation (ASF) under one or more
   5    contributor license agreements.  See the NOTICE file distributed with
   6    this work for additional information regarding copyright ownership.
   7    The ASF licenses this file to You under the Apache License, Version 2.0
   8    (the "License"); you may not use this file except in compliance with
   9    the License.  You may obtain a copy of the License at
  10
  11        http://www.apache.org/licenses/LICENSE-2.0
  12
  13    Unless required by applicable law or agreed to in writing, software
  14    distributed under the License is distributed on an "AS IS" BASIS,
  15    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16    See the License for the specific language governing permissions and
  17    limitations under the License.
  18    ====================================================================
  19 -->
  20 <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
  21
  22 <document>
  23     <header>
  24         <title>Hacking HSSF</title>
  25         <authors>
  26             <person email="user@poi.apache.org" name="Glen Stampoultzis" id="GJS"/>
  27             <person email="acoliver@apache.org" name="Andrew Oliver" id="AO"/>
  28         </authors>
  29     </header>
  30     <body>
  31         <section><title>Where Can I Find Documentation on Feature X</title>
  32             <p>
  33                 You might find the
  34                 'Excel 97 Developer's Kit' (out of print, Microsoft Press, no
  35                 restrictive covenants, available on Amazon.com) helpful for
  36                 understanding the file format.
  37             </p>
  38             <p>
  39                 Also useful is the <link href="http://sc.openoffice.org/excelfileformat.pdf">open office XLS spec</link>.  We
  40                 are collaborating with the maintainer of the spec so if you think you can add something to their
  41                 document just send through your changes.
  42             </p>
  43         </section>
  44         <section><title>Help, I Can't Find Feature X Documented Anywhere</title>
  45             <ol>
  46                 <li>
  47                 Look at OpenOffice.org or Gnumeric sources if its implemented there.
  48                 </li>
  49                 <li>
  50                 Use org.apache.poi.hssf.dev.BiffViewer to view the structure of the
  51                 file.  Experiment by adding one criteria entry at a time.  See what it
  52                 does to the structure, infer behavior and structure from it.  Using the
  53                 unix diff command (or get cygwin from www.cygwin.com for windows) you
  54                 can figure out a lot very quickly. Unimplemented records show up as
  55                 'UNKNOWN' and prints a hex dump.
  56                 </li>
  57             </ol>
  58         </section>
  59         <section><title>Low-level Record Generation</title>
  60             <p>
  61                 Low level records can be time consuming to created.  We created a record
  62                 generator to help generate some of the simpler tasks.
  63             </p>
  64             <p>
  65                 We use XML
  66                 descriptors to generate the Java code (which sure beats the heck out of
  67                 the PERL scripts originally used ;-) for low level records.  The
  68                 generator is kinda alpha-ish right now and could use some enhancement,
  69                 so you may find that to be about 1/2 of the work.  Notice this is in
  70                 org.apache.poi.hssf.record.definitions.
  71             </p>
  72         </section>
  73         <section><title>Important Notice</title>
  74             <p>One thing to note:  If you are making a large code contribution we need to ensure
  75             any participants in this process have never
  76             signed a "Non Disclosure Agreement" with Microsoft, and have not
  77             received any information covered by such an agreement.  If they have
  78             they'll not be able to participate in the POI project.  For large contributions we
  79             may ask you to sign an agreement.</p>
  80         </section>
  81         <section><title>What Can I Work On?</title>
  82             <p>Check our <link href="../todo.html">todo list</link> or simply look for missing functionality.  Start small
  83             and work your way up.</p>
  84         </section>
  85         <section><title>What Else Should I Know?</title>
  86             <p>Make sure you <link href="../getinvolved/index.html">read the contributing section</link>
  87             as it contains more generation information about contributing to POI in general.</p>
  88         </section>
  89     </body>
  90 </document>