src/documentation/content/xdocs/hwpf/docoverview.xml - poi - Git at Google

 <?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.1//EN" "../dtd/document-v11.dtd">

 <document>
  <header>
   <title>Apache POI - HWPF - Java API to Handle Microsoft Word Files</title>
   <subtitle>Word File Format</subtitle>
   <authors>
    <person name="S. Ryan Ackley" email="sackley@cfl.rr.com"/>
   </authors>
  </header>

  <body>
   <section><title>The Word 97 File Format in semi-plain English</title>

    <p>The purpose of this document is to give a brief high level overview of the
       HWPF document format. This document does not go into in-depth technical
       detail and is only meant as a supplement to the Microsoft Word 97-2007
       Binary File Format freely available from
       <link href="http://www.microsoft.com/interop/docs/officebinaryformats.mspx">Microsoft</link>.</p>
    <p>The OLE file format is not discussed in this document. It is assumed that
       the reader has a working knowledge of the POIFS API. </p>

    <section><title>Word file structure</title>
     <p>A Word file is made up of the document text and data structures
        containing formatting information about the text. Of course, this is a
        very simplified illustration. There are fields and macros and other
        things that have not been considered. At this stage, HWPF is mainly
        concerned with formatted text.</p>
    </section>
    <section><title>Reading Word files</title>
     <p>The entry point for HWPF's reading of a Word file is the File Information
        Block (FIB). This structure is the entry point for the locations and size
        of a document's text and data structures. The FIB is located at the
        beginning of the main stream.</p>
     <section><title>Text</title>
      <p>The document's text is also located in the main stream. Its starting
         location is given as FIB.fcMin and its length is given in bytes by
         FIB.ccpText. These two values are not very useful in getting the text
         because of unicode. There may be unicode text intermingled with ASCII
         text. That brings us to the piece table.</p>
      <p>The piece table is used to divide the text into non-unicode and unicode
         pieces. The size and offset are given in FIB.fcClx and FIB.lcbClx
         respectively. The piece table may contain Property Modifiers (prm).
         These are for complex(fast-saved) files and are skipped. Each text piece
         contains offsets in the main stream that contain text for that piece.
         If the piece uses unicode, the file offset is masked with a certain bit.
         Then you have to unmask the bit and divide by 2 to get the real file
         offset. </p>
     </section>
     <section><title>Text Formatting</title>
      <section><title>Stylesheet</title>
       <p>All text formatting is based on styles contained in the StyleSheet.
          The StyleSheet is a data structure containing among other things, style
          descriptions. Each style description can contain a paragraph style and
          a character style or simply a character style. Each style description
          is stored in a compressed version on file. Basically these are deltas
          from another style.</p>
       <p>Eventually, you have to chain back to the nil style which is an
          imaginary style with certain implied values.</p>
      </section>
      <section><title>Paragraph and Character styles</title>
       <p>Paragraph and Character formatting properties for a document's text are
          stored on file as deltas from some base style in the Stylesheet. The
          deltas are used to create a complete uncompressed style in memory.</p>
       <p>Uncompressed paragraph styles are represented by the Pargraph
          Properties(PAP) data structure. Uncompressed character styles are
          represented by the Character Properties(CHP) data structure. The styles
          for the document text are stored in compressed format in the
          corresponding Formatted Disk Pages (FKP). A compressed PAP is referred
          to as a PAPX and a compressed CHP is a CHPX. The FKP locations are
          stored in the bin table. There are seperate bin tables for CHPXs and
          PAPXs. The bin tables' locations and sizes are stored in the FIB.</p>
       <p>A FKP is a 512 byte OLE page. It contains the offsets of the beginning
          and end of each paragraph/character run in the main stream and the
          compressed properties for that interval. The compessed PAPX is based on
          its base style in the StyleSheet. The compressed CHPX is based on the
          enclosing paragraph's base style in the Stylesheet.</p>
      </section>
      <section><title>Uncompressing styles and other data structures</title>
       <p>All compressed properties(CHPX, PAPX, SEPX) contain a grpprl. A grpprl
          is an array of sprms. A sprm defines a delta from some base property.
          There is a table of possible sprms in the Word 97 spec. Each sprm is a
          two byte operand followed by a parameter. The parameter size depends on
          the sprm. Each sprm describes an operation that should be performed on
          the base style. After every sprm in the grpprl is performed on the base
          style you will have the style for the paragraph, character run,
          section, etc.</p>
      </section>
     </section>
    </section>
   </section>
  </body>
 </document>
	<?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.1//EN" "../dtd/document-v11.dtd">

	<document>
	<header>
	<title>Apache POI - HWPF - Java API to Handle Microsoft Word Files</title>
	<subtitle>Word File Format</subtitle>
	<authors>
	<person name="S. Ryan Ackley" email="sackley@cfl.rr.com"/>
	</authors>
	</header>

	<body>
	<section><title>The Word 97 File Format in semi-plain English</title>

	<p>The purpose of this document is to give a brief high level overview of the
	HWPF document format. This document does not go into in-depth technical
	detail and is only meant as a supplement to the Microsoft Word 97-2007
	Binary File Format freely available from
	<link href="http://www.microsoft.com/interop/docs/officebinaryformats.mspx">Microsoft</link>.</p>
	<p>The OLE file format is not discussed in this document. It is assumed that
	the reader has a working knowledge of the POIFS API. </p>

	<section><title>Word file structure</title>
	<p>A Word file is made up of the document text and data structures
	containing formatting information about the text. Of course, this is a
	very simplified illustration. There are fields and macros and other
	things that have not been considered. At this stage, HWPF is mainly
	concerned with formatted text.</p>
	</section>
	<section><title>Reading Word files</title>
	<p>The entry point for HWPF's reading of a Word file is the File Information
	Block (FIB). This structure is the entry point for the locations and size
	of a document's text and data structures. The FIB is located at the
	beginning of the main stream.</p>
	<section><title>Text</title>
	<p>The document's text is also located in the main stream. Its starting
	location is given as FIB.fcMin and its length is given in bytes by
	FIB.ccpText. These two values are not very useful in getting the text
	because of unicode. There may be unicode text intermingled with ASCII
	text. That brings us to the piece table.</p>
	<p>The piece table is used to divide the text into non-unicode and unicode
	pieces. The size and offset are given in FIB.fcClx and FIB.lcbClx
	respectively. The piece table may contain Property Modifiers (prm).
	These are for complex(fast-saved) files and are skipped. Each text piece
	contains offsets in the main stream that contain text for that piece.
	If the piece uses unicode, the file offset is masked with a certain bit.
	Then you have to unmask the bit and divide by 2 to get the real file
	offset. </p>
	</section>
	<section><title>Text Formatting</title>
	<section><title>Stylesheet</title>
	<p>All text formatting is based on styles contained in the StyleSheet.
	The StyleSheet is a data structure containing among other things, style
	descriptions. Each style description can contain a paragraph style and
	a character style or simply a character style. Each style description
	is stored in a compressed version on file. Basically these are deltas
	from another style.</p>
	<p>Eventually, you have to chain back to the nil style which is an
	imaginary style with certain implied values.</p>
	</section>
	<section><title>Paragraph and Character styles</title>
	<p>Paragraph and Character formatting properties for a document's text are
	stored on file as deltas from some base style in the Stylesheet. The
	deltas are used to create a complete uncompressed style in memory.</p>
	<p>Uncompressed paragraph styles are represented by the Pargraph
	Properties(PAP) data structure. Uncompressed character styles are
	represented by the Character Properties(CHP) data structure. The styles
	for the document text are stored in compressed format in the
	corresponding Formatted Disk Pages (FKP). A compressed PAP is referred
	to as a PAPX and a compressed CHP is a CHPX. The FKP locations are
	stored in the bin table. There are seperate bin tables for CHPXs and
	PAPXs. The bin tables' locations and sizes are stored in the FIB.</p>
	<p>A FKP is a 512 byte OLE page. It contains the offsets of the beginning
	and end of each paragraph/character run in the main stream and the
	compressed properties for that interval. The compessed PAPX is based on
	its base style in the StyleSheet. The compressed CHPX is based on the
	enclosing paragraph's base style in the Stylesheet.</p>
	</section>
	<section><title>Uncompressing styles and other data structures</title>
	<p>All compressed properties(CHPX, PAPX, SEPX) contain a grpprl. A grpprl
	is an array of sprms. A sprm defines a delta from some base property.
	There is a table of possible sprms in the Word 97 spec. Each sprm is a
	two byte operand followed by a parameter. The parameter size depends on
	the sprm. Each sprm describes an operation that should be performed on
	the base style. After every sprm in the grpprl is performed on the base
	style you will have the style for the paragraph, character run,
	section, etc.</p>
	</section>
	</section>
	</section>
	</section>
	</body>
	</document>