          STYLCH: A STYLE CHANGING UTILITY FOR WORDSTAR
                        Beta Test Version
                           30 May 1991
                                

                       by John G. Bennett
                           72431,1407


This documentation and the accompanying program are copyright 
1991 by their author, John G. Bennett.  They may be freely dis-
tributed and copied, but not sold or included in any other com-
mercially sold package without the permission of the author.

WordStar is a trademark of WordStar International.

John G. Bennett is not an employee of, a consultant of, or other-
wise connected with WordStar International, except as a user of 
their products.

ACKNOWLEDGEMENTS: I am grateful to James Burton for testing 
STYLCH, and to James Burton and especially Joe Masters of WSI for 
help with undocumented features of the WordStar style library.  I 
am indebted to Robert J. Sawyer, former Associate Sysop of the 
WordStar Forum of CompuServe for the basic idea of using WordStar 
data structures to provide input for utilities which change those 
data structures, for innumerable tips and messages of good advice 
on the WordStar forum, and for his excellent work as a sysop of 
the WordStar Forum.

USING THIS MANUAL: This manual assumes that readers of it are 
familiar with WordStar's paragraph styles.  Many users familiar 
with WordStar will be able to use STYLCH by reading just the USE 
and the CAUTIONS AND LIMITATIONS sections of this manual.  Addi-
tionally, a list of error messages and some technical notes are 
provided.  

USE:  STYLCH is a utility which can be used to make changes to 
many different styles at once in a WordStar 5.5 or 6.0 document.  
To use it to change styles in a document you must first enter the 
changes you want into a special style which has the name "Stylch" 
[the quotation marks are not part of the name].  You can create 
this style using ^OFD in the usual way.  In this style, all 
fields except the name and those items you want to change should 
be blank (you can blank a field with ^Y).  For instance if you 
want to change the left margin and paragraph margin in several 
styles at once, set up the Stylch style so that everything is 
blank except for the left margin field and the paragraph margin 
field; these should contain the new values you wish to have in 
the styles.  Once you've defined the style, use ^K or F10 to 
exit; probably you will not want to save the changes to the 
library, but you may find it handy to have a completely blank 
style, named Stylch, in your style library, which you can modify 
each time you want to use STYLCH.

     Once you've defined the Stylch style, you must insert a tag 
for the style into your document; otherwise the style you created 
will not be saved.  You'll probably want to insert it where it 
can't disturb your formatting; perhaps at the end of the document 
or else immediately before another style tag.  Insert it some-
where where you can conveniently find it later, as you'll proba-
bly want to delete it after running STYLCH.

     Next you must save your document, because STYLCH can only 
work on files, not on documents stored in memory.  You might as 
well ^KD it, because you'll just have to reload it after STYLCH 
finishes, anyway, and STYLCH doesn't take long to work.

    You can run STYLCH by shelling out to DOS unless your system 
is terrifically cramped for memory space; if it is, you'll need 
to exit WordStar to run it.  Either way the DOS command is

           STYLCH documentfile

where, as usual, you may need to add the path for STYLCH if 
you're not logged onto the directory where it resides and it's 
not on your path.  You should supply the full drive, path, and 
file name of your document on the command line.  STYLCH is not 
sophisticated about looking for the file and will give up with an 
error message if it can't find it immediately.

    After STYLCH loads it will announce itself, read your data 
file, and then present you with a list of the styles used in your 
document (or most of them --- see CAUTIONS AND LIMITATIONS).  You 
must mark the styles you wish to change.  To mark a style on the 
list, move the highlight bar to the style you wish to mark using 
either the arrow keys or the WordStar diamond (^E, ^S, ^D, ^X), 
or the Home key (first item on list), or the End key (last item 
on list).  To mark the highlighted style, use the + key; to 
remove the mark, use the - key.  When a style on the list has 
been marked, a triangle appears immediately before the name of 
the style.  When you have finished marking styles, use ^K key or 
the F10 to tell STYLCH you are finished.  At the bottom of the 
screen is a reminder of some of the keys you can use when select-
ing styles to modify.

    Stylch will them make the changes in your file and exit to 
DOS.  You may then reload your document into WordStar and resume 
editing.  All the styles you checked have now been modified by 
inserting into them the values you put in the Stylch style.  
Probably you will want to delete the Stylch style tag; it is no 
longer needed.  You will need to do a global reformat (^QU) to 
see the effects of your changes.  That's all there is to using 
STYLCH.

CAUTIONS AND LIMITATIONS:  Please note the following cautions and 
limitations.  I have tried my best to make STYLCH bug-free and 
safe, but for various reasons, I cannot guarantee that it is.  If 
you discover bugs or have suggestions for improvements, please 
let me know; but note that some of the limitations are a result 
of the design of WordStar, and cannot be remedied in any add-on 
product.

Beta Test Version:  This version is still somewhat experimental.  
I have only a simple computer system, and only WordStar 5.5C to 
test STYLCH on.  I have tried to make it sound, but there are 
often unforeseen bugs when programs are run under conditions 
where they were not tested.  I'll try to fix any bugs I can if 
they are reported, and if I can diagnose them on my hardware.

Styles Not Fully Documented: The published file format documents 
do not give enough detail about the style library in a WordStar 
document to enable one to modify styles in exactly the way Word-
Star does.  I have asked WordStar representatives, but have not 
yet got full details of the workings of the style library, so I 
can't really guarantee that everything will go correctly.  So 
far, the testing and examining I have done leads me to think 
there will be no problem other than the one mentioned below 
involving asterisks, but I cannot be sure what other undocumented 
complications lurk in the style library.

No Inheritance: When you define a style in WordStar, setting a 
field blank means you want the value to be inherited from the 
condition of the text immediately before the style tag was 
placed.  In the special style, Stylch, the program STYLCH inter-
prets that blank as meaning that you do not wish to change the 
value of that field.  Consequently, you cannot use STYLCH to set 
the value of a field to Inherited.  This is a limitation in the 
design of STYLCH for which I see no feasible remedy.

The Body Text Style: The Body Text style is WordStar's default; 
it is the style used when none has been specified in the docu-
ment.  In some WordStar files, no Body Text Style data appears; 
in these documents STYLCH cannot change the Body Text style.  If 
the Body Text style does not appear on the list of styles STYLCH 
presents for marking, then the Body Text Style cannot be changed 
by STYLCH.  (On the other hand, for some reason some files con-
tain two entries for the Body Text style, and for them, STYLCH 
will present two Body Text Styles to be marked.  In this case, 
mark both or neither.)

Asterisks: Whenever WordStar displays the list of styles, it 
marks with an asterisk any style which has the same name as a 
library style, but which is different from the corresponding li-
brary style.  I have not been able to learn the full details of 
the process by which WordStar does this, so using STYLCH may 
disrupt the proper display of asterisks for styles it modifies.  
Certainly if you modify a style using STYLCH so as to make it 
identical with the library version, WordStar will still consider 
the style to be modified and display the asterisk.  Otherwise, 
cases in which the display of asterisks is incorrect should be 
extremely rare.  If you think WordStar is not properly displaying 
(or failing to display) an asterisk for a given style, you can 
correct the problem by issuing ^OFD, selecting the style in 
question from the list, and then ending the edit with ^K or F10 
without making any changes to the style.  Any inaccuracies in 
assigning an asterisk to that particular style after that are 
WordStar's fault, not STYLCH's.  It is just barely possible that 
the same mechanism that encodes the information used to display 
asterisks has some other role in WordStar that STYLCH would 
disrupt, but I have not been able to find any reason to expect 
this.

63 Styles: STYLCH can only handle 63 styles at a time.  If you 
have a file with more than that many styles used in it, STYLCH 
will stop with an error message as soon as it discovers this.  63 
styles is a screen-full as STYLCH displays them, so it seemed a 
convenient limit, and I find it hard to believe that anyone would 
need more.  If there is enough need, I could add paging of the 
display of styles so that STYLCH could handle more styles.  (If 
you have more than 63 styles in your documents, you probably need 
STYLCH badly.)

No Color Options: STYLCH runs in black and white, even on color 
displays (I think; I have a monochrome display myself).  If there 
is sufficient demand, a command line option to change colors 
could perhaps could be added, but I'd rather not, because with a 
monochrome monitor, I have no way of testing this properly.



ERROR MESSAGES:  When STYLCH discovers something has gone wrong, 
it issues an error message and terminates, setting the DOS error 
level to a non-zero value.  Here are the error messages (followed 
in parentheses by the corresponding DOS error levels) which it 
can issue:


"No input file given.  Usage: stylch inputfile"  (1)

This message is given when you forgot to include in the command 
line the name of the WordStar document file you wish to modify.


"Couldn't open this file." (2)

STYLCH's attempt to open the file failed.   Usually this means 
that you mistyped the name, or that you failed to give the full  
drive and path specification of the file.


"This file is not a WS 5.0 or later document file."  (3)

STYLCH can only work on document files of WordStar versions which 
use paragraph styles; to date, that means versions 5.5 and 6.0.  
If STYLCH can't find the document file header common to files 
produced by WordStar 5.0 or later, it issues this error message.


"This file has been truncated or a file read error has occurred." (4)

You probably won't see this error message.  It could only occur 
because of failure of an attempt to read the style library point-
er beginning 16 bytes into the file.


"This file is not a WS 5.5 or later document file." (5)

In WordStar document files produced by WordStar version 5.5 or 
later (i.e., those that have styles) there is a pointer in the 
file header to the library which stores the style information.  
That library is at the end of the file, and the pointer tells 
WordStar (and STYLCH) where the text ends and library information 
begins.  This error message occurs when the value of that pointer 
is 0, which only happens in WordStar 5.0 files.


"No styles are used in this file." (6)

If there are no style tags in the text of your file, no style 
data is saved in the file.  In this case, when STYLCH attempts to 
read the data in the STYLE library it is attempting to read 
beyond the end of the file, and this error message is the result.


"There are too many styles in the file.  I can only handle 63."  (7)

STYLCH found that there were more than 63 styles whose data was 
stored in your file.  It can't handle that many.  This is dis-
cussed under CAUTIONS AND LIMITATIONS, above.


"Could not find the style, Stylch."  (8)

STYLCH couldn't find the special style in which you embedded the 
information about the changes you wish to make.  Either you 
didn't create it, or you forgot to add a tag for it to the text.  
In either case, the data about the changes you want is not in the 
file.


"Out of Memory" (9)

STYLCH needs memory to hold the data about changes, and it allo-
cates this dynamically as it runs.  It didn't have enough memory.  
Stylch doesn't really need much memory, so it is extremely un-
likely that this error would occur unless you are running STYLCH 
from within WordStar.  Try exiting WordStar and running it from 
the command line.  If many people are having this problem, I can 
probably reduce the amount of memory STYLCH uses.


"The style, Stylch, contained no changes." (10)

STYLCH found the special style named Stylch, but all the fields 
in it were set blank (inherited).  This means you want no 
changes.  Go back into your document and enter the changes you 
want into the special style, Stylch.  Recall (see CAUTIONS AND 
LIMITATIONS) that STYLCH cannot be used to set the value of a 
style field to Inherited.


"Seek error while writing style changes."  (11)

An error occurred while STYLCH was trying to find the place in 
the file to write the changes.  This should not occur.  Try 
again.


"File write error" (12)

An error occurred while STYLCH was trying to write the data to 
the file.  Try again.



TECHNICAL NOTES: These technical notes are not intended to be 
comprehensible to the general reader, but he or she is welcome to 
try to follow along as well as possible.  They presuppose famil-
iarity with various programming concepts and with the WordStar 
File Format Documents in the libraries of the CompuServe WordStar 
forum.

Source code: STYLCH is written in C for the MIX Power C compiler.  
In much of it is ANSI conforming, but I have used a few functions 
which are probably peculiar to the MIX compiler.  The source code 
is not provided routinely, but I have no strong objection to 
making it available to anyone requesting it.  Just now its not in 
much shape to be read by anyone, though.

STYLCH works exclusively on the style library at the end of the 
WordStar document file, except for the check for the file header 
to verify that the file is a WordStar document file and the 
retrieval of the pointer stored in the header which locates the 
beginning of the master library at the end of the file.  STYLCH 
does not (unless it malfunctions) do anything to the text of the 
files it works on.

WordStar Version information: STYLCH checks the version of Word-
Star which produced the file it reads by checking the format of 
the file.  It checks the first three bytes to verify that it is a 
WordStar 5.0 or later file, and then checks for a non-zero point-
er in the file header to the master library to verify that the 
file is WordStar version 5.5 or later.  STYLCH ignores the byte 
giving the version number which is located in the file header, so 
it is compatible with files in which this byte has been deliber-
ately altered.  It displays a version number on the screen which 
it gets from the second byte of the master index, but it makes no 
use of this information except to display it.

Asterisks:  I report here what little I have been able to find 
out about the mechanism by which WordStar determines whether a 
style is identical to a library style.  Much of this is undocu-
mented, and little of it is official. In the master library that 
is an index for the style library.  Each item in this index 
consists of a twenty-four byte style name (padded with blanks as 
necessary), five bytes which are identified as "Used internally", 
and a four byte pointer to the data for the style.  Apparently 
WordStar uses the last two bytes of the five "used internally" to 
store a CRC value for the style data.  I don't know how this 
number is calculated, but it is used to compare styles in the 
document with styles in the library (the CRC values are compared, 
rather than the data directly).  The number appears to be calcu-
lated or recalculated every time one issues a ^K or F10 to exit 
from editing a style (initiated by ^OFD).  STYLCH takes the 
rather daring step of simply setting this value to 0ffeeh for 
every style it modifies.  This will generally be wrong, but it 
appears that at worst this will disrupt the proper display of 
asterisks, and that only rarely.
