Apple II
File Type Notes
_____________________________________________________________________________
                                                  Developer Technical Support

File Type:         $50 (80)
Auxiliary Type:    $8010

Full Name:     AppleWorks GS Word Processor File
Short Name:    AppleWorks GS Word Processor

Revised by:    Matt Deatherage & Dave Lyons                    September 1990
Written by:    Sydney R. Polk & Stephan Schwirzke,                  July 1990
               Claris Corporation
               Matt Deatherage, Apple Computer, Inc.

Files of this type and auxiliary type contain word processor documents from 
AppleWorks GS.
Changes since July 1990:  Corrected the document format to include a count of 
the SaveArray entries, since such a count there is.  Also added a description 
of how to count rulers.
_____________________________________________________________________________

AppleWorks GS is an integrated desktop productivity system for the Apple IIgs 
personal computer.  AppleWorks GS includes a word processor, spreadsheet, data 
base, communications module and page layout module in one program.  The word 
processor (whose file format is described herein) is paragraph-based and 
allows multiple fonts, styles, sizes, colors and rulers.

For more information on AppleWorks GS, contact:

                    Claris Corporation
                    5201 Patrick Henry Drive
                    P.O. Box 58168
                    Santa Clara, CA 95052-8168

                    Technical Support
                    Telephone:  (408) 727-9054
                    AppleLink:  Claris.Tech

                    Customer Relations
                    Telephone:  (408) 727-8227
                    AppleLink:  Claris.CR

The AppleWorks GS file format is copyrighted (C) 1990 by Claris Corporation and 
is printed here with permission.


Definitions

The following definitions are used in this document in addition to those 
defined for all Apple II file types:

Paragraph     An AppleWorks GS paragraph consists of a paragraph header and a 
              carriage return ($0D) with text in between.  The paragraph 
              header is defined later in this Note.

Font change   A font change is signified by the one Byte token $01, followed 
              by the Word new font family number.

Style change  A style change is signified by the one Byte token $02 followed 
              by the new Style Byte.  The format of the Style Byte is 
              included in this section.

Size change   A size change is signified by the one Byte token $03, followed 
              by the Byte new font size.

Color change  A color change is signified by the one Byte token $04, followed 
              by the Byte new color.  The color is an offset (0-15) into 
              QuickDraw II color table number zero.  

Style Byte    A style byte is a Byte of bit flags, defined as follows:

              Bit 7:    Subscript
              Bit 6:    Superscript
              Bit 5:    Reserved for future use
              Bit 4:    Shadow
              Bit 3:    Outline
              Bit 2:    Underline
              Bit 1:    Italic
              Bit 0:    Bold

              When using a Style Byte with QuickDraw II, be sure to mask out 
              bits 6 and 7 as QuickDraw II does not support these styles.

Text Block    The Text Block is how AppleWorks GS stores text in memory.  The 
              format is as follows:

              blockSize  (+000)  Word        The length of this Text Block, 
                                             including the block size.
              blockUsed  (+002)  Word        The number of bytes actually 
                                             used by this Text Block.  
                                             If this is less than blockSize, 
                                             the remaining bytes should be 
                                             ignored. This will not happen on 
                                             disk.
              theText    (+004)  Paragraphs  Paragraphs, as defined in this 
                                             section.

              Paragraphs are stored consecutively within Text Blocks, and a 
              paragraph is not split over two or more Text Blocks.  If there 
              is more than one Text Block, consecutive Text Blocks contain 
              consecutive sets of paragraphs.

Text Block Records
              Text Block Records consist of a Long giving the size followed 
              by a text block.  A Text Block Record is redundant.

Reserved Characters
              ASCII characters $01-$07 have special meaning in an 
              AppleWorks GS WP file and are considered special characters.
              Character $09 has is the Tab character and character $0D is 
              the only paragraph ending character, the Return.

              $01:  Font change   described in this section
              $02:  Style change  described in this section
              $03:  Size change   described in this section
              $04:  Color change  described in this section
              $05:  Page token    to be replaced with the page number of 
                                  this page 
              $06:  Date token    to be replaced with the current ASCII date 
              $07:  Time token    to be replaced with the current ASCII time

Dates and times are in the "Thursday, July 5th, 1989 06:30 PM" 
format.

              $09:  Tab           the tab character
              $0D:  Return        ends a paragraph

Paragraph header
              A paragraph header is seven bytes long:

              firstFont  (+000)  Word        Font family number of the first 
                                             character in the paragraph.
              firstStyle (+002)  Style Byte  The style of the first character 
                                             in the paragraph.
              firstSize  (+003)  Byte        The size (in points) of the 
                                             first character in the paragraph.
              firstColor (+004)  Byte        The color of the first character 
                                             in the paragraph, as an offset 
                                             into QuickDraw II color table 
                                             zero.
              reserved   (+005)  Word        Reserved for future use.

Document header
              A document header is found at the beginning of every AppleWorks 
              GS word processing file.  The header begins at offset zero and 
              is 282 bytes long:

              version    (+000)  Word        The version number of the file 
                                             format.  This is $1011 for 
                                             AppleWorks GS version 1.0v2 
                                             and 1.1.
              headerSize (+002)  Word        Total size of the header in 
                                             bytes.  This is 282 ($11A) for
                                             version $0100.
              refRecSize (+004)  Word        Size of the reference record 
                                             (fields rBits through rColor) in 
                                             bytes.  Always 48 ($30).
              rBits      (+006)  22 Bytes    Each word in rBits 
                                             is a bit flag representing 
                                             the state of one of the 
                                             AppleWorks GS menus when 
                                             the file was saved.  For 
                                             example, if bit 0 of the 
                                             fourth word is clear, then 
                                             the first item in the 
                                             fourth menu was disabled 
                                             when the file was saved.
              rUndo      (+028)  Long        Reserved; set to zero.
              rState     (+032)  Long        Reserved; set to zero.
              rNum       (+036)  Word        Reserved; set to zero.
              rRefCon    (+038)  Long        Reserved; set to zero.
              rChange    (+042)  Long        Reserved; set to zero.
              rPrint     (+046)  Long        Reserved; set to zero.
              rColor     (+050)  Long        Reserved; set to zero.
              cTabSize   (+054)  Word        Size of the color 
                                             table in bytes.  This is 
                                             always 64.  This is twice 
                                             as large as needed; the 
                                             second 32 bytes of color 
                                             table space are reserved 
                                             for future expansion.
              colorTable (+056)  32 Bytes    The QuickDraw II 
                                             color table for this 
                                             document.
              reserved   (+082)  32 Bytes    Reserved for 
                                             future expansion.  The size 
                                             of this field is included 
                                             in cTabSize.
              pRecSize   (+120)  Word        Size of the print 
                                             record in bytes.  This is 
                                             always 160.
              printRecord (+122) 160 Bytes   A Print 
                                             Manager print record for 
                                             this document.

Word Processor Global Variables
              Some global variables for the document are calculated after the 
              file is read; these are marked "reserved."  The total size of 
              the globals is 386 bytes.  The document is actually stored as 
              three documents--the text, the header and the footer, as is 
              described in the "File Structure" section of this Note.  The 
              AppleWorks GS word processor swaps a section of data depending 
              on whether the text, header or footer was showing when the file 
              was saved.  The first section reflects the state of the 
              document at save time and is a duplicate of one of the other 
              three sections, depending on the value of "stuff".  The 
              switched variables are defined in this section as "SwapVars."

              intVersion  (+000)  Word       AWGS WP internal version; 
                                             currently $0002.
              view        (+002)  Word       The current view.  
                                             Possible values are $0000 
                                             for the text, $0001 for the 
                                             header and $FFFF (-1) for 
                                             the footer.
              stuff       (+004)  Word       Indicates which 
                                             sections variables were 
                                             swapped in when the file 
                                             was saved.  Possible values 
                                             are $0000 for the text, 
                                             $0001 for the header and 
                                             $FFFF (-1) for the footer.
              curDate     (+006)  String     The ASCII date 
                                             when the file was saved.  
                                             This field always takes 26 
                                             bytes regardless of the 
                                             length of the string.
              curTime     (+032)  String     The ASCII time 
                                             when the file was saved.  
                                             This field always takes 10 
                                             bytes regardless of the 
                                             length of the string.

              Dates and times are in the "Thursday, July 5th, 1989 06:30 PM" 
              format.

              curPageNum  (+042)  String     The ASCII current 
                                             page number (e.g., "15").  
                                             This field always takes 8 
                                             bytes regardless of the 
                                             length of the string.

              The next seven fields are used in headers and footers for 
              time, date and page tokens.

              docPages    (+050)  Word       Number of pages in 
                                             current document.
              startPage   (+052)  Word       Number with which 
                                             to start pagination.
              reserved    (+054)  Word       Reserved; set to 
                                             zero when writing.
              visRuler    (+056)  Word       Boolean; FALSE ($0000) 
                                             if ruler is not showing, 
                                             TRUE ($0001) if it is.
              reserved    (+058)  Long       Reserved; set to 
                                             zero when writing.
              headerHeight (+062) Word       Height of header 
                                             in pixels; maximum of 110.
              footerHeight (+064) Word       Height of footer 
                                             in pixels; maximum of 110.

              The next 80 bytes are swapped out variables defined in 
              this section:

              currentVars (+066)  SwapVars   80 bytes 
                                             reflecting current 
                                             variables when the document 
                                             was saved.
              docVars     (+146)  SwapVars   The document's variables.
              headerVars  (+226)  SwapVars   The header's variables.
              footerVars  (+306)  SwapVars   The footer's variables.

SwapVars      The SwapVars are variables that are different for the text, 
              header and footer.  The set of SwapVars in docVars is the 
              variables at the time the file was saved.  The remaining three 
              sets of SwapVars apply to their sections of the file.

              reserved    (+000)  Long       Reserved; set to 
                                             zero when writing.
              reserved    (+004)  Long       Reserved; set to 
                                             zero when writing.
              reserved    (+008)  Word       Reserved; set to 
                                             zero when writing.
              lastPrgph   (+010)  Word       The number of the 
                                             last defined paragraph in 
                                             the document.  Paragraphs 
                                             are numbered from one.
              pageSize    (+012)  Word       Page size 
                                             (vertically), in pixels.
              topSpace    (+014)  Word       Top space above 
                                             page, in pixels.
              bottomSpace (+016)  Word       Bottom space below 
                                             page, in pixels.
              paperSize   (+018)  Word       Paper size 
                                             (vertically), in pixels.
              horRulerRes (+020)  Word       Horizontal resolution 
                                             for ruler, in pixels
              oPageRect   (+022)  Word       Offset from paper 
                                             to page rect, horizontally, 
                                             in pixels.
              windPage    (+024)  Word       The page number 
                                             that begins the current 
                                             window.
              lineOffset  (+026)  Word       How far down the 
                                             top page the window starts, 
                                             in pixels.
              firstPrgph  (+028)  Word       Number of the 
                                             paragraph (paragraphs are 
                                             numbered from one) that has 
                                             the first text on this page.
              firstLine   (+030)  Word       Number of the 
                                             first line in this 
                                             paragraph in the window.
              height      (+032)  Word       The height of the 
                                             paragraph before the first 
                                             line, in pixels in the window.
              topSel      (+034)  Word       The paragraph 
                                             number of the topmost 
                                             portion of the selection, 
                                             or zero for no selection.
              topSelLine  (+036)  Word       The line number of 
                                             the topmost portion of the 
                                             selection.
              selOffset   (+038)  Word       The offset into 
                                             the paragraph in bytes of 
                                             the first character of the 
                                             selection.
              reserved    (+040)  Long       Reserved; set to 
                                             zero when writing.
              insFlag     (+044)  Word       Zero for a single 
                                             insertion point, one for a 
                                             selected range.
              caretEnd    (+046)  8 Bytes    End points of the 
                                             caret line.  
              rangePar    (+054)  Word       The paragraph number of the 
                                             end of the selection.
              rangeLine   (+056)  Word       The line number of 
                                             the end of the selection.
              rangeOffset (+058)  Word       The offset of the 
                                             end of the selection
              stylePending (+060) Boolean Word
                                             TRUE if the current font 
                                             has been changed but 
                                             nothing has been typed.
              fontID      (+062)  Long       The font ID of the 
                                             current font.
              color       (+066)  Word       The low byte is the current 
                                             color byte (0-15); the 
                                             high byte is zero.
              topPrgphLine (+068) Word       The top paragraph 
                                             on the screen.
              topLine     (+070)  Word       The top line of the paragraph 
                                             on the screen.
              topPB       (+072)  Word       Top page boundary--
                                             the page number of the top 
                                             line in the window.
              bottomPrgph (+074)  Word       Paragraph number of the 
                                             bottom paragraph on screen 
              bottomLine  (+076)  Word       Bottom line on screen
              bottomPB    (+078)  Word       Bottom page boundary--
                                             the page number of the 
                                             bottom line in the window.

SaveArray entry
              In the main document there will be one entry in a SaveArray for 
              each paragraph in the document.  Each entry is 12 bytes:

              textBlock   (+000)  Word       Text Block number.  
                                             Text Blocks are numbered 
                                             from zero in the document; 
                                             this entry shows in which 
                                             text block this paragraph 
                                             can be found.
              offset      (+002)  Word       Adding this value 
                                             to the offset of the text 
                                             block gives the beginning 
                                             of the paragraph.
              attributes  (+004)  Word       $0000 = Normal text, 
                                             $0001 = page break paragraph.
              rulerNum    (+006)  Word       Number of the 
                                             ruler associated with this 
                                             paragraph.  If this 
                                             paragraph is a page break 
                                             paragraph, ignore this field.
              pixelHeight (+008)  Word       Height of this 
                                             paragraph in pixels.
              numLines    (+010)  Word       Number of lines in 
                                             this paragraph.

Ruler         Each paragraph has a ruler associated with it; the rulers are 
              stored in the order in which they appear in the document and are 
              numbered consecutively beginning with zero.  Rulers are 52 bytes 
              long and have the following structure:

              numParagraphs (+000) Word      The number of paragraphs 
                                             using this ruler.
              statusBits  (+002)  Flag Word  Bits 15-8:  Reserved for 
                                                         future use.
                                             Bit 7:      Full justification
                                             Bit 6:      Right justification
                                             Bit 5:      Center justification
                                             Bit 4:      Left justification
                                             Bit 3:      Paragraph cannot 
                                                         break pages if this 
                                                         bit is set.
                                             Bit 2:      Triple spaced 
                                                         (really double)
                                             Bit 1:      Double spaced 
                                                         (really one and 
                                                         one half)
                                             Bit 0:      Single spaced
              leftMargin  (+004)  Word       Left margin in 
                                             pixels from the left edge 
                                             of the window.
              indentMargin (+006) Word       Indent margin in 
                                             pixels from the left edge 
                                             of the window.
              rightMargin (+008)  Word       Right margin in 
                                             pixels from the left edge 
                                             of the window.
              numTabs     (+010)  Word       This will be a 
                                             number from one to ten; 
                                             there is always at least 
                                             one tab.
              tabRecs     (+012)             10 Tab Records
                                             A tab record is defined in 
                                             the following section.

Because rulers are defined consecutively from zero, you can use the SaveArray 
entries to find the total number of rulers.  Look at the ruler number for each 
SaveArray entry; the highest-numbered ruler you find is an indication of the 
ruler count.  For example, if the highest rulerNum in any SaveArray entry is 
$0003, there are four rulers in the document.

Tab Record    A tab record identifies the type of tab in a ruler:

              tabLocation (+000)  Word       The location of the tab, 
                                             in pixels, from the left edge 
                                             of the screen.
              tabType     (+002)  Word       The type of tab.  
                                             $0000 is a left tab; $0001 
                                             is a right tab, and -1 ($FFFF) 
                                             is a decimal tab, which 
                                             centers around period characters.


File Format and Structure

The AppleWorks GS Word Processor file is composed of sections defined in 
"Definitions."  The document structure is as follows:

              docHeader   (+000)  Document Header
              globals     (+282)  WP Globals
              docSACount  (+668)  Word       Number of SaveArray 
                                             entries to follow
              docSaveArray (+670) SaveArray entries
                                             One entry for each paragraph
              docRulers   (+xxx)  Rulers     The rulers start here.  
                                             "xxx" is at +670 + 12* the 
                                             number of paragraphs.
              docTextBlocks (+yyy) Text Block Records
                                             The text block records start 
                                             here.  Note that when saved to 
                                             disk, there is no extra space in 
                                             a Text Block so the size is 
                                             equal to the used field.  
                                             "yyy" is at "xxx"+52*number of 
                                             rulers.
              headSaveArray       SaveArray entries
                                             SaveArray entries for this 
                                             document's header.  The offset 
                                             depends on the length of the 
                                             document's text blocks.
              headRulers          Rulers     The rulers for the header.
              headTextBlocks      Text Block Records
                                             The text for the header.
              footSaveArray       SaveArray entries
                                             The SaveArray entries for this 
                                             document's footer.
              footRulers          Rulers     The rulers for the footer.
              footTextBlocks      Text Block Records
                                             The text for the footer.

Please note that the number of paragraphs stored in the document is always one 
greater than the number displayed in the window.  The last character is always 
a Return character.  The number of carriage returns displayed is equal to the 
number of carriage returns stored minus one.  This is so all of the paragraphs 
are guaranteed to end in a carriage return internally.

Blank document sections have a zero in the lastPrgph field of the SwapVars and 
have no save arrays, rulers, or text blocks.

The maximum number of paragraphs in a document is 64K-1 (65,535) and the 
maximum number of characters in a paragraph is 64K-13 (65,523), giving a 
maximum theoretical document size of a healthy 4,294,049,805 characters.

Further Reference
_____________________________________________________________________________
  o  Apple IIgs Toolbox Reference, Volumes 1 through 3

