;
                                   JUST.COM                                   

             Size (recs) CRC   Version    Author/Latest Issue      Disk
JUST.COM       4k (32)   06A9  1.3        Gene Pizzetta 10/91      Z3COM10

  1- Syntax/Options  2- Justification Method  3- Notes                        

   JUSTIFY is a ZCPR3 version of Irv Hoff's utility  (3/8/88) to justify ASCII 
and WordStar text files with many new features.  Very fast and easy to use, it
makes even margins by a unique fill method that produces handsome documents.

   Based on the FILT7 program, JUSTIFY resets high bits, removes control char-
acters, expands tabs,  removes trailing spaces,  eliminates orphan line feeds,
and normalizes binding spaces and  soft  carriage  returns.   Soft hyphens are
changed to normal hyphens at the end of the line, but eliminated elsewhere.

   Under ZSDOS or ZDDOS,  JUSTIFY will transfer the create date stamp from the
source file to the new file.   If the source  file  has no  create  date,  the
source file's modify date will be used instead.
:1
    Syntax   JUSTIFY {dir:}infile {dir:}{outfile} {{/}options}

   Everything is optional, except the source file.  If no  DIR or DU is given,
the current drive and user is assumed.   If no  destination file is  given, it
will have the same name as the source file, but with  a filetype of "JUS".  If
an existing file has the same name as the destination file,  the existing file
will be renamed to filetype "BAK".

   On error,  such  as an invalid directory or a file not found,  JUSTIFY sets
the program error flag to the standard codes listed in  Z34ERR.LIB and invokes
the error handler.   Even a user abort via  ^C  invokes the error handler so a
pending SUB or ZEX operation can be aborted.
 Options - 1/3 

   A leading slash is necessary unless the option list is the  third parameter
on the command line.

     nn   Text  width.  The  width  of  the  line  (right  margin
          column)   used   for   justifying.  The   default,   as
          distributed, is 65.

     S    Justify lines starting  with  a  space.  If you wish to
          indent the first line of each paragraph, you still want
          them justified.  There are two ways to accomplish this.
          Use the S option or use the  "]"  in-text  character in
          the first  column  of each indented line.  The S option
          requires nothing special  in  the source file; however,
          if you have other lines that  are  indented  but should
          not be  justified, they will be justified too.  In that
          case you need to  use  a  ";"  at the beginning of each
          line not to be justified.
 Options - 2/3 

     L    Justify lines regardless  of original length.  Normally
          lines are not justified if it would  require  more than
          two spaces  between  words.  If  some  lines  need more
          spaces, the L option must be used to  totally  fill the
          line.  But then  even  short  lines  will be justified,
          such as:
               such            as            this           one
          which could have been prevented by using:
               ;such as this one
          The ";" is dropped and  the  word "such" started at the
          left margin.  If option L is not  used,  however, short
          lines are  left  alone and all but the very worst lines
          will be justified.  If a line is not justified, chances
          are excellent that the  lengthy  word  on the next line
          can be hyphenated to allow part of it to  be  placed on
          the current line.
 Options - 3/3 

     F    Retain embedded form feeds.  Normally, form feeds, like
          all other control characters are removed from the file.
          With the F option, form feeds are preserved.

     Q    Toggle quiet mode.  This  options normally puts JUSTIFY
          into quiet mode.  If the quiet  flag  is  set, however,
          this option will toggle back to verbose mode.

   All options may be  configured as the  defaults.   In that case the command
line option will toggle the option off.
 In-Text Special Characters 

   The characters must appear in the first  column of the  line  they  affect.
Normally none of these special characters are required.

     )    Center this  line.  Centering  a  line  is  easy to do.
          Just type the ")" right parens  character  at  the left
          margin and  then  move  the line to be centered against
          that character:
               )This line will be centered
               )So Will this one
               )This too

     ]    Justify this indented paragraph.  The "]" right bracket
          forces the justification  of  lines  that are indented,
          when you have not selected option  S  to  justify lines
          beginning with  spaces.  The bracket will be changed to
          a space, so the length  of  the  line and the number of
          columns intended will be kept intact.

     ;    Do not justify this line.  A semi-colon ";" in the left
          column  prevents  justification  of  the  line.  It  is
          probably seldom needed.
:2 
 Justification Method - 1/6                      Irv Hoff W6FFC - PRACSA RCPM 

   The JUSTIFY fill method differs significantly from WordStar,  Word Perfect,
and other common justification algorithms:

     1. Never puts an extra "fill blank" between the first two or
     last two words, unless those are required.

     2. Justifies the center of the first line, the right side of
     the second line, and  the  left  side of the third line.  It
     always moves in one additional word at each end to  do this.

     3. Never  puts  any  extra  blanks  in  a location where two
     blanks already exist.

     4. Fills the final line  of  a  paragraph  if it is within 4
     characters of normal length.
 Justification Method - 2/6 

   The word  "justify"  as used in this discussion  means  "to fit exactly, to
fill a full line."  Consequently, a program that justifies will fill each line
to the same width, producing even margins on both sides of the  page.   To  do
this with a normal typewriter or  computer  display  requires  inserting "fill
blanks" (extra spaces) between words at various plaes on the line.   No matter
how this is accomplished, it produces text  that  has  "holes"  in  it.   This
detracts to some extent from reading that text in a normal manner.

   Adding these extra "fill blanks" in the least obtrusive manner then becomes
very important.  WordStar (currently version 4.0) is by a wide margin the most
popular word processor program for people  with  CP/M  computers.   Ironically
this is the very worst program available with regard to adding fill blanks for
justification.

   You may wish at this time to stop and read  FORMAT.INF,  included with this
distribution, which goes into some depth  showing  why  this  statement is not
overstated and shows examples of the  juvenile  method  WordStar  uses.  (I've
been known in the past to say even a child in  Kindergarten could have thought
up a better method.)
 Justification Method - 3/6 

   To quickly summarize,  for  WordStar 4.0,  the  first fill  blank needed is
always  placed  between the last two words on the right  side.   The second is
always placed between the first two words.  Any others alternate from right to
left.  This means every line not already the correct length will have an extra
blank between the last  two  words.   The  worst  case would be where you need
three or more additional fill blanks and the end of the  sentence is something
like this:

     ...this is the end of the sentence.  I
                                        ^^
                                    two blanks

after justification with WordStar 4.0, the same line:

     ...this is the end of the sentence.    I
                                        ^^^^
                                     four blanks
 Justification Method - 4/6 

   This  "worst possible case"  is not as unusual with the WordStar program as
you might at first think.   Winding up  with three  sequential blanks is quite
common.

   Why "yet another" program?  I started to write a new DOC file for a differ-
ent program I have been working with for some time.  A comparable program with
a fine DOC file already exists.   It was written via WordStar and justified to
64 columns.   In trying to read that file,  I kept getting  distracted  by the
manner in which WordStar justifies its text.  I kept wanting to redo that part
so I could then  read  the  text  for  content  rather  than be annoyed by the
format.

   The manual did look  great,  from  a distance.  I thought my DOC file might
look better if it had justified margins.  To do this I needed two things:

     1. A program that  would  insert  fill  characters in a more
     logical manner than WordStar, and

     2. Since I don't use/care for WordStar, would need to obtain
     another program for that purpose.
 Justification Method - 5/6 

   About that time,  somebody uploaded  ALPHA20.LBR  to the local  BBS  that I
operate.   It meant I could write the text  (as I am doing now) with my normal
editor  (VEDIT, in my case)  and then run it through  a  format program to add
justification.

   Unfortuantely that fizzled out when I found that  ALPHATXT  does not recog-
nize lines already the correct length.   It  was  essentially a  program  that
wants to format files and then add justification.  I then heard of  ROFF4  and
later RNF13.   Both these programs are patterned  after an UNIX program of the
early 80's called  RUNOFF.   They both do an excellent job of reformatting and
will quit at that point if you like.   Just what I wanted.   In  fact,  as the
examples in  FORMAT.INF  show,  these programs can take badly  munged text and
make it into a perfectly formatted  output file.   They will  also  justify to
even margins while formatting, if you wish.
 Justification Method - 6/6 

   Either  was  quite  close to what I had in  mind.   However  ROFF4  doesn't
properly justify lines already the proper length and thinks they are one char-
acter too long.   All  these  programs  mentioned so far  have  the same fault
illustrated above for WordStar  -  they can wind up with four blanks in a row.
Three at  these  locations  is  commonplace.   Although  both  these  programs
alternate from right side to left  side  with  fill  blanks, they always start
with the last two words on one line and the first two words on the next line.

   I decided it was time I stop  "just thinking about" a program I had written
in 1976 for ham radio use and adapt it to CP/M.   At that  time  I  assumed my
work would be considered very elementary by  any professional programmer.   It
was an interesting program that would justify conversational  messages, as you
typed them, in real time, over ham radio.

   It is so very fast and so easy to use, you might even go out of your way to
put out justified text, now.  (I've been using it extensively on the pre-typed
messages I write for batch uploading to CompuServe.)

   By using ROFF4 or RNF13,  you  can  re-format  existing  text  files  to 72
columns and then run them through JUSTIFY quite quickly and easily.  You might
indeed prefer the new appearance of those files.
:3
 JUST Notes - 1/2 

   a. Vs 1.3 updates (9/30/91, Gene Pizzetta):
      - Now checks for ambiguous filenames before doing anything.
      - Made display of line-count progress  reports a configurable option.

   b. Vs 1.2 updates (9/10/91, Gene Pizzetta):
      - Separate assembly without video  highlighting no longer supported, but
        now uses ZSLIB HIVON and  HIVOFF instead of much larger VLIB routines.
      - Since size was no longer a problem, some of the code was uncrunched to
        make it more straightforward.

   c. Vs 1.1b updates (9/4/91, Bruce Morgen):
      - Tweaked code and used VLIB11 (slower, but smaller when only a few 
        routines are called).  
      - Video-enabled version now 32 records, vanilla version now 30 records.
 JUST Notes - 2/2 

   d. Vs 1.1 updates (8/31/91, Gene Pizzetta):
      - Disassembled enough to change to a relocatable file. 
      - Changed to Z80 opcodes to  partially  compensate  for  space  used  by
        additional features.  
      - Replaced some routines with library routines.  
      - Removed requirement for output filename.
      - Changed key options to command line entry.  
      - Fixed bug that was eliminating soft hyphens at the end of a line,  not
        just in the middle of the line.  
      - Changed some messages to make them more descriptive.  
      - Added DU support, intelligent usage screen,  error flag setting, error
        handler invocation,  quiet mode,  command line column count entry, and
        ZCNFG configuration.  
      - Under  ZSDOS and  ZDDOS file create date stamps are transferred to the
        new file.
