
                ######  ####### ######   #####
                #     # #       #     # #     #
                #     # #       #     # #     #
                ######  #####   ######  #     #
                #       #       #   #   #   # #
                #       #       #    #  #    #
                #       ####### #     #  #### #

         #####  ######
        #     # #     #  #####    ####    ####   ######
              # #     #  #    #  #    #  #       #
         #####  ######   #    #  #    #   ####   #####
              # #        #####   #    #       #  #
        #     # #        #   #   #    #  #    #  #
         #####  #        #    #   ####    ####   ######



Greetings fellow PERQ Fanatics,

Here's the latest version of the information that I've been able to
gather for using 3Prose.  Thanks to Brian Rosen and Malcolm Shute for
their helpful comments and additions to the last version of this
document!

The following is some information that I've attempted to piece
together for the 3Prose document formatting software.  So far, I've
been unable to locate any documentation for this software, with the 
exception of the following on-line help that appears when 3Prose is
invoked with /help on the command line.  The following was copied
from the on-line help display, verbatim:


3Prose - A Text formatting utility  

     3Prose is a text formatting utility.  See the 3Prose
manual for a full description of Prose and how to use it.

Command form:
     3Prose InFile OutFile {switches}

InFile is the source file name or list of file names
seperated by commas.  The source file names are first looked
up exactly as typed and then with .Prose appended.

OutFile is the result file name.  If this name is omitted, the
result file name is formed by stripping the .Prose from the first
InFile name and adding .Doc.

Valid switches:
     /HELP           print this help message.
     /BAUD:<n>       set the baud rate for the RS232 port.
                     /BAUD by itself sets 9600.
     /<directives>   a list of directives to execute before
                     reading the source file.  Each directive
                     must be preceeded by a period.  This must
                     the last switch because the remainder of
                     the line is interpreted as directives.


That's all of the on-line help provided for both the POS and Accent
versions of 3Prose.  

Hopefully someone reading this will be familiar with this software and
can explain more about using it properly ...and will tell us how to
obtain the original 3Prose documentation.  At the very least,
hopefully someone will recognize some other document formatting
software that 3Prose is similar to which has similar commands, syntax,
etc.  So far, I've seen a few, very few, that is, similarities to
DEC's VAX/VMS Runoff software (.rno files), and many major differences
as well.  I'm curious to know if there was some other similar document
formatting software in use, on some other computer system, named Prose
and Three Rivers Computer/PERQ Systems created their own version of it,
naming it 3Prose.

What is 3Prose?  From what I've been able to determine, 3Prose is some
type of text formatting software used for producing memos, documents,
etc.  3Prose was was based on DEC RUNOFF and was written by John
Strait.  Unlike Mint, 3Prose does not to support the inclusion of
graphics in documents.  It should support multiple fonts, but I
haven't figured out how to use multiple fonts with 3Prose.

3Prose was used at Three Rivers Computer Co./PERQ Systems Corp. to
produce internal documents and memos.  It was used there to create
some of the short documents that I looked at in an effort to "reverse
engineer" them so that I could figure out some of the syntax, etc. in
order to be able to create my own documents using 3Prose.  I located
copies of the 3Prose software from a hard disk that I obtained from
the old PERQ Systems office in Fairfax, Virginia, which was a Megascan
office at the time,  Another copy was found on a tape which also came
from there.  The machines that this disk and tape came from were used
there to design part of the PERQ3 just before PERQ Systems went out of
business.  

What follows are some of the commands and syntax for 3Prose that I
have been able to figure out.  I can't guarantee that this information
is one-hundred percent corect.  In fact, I would imagine that part of
it is incorrect, as it is a "best guess" effort.  Having only had a
very few 3Prose source documents to study, which contained very few
comments didn't make figuring things out very easy.  I would imagine
that 3Prose has more features than were used in those documente.

Please use this information at your own risk :-)  If anyone has any
further information about 3Prose, any corrections to make about this
posting, etc., please speak up so that all of us will get to know more
about 3Prose.  Thanks!

Now, on with some, possibly, useful information...

Note that more than one statement per line may be used.

If 3Prose is given a non-existant file name as an argument, it will
fail with:

*** filename not found.

This error message will then be followed by an uncaught exception.

If no input file name is given on the command line. 3Prose will prompt
for an input name and then an output file name.  For the output file name,
one can just press <CR> and the output file name will be the input name
with .Doc appended to it.

In alphabetical order, the known 3Prose statements follow, along with
examples, where possible.

Note that the kn parameter used in some of the following statements,
such as .margin, .paragraph, .option, etc., is a constant for the
"keep buffer" processing.


Statements
----------

.break

     New paragraphs must be preceeded by this; it also follows .inx
     statements.  It means "do end of processing here".


.com or .comment 

     Any text which follows this is taken to be a comment  

     .comment This is a comment, commenting about a comment. 


.count

     Count appears to be used to set the page number at which counting 
     is to begin.

     .count 1 .com begin counting at page 1


.form

    Define form processing.  This defines parameters pertaining to the
    appearance of the pages, page numbering, etc.

    The following defines the title to be on the top line starting at
    position 1, the date to be displayed on the top line at position
    60, the time to be displayed on the following line at position 60.
    There will be a long line at the bottom of the page.  The subtitle
    will appear at the bottom of the page at position 1, the page 
    numbers appear as, - 2 -, for example and begin at page 1.

    .form([ // #1 t / #60 e / #60 w // l50
    +"___________________________________________________________"
    +// #1 s / #33 "- " pn:1 " -" //])
  

    [ - page start
    / - skip a line
    # - followed by a number, is space over to the nth character 
        position  
    t - print the title here
    e - print the date
    w - print the time
    l - followed by a number, is the number of lines in the page
    s - print subtitle here
    pn - print page number
    :1 - ??? (possibly the starting page number)
    ] - end page

    Quoted text is printed verbatim.


.inx

     This is used to place a phrase in an index.  Note that .inx 
     statements are followed by .break statements in many of the
     .prose files that I've used as examples.  However, doing so
     should not be necessary, unless this be done because of some
     sort of bug in the version of 3Prose used.

     .inx PERQ .com place PERQ in the index
     .inx VAXEN .com place VAXEN in the index
     .inx ###Where .com place Where, indented 3 spaces, in the index

     # is a non expandable space

.input
    
     This is one of the first statements to appear in a .prose script.
     Often, it is preceeded by a .output statement.  The only thing that
     I can figure out about this, except for the following, is that it
     is used to surround text that is supposed to be underlined, etc.

     This statement is something that affects the input filter (does
     anyone know anymore about this input filter?) used to read the
     source file.  It is supposed to define which characters turn on
     and off special processing like underline, bold, etc.

     According to a comment in one of the .prose files that I used as
     a reference, the .input statement is used to "Define I/O / Globals".

     .input(h~ b| u%) 
     .input(h% b| u#)
     .input(h~ u/ b#)
     .input(h~ b| u#)  

     For the first example above, text that is to be underlined would 
     appear as follows:

     %This is underlined% 

     I haven't been able to figure out, yet, what the h and b parameters
     are used for.  When surrounding text with the characters used with
     the h and b parameters nothing appers to happen.



.margin 

     This is used to set the document's margins.

     .margin(k0 l4 r73) .com left margin = 4, right margin = 73
     .margin(k1 l0 r60) .com left margin = 0, right margin = 60 
     .margin(k2 l20 r40) .com left margin = 20, rignt margin =40

     The constant kn is the margin identifier; it is used later
     in the .prose script to refer to this margin setting. Margins
     with the id are remembered, so that you can set the margins
     to the prior settings.  

     margin 2 .com set margin to defined margin 2 (const. k2)

     Margins may also be defined and set later on in the script, after
     all of the initialization has taken placs.  When marginss are 
     directly defined at the point where they are to be used, a margin
     identifier is not used.

     .margin(l5 r75) .com set left margin = 5, right margin = 75

     Additionally, predefined margins may have their parameters
     incremented or decrememted from the original settings.

     .margin(k1 l+6 r-2) . narrow the text by 6 on left, 2 on right

     
.option

     These statements are used to define option processing. kn is used
     as a constant to identify the option at later points in the
     script.  Normally these options are defined near the beginning of
     the .prose script.

     .option 0 .com initialization?
     .option(k0 f+ l+ r+ p+ j20 m+ e+ u-) .com defaults
     .option(k1 f+ l+ r+ p+) .com normal text   
     .option(k2 f- l+ r- p-) .com used for a section heading
     .option(k3 f+ l+ r+ p+ j20 m+ e+ u-) .com indented text
     .option(k4 f- l- r- p+) .com centred text
     .option(k5 f- l+ r- p- m+ s1 u-) .com completely unaltered text   

     Option statements may also be used later on in the document
     without the kn constant.

     .option(f- l- r- p-) .com center text
     .option .com default, the same as .comment 0?
     .option(f- p-) .com no text justification?
     .option(j4) .com ???
     .option(j99) .com ???

     After the options have been defined, they may be used for text
     formatting throughout the document by:

     .option 1 .com this would begin using an option identified by k1 

     Explanation of parameters used:

     e+ ???
     e- ???

     f+ all lines in paragraph have same physical length; end at margins
     f- lines have jagged margin 
  
     f+ fill the text between the left and right margins by expanding 
        spaces.  There will be smooth margins.  
     f- don't fill.  Margins may have jagged edges.

     j[#] ??? Changing the value of # appears to make no visible changes

     l+ turn left justification on
     l- turn left justification off

     m+ ???
     m- ???

     p+ ???
     p- ???

     r+ turn right justification on
     r- turn right justification off
         
     s[#] ???

     u+ Convert all text to upper-case
     u- Do not convert all text to lower-case

     Note: Text may be centered by turning on both right and left 
     justification.  A slightly different appearance of the centered
     text results when the f flag is turned on or off. 


.output 

     Normally this is the first statement to appear, but it is not always
     used.  I have no idea what it is used for; I can only suppose that
     asc means to output the data to the output, .doc, file  in ASCII 
     format and that the e and u are some sort of flags that are set when 
     followed by a + sign.  

     According to a comment in one of the .prose files that I used as a
     reference, the .output statement is used to "Define I/O / Globals".   

     .output(asc e+)     
     .output(ase e+ u+)

     Note that if .output is given no arguments, no errors appear to
     result and the document appears to be processed properly.  Likewise,
     if no .output statement at all is used, there are no error messages
     and the file appears to be processed properly.  In addition, if asc
     is used as the only argument, nothing noticable happens.  However, 
     if asc is left out and e+ and,or, u+ are used as arguments, an error
     message similar to the following results:

---    1. .Output(e+)
Output Error: Bad terminal type
--- Output error: +


.page

     Used to begin a new page.  It can also be used with an argument. 
     However, I'm not certain as to what the purpose of the argument
     is.  When .page is followed by a .count statement, the page 
     numbering is reset to the .count value.

     .page .com Begin a new page.
     .page 8 .com ???
   

.paragraph

     Define paragraph processing.  This works in a manner similar to
     option processing.  This is used to define the format of
     paragraphs, etc.  Note that a blank line may be used to seperate
     the paragraphs.

     .paragraph(k0) .com begin defining paragraph processing?
     .paragraph(k1 f~ nn3 u4 s2 p8) .com numbered itens, singls spacing
     .paragraph(k2 f~ nl3 u4 s2 p8) .com capitol letter items, dbl. spaced 
     .paragraph(k3 f> nl3 u4 s0 p8) .com capitol letter items, no space
     .paragraph(k4 f> ni3 u4 s1 p8) .com lower case items, single spaced 
     .paragraph(k5 f> nn3 u4 s1 p8) .com numbered items, one space
   
     The .paragraph statements can also us used in the script without 
     being pre-defined. 

     .paragraph(f@ s1 p5 i5) .com ? 
     .paragraph .com used alone
     .paragraph(s0) .com no justification, etc. each line types will appear 
                    .com on a seperate line.
     .paragraph(u4 s0) .com ???

     After paragraphs have been defined, they may be used throughout the
     script by calling the definitions as follows:

     .paragraph k2 .com begin using paragraph identified by k1

     Explanation of the parameters ued:

     i[#] - Indent first line # spaces

     nl[#] - lower-case letters identify paragraphs
     nL[#] - upper-case letters identify paragraphs
     nn[#] - numbered paragraphs
     nr[#] - lower-case Roman numbering
     nR[#] - upper-case Roman numbering 

     In the above parameters, # indicates the number of spaces to indent
     the first line in the paragraphs.  Note that the identifying number 
     or letter is also indented.  If # is equal to 3, the first part of
     the _text_ in the first line is even with the text in the other lines
     in the paragraph.  If # is less than 3, the text is "outdented" 
     rather than even or indented.

     p[#] - ???

     s0 - No spacing between paragraphs
     s1 - Single spacing
     s2 - Double spacing
     s[#] - Whatever spacing you want.

     u[#] - Indents first line to the right when # is decremented

 
.skip

     This is used to allow one to skip down n lines.

     .skip 4 .com Skip down four lines.
     .skip 10 .com Skip down ten lines.


.sortindex

     Apparently, this does some sort of sort on the contents of the
     index.  I haven't the slightest clue as to what function of the
     parameters are.

     .sortindex(sp r4 m5)


.subtitle

     Defines the subtitle to be used.  For example, a subtitle that
     would appear at the bottom of a page.

     .subtitle Chapter 1: Why is Where and What


.title

     This is used to define the title that is to be placed where the
     formatting commands define it to be placed.  For example, at the
     top left corner of each page.  

     .title Revenge of the PERQs
     


Miscellaneous Notes
-------------------

Underlining of text:

     In order to have text underlined, it must be surounded by some
     previously identefied marker characters.  The user can define what
     characters are used to identify the beginning and ending of the
     underlining.  The characters to be used must be defined in the
     .input statement.  If the u parameter in the .input statement is
     followed by a /, then text surrounded by the / character would be
     underlined.  For example:

     /This is underlined./

     Note that this text would not be fully underlined; only the individul
     words would be underlined, not the blank spaces.


I/O / Globals

     Apparently some sort of global text substitution of text is allowed. 
     How this works, however, I haven't figured out.  Apparently the
     text to be substituted is somehow entered on the command line when
     3Prose is invoked.  After doing this, all occurances of text 
     identified by the constant surrounded by a / is replaced by the 
     word or phrase assigned to the constant.  For example, if picture
     was a constant to be used, and the word photograph was assigned to
     that constant, every time that /picture/ was used in the .prose file
     the word picture would be substituted for it in the processed 
     document.  

Printing:

     The CPrint software has /PROSE and /DOC switches.  I can't see where 
     these switches perform anything other than changing the font used 
     for printing.   
