\begindata{hlptext,538398720}
\textdsversion{12}
\template{help}
\chapter{srctext: a superset of all source editing packages

}
\section{What srctext (and source views) are

}
\leftindent{Srctext is common to all the source code editing views in EZ, 
such as  \helptopic{ctext}  (for C programmers),  \helptopic{mtext}  (for 
Modula-2 programmers), and  \helptopic{plmitext}  (for PL/MI programmers). 
 See the end of this document for a complete list of these source views.


When editing source code with EZ, each individual language's source view 
uses a "template".  This template contains style information and in most 
cases, example code.  The style information causes your code to be 
displayed in a fixed-width (typewriter) font.  The example code will appear 
whenever you edit a file that didn't already exist.  Most templates contain 
 \helptopic{dogtags} , which will cause pertinent information to be filled 
in automatically when you edit a new file.

}
\section{Starting a source view

}
\leftindent{Whenever you edit a file with a recognized extension, EZ uses 
the appropriate source view to edit it.  To find out which extensions are 
used by which source views, look at the file 
\italic{/usr/andrew/lib/global.ezinit}, and read the help file for 
 \helptopic{initfiles} .


Example:

\typewriter{  ~> \bold{ez myfile.h}}     will use the  \helptopic{ctext} 
 source view to edit myfile.h.

}
\section{Comparing files

}
\leftindent{An interactive \italic{diff} package called \italic{ezdiff} is 
available for comparing your files in EZ.  See the  \helptopic{ez-diff} 
 help file for more information.

}
\section{Compiling programs

}
\leftindent{A package to compile your program within EZ, and parse errors 
so that you can step through them, is available.  See the 
 \helptopic{compile}  help file for more information.

}
\section{How source views work

}
\leftindent{When source code is edited with EZ, styles are superimposed on 
the text for the programmer's convenience.  Comments are italicized, 
function names are displayed in bold type, and other styles are added 
depending on the particular language.  These styles are not saved to the 
file, since most compilers wouldn't appreciate them; the styles exist only 
during editing.


\bold{Note:} When the source views insert whitespace, they automatically 
insert the correct combination of tab and space characters, replacing 
spaces by tabs when possible without changing the look of the line. 
 \smaller{(Not applicable if the "use-tabs" option is turned off; see 
below.)}

}
\section{Special keys

}
\leftindent{The source views remap keys to perform certain functions.  Some 
are shortcuts for popup menus (see below).  Others include:


\bold{The tab key.} Tab has three uses:


\leftindent{1.) If there is a selected region, all the lines within that 
region will be re-indented to what source view considers the "correct" 
indentation.  \smaller{(not applicable if "enable-indentation" is turned 
off; see below)}


2.) If there is no selected region and the text caret is positioned 
\italic{before} any text on the current line (within the initial 
whitespace), then that line will be re-indented as above. \



3.) If the text caret is positioned \italic{after} some non-whitespace text 
on the line, it will insert enough whitespace to move to the caret to the 
next tab column.  Tab columns are positioned at multiples of "tab-size" (8 
by default).  Any existing whitespace at the caret position will be counted 
as if it were inserted (so the tab key will skip over whitespace to the 
next tab column if it is sitting on whitespace).

}
\bold{The Linefeed (Ctrl-J) key.}   Linefeed does two things:  \



\leftindent{1.) It re-indents the current line, just in case it needs to be 
fixed up (since sometimes the indentation after typing something is 
different than without it, i.e., else). \



2.) It inserts a newline, and then inserts the correct indentation for the 
new line (moving the caret to that point).

}
\bold{The Insert key.}


\leftindent{[Ins] toggles between the normal "insert" mode, and "overstrike 
mode".  Overstrike mode is only available when editing source code.  It 
types over existing characters, except for tabs and newlines.

}
\bold{The Esc-1 (or Alt-1) key sequence.}


\leftindent{In most languages, this will insert a comment at the end of the 
line.  Its behavior depends on the options you have set (see below).

}
\bold{The Esc-2 (or Alt-2) key sequence.}


\leftindent{In some languages, this will insert a "bang comment" or 
"in-line comment" at the end of the line.  Its behavior depends of the 
options you have set (see below).

}}\leftindent{
}\section{Pop-up menu meanings

}
\leftindent{In addition to the regular EZ menu options, the source views 
supply an additional menu, the Source Text menu.  It contains the following 
options:


\leftindent{\bold{Redo styles:}  (Esc-r or Alt-r key)  Updates all the 
styles that are put on comments, function names, and keywords.


\bold{Indent line/region:}  (Tab key)  See description of tab key, above.


\bold{Format line/region:}  (Esc-^R or Ctrl-Alt-r key)  Does all the same 
things as the "Indent line/region" (Tab key), but it will also re-flow 
comments together, and break lines up appropriately if max-length has been 
set.


\bold{Compress region:}  If a region is selected, it will be "compressed" 
into a box.  Otherwise, all nearby lines that are indented as far or 
farther than the line the caret is on will be "compressed" into a box.  To 
restore the text, click a mouse button in the box.  \smaller{(If compressed 
text is saved, the file will contain the text in its original uncompressed 
form.  No record of its being compressed is saved.)}


\bold{Compress all inner indents:}  Similar to "Compress Region", but it 
will traverse the entire file, compressing all regions that are indented as 
far or farther than the line the caret is on.  \smaller{(Regions less than 
3 lines long will not be compressed.)}


\bold{Decompress all:}  Removes all the boxes and restores the text that 
was compressed inside them.  To decompress a single box, just click a mouse 
button on it instead.  The left mouse button will cause the decompressed 
text to be highlighted, so you can immediately re-compress it.  The right 
mouse button will not affect the cursor's position.


\bold{Find Next too-long Line:}  (Esc-^T or Ctrl-Alt-t key)  This appears 
whenever the max-length has been set (see below).  It will find the next 
line that's longer than max-length, and highlight the offending characters.


\bold{Rename identifier:}  Prompts for identifier to replace and what to 
replace it with, then replaces all occurrences in the selected region with 
the desired string.


\bold{Force Upper On(Off):}  Toggles the force-upper option.  When On, it 
will cause keywords to be made uppercase when they're typed in.

}}
\section{Customizing source views in your preferences file

}
\leftindent{For more information, see the help text for 
 \helptopic{preferences} .  All the source views allow you to specify 
certain EZ preferences.  Since the source view for each language has its 
own preferences, substitute (for example) "ctext", below when "?text" is 
specified.  Default values are shown in italic.


\bold{ez.?text_Uppercase:} \italic{WORD1,WORD2,...}

This preference specifies a list of words to force uppercase (but without 
styles) when they're typed with the force-upper option turned on.


\bold{ez.?text_UserDef:} \italic{WORD1,WORD2,...}

This preference is for listing user-defined, or compiler-specific keywords. 
 In most languages, the words MUST be uppercase to be recognized properly, 
but in languages like C, they need not be.


}\leftindent{\bold{ez.CompressBoxFont:} \italic{andysans8}

This preference determines the font to be used in the boxes that represent 
"compressed" regions of code.


\bold{ez.CompressBoxForegroundColor:} \italic{black}

This preference sets the color of the string "nnn compressed lines" that 
appears in boxes of compressed code.


\bold{ez.CompressBoxBackgroundColor:} \italic{white}

Specifying this preference will replace the border drawn around compress 
boxes with a solid rectangle of the specified color.


\bold{ez.InitialRedoStyles:} \italic{on}

Switching this preference to \italic{off} will prevent EZ from doing an 
automatic "Redo Styles" when it first comes up.  It will come up noticeably 
faster for extremely large files, but you'll have to manually select the 
"Redo Styles" menu (or Alt-r key) to get the styles put in place.


\bold{ez.ReindentComments:} \italic{yes}

Comments will be reindented to line up with code when "Reindent 
line/region" is selected.  But if this preference is set to \italic{no}, 
comments will be left exactly where they are.  (Note: global.preferences 
may change this default to \italic{no}.  Also, "Re\underline{format} 
line/region" \underline{always} reindents comments; this preference does 
not affect it).

}

\section{Customizing source views in your .ezinit file

}
\leftindent{For more information, see the help text for 
 \helptopic{initfiles} .  All source views have several ezinit options in 
common.  Specific ones may be found in the help text for that particular 
language.


\leftindent{\bold{level-indent} <varies by language; usually 2 or 4>

Controls how far nested code gets indented.  \smaller{(Not applicable if 
preempted by more specific options, such as plmitext's "do-indent")}


\bold{cont-indent \italic{2}}

Controls how far the continued line is indented when a single statement is 
broken by a newline character.  \smaller{(Does not apply to \italic{wrapped} 
lines)}


\bold{reindent-comments} <see ReindentComments preference>

If zero, comments will be left where they are when a line or region is 
reindented.  If non-zero, comments will be reindented when a line or region 
is reindented.  \smaller{(This is only needed if you want special behavior 
for certain file extensions; it's more convenient to simply set the 
\bold{ez.ReindentComments} preference)}


\bold{comment-indent} <\bold{\italic{3}} for most languages>

Controls how far the continued line is indented when a comment is broken by 
a newline character.  \smaller{(Does not apply to \italic{wrapped} lines)}


\bold{comment-col} <\bold{\italic{1}} for most languages>

Specifies what column to put comments in when Esc-1 is pressed.  Its value 
can be negative or positive, and this determines where Esc-1 puts the 
comment if the specified column already contains code.  If positive, the 
comment will be placed farther out on that line.  If negative, a new line 
will be inserted so the comment can be placed exactly there.


\bold{linecomment-col} <\bold{\italic{1}} for most languages>

Specifies what column to put comments in when Esc-2 is pressed.  Its value 
can be negative or positive, and this determines where Esc-2 puts the 
comment if the specified column already contains code.  If positive, the 
comment will be placed farther out on that line.  If negative, a new line 
will be inserted so the comment can be placed exactly there.


\bold{remark-padding \italic{1}}

Controls how closely a remark can get to code, when the code extends beyond 
"comment-col".  Setting this to 0 will let the `/*' smash right up against 
the code.  The default value 1 will force a minimum of one space to be 
maintained.  \smaller{(Notice that it won't necessarily ADD a space between 
code and comments that were ALREADY smashed together; it's only a 
\italic{preventative} measure)}


\bold{max-length} <\bold{\italic{0}} for most languages>

If non-zero, will display a warning when a file is saved containing lines 
exceeding that length.  Zero means "no maximum length".  Non-zero values 
are usually only used for code that must also be viewed on fixed-width 
terminals.  An additional menu item, "Find Next too-long Line", will appear 
on the Source Text menu card (see above).


\bold{use-tabs} <varies by language>

If 0, will indent exclusively with space characters.  If non-zero, will 
optimize whitespace with tab characters wherever possible.


\bold{enable-indentation} <\bold{\italic{1}} for most languages>

All source views that "know" how to indent code will have this enabled by 
default.  A value of zero will disable it so indentation must be done 
manually.


\bold{tab-stops} <none>

This is a list of numbers separated by whitespace or commas.  Each number 
is a "tab stop", which determines where the cursor will jump to next time 
Tab is pressed.  \smaller{(Not applicable when cursor is at front of line 
and "enable-indentation" is on, because the automatic indenting will 
preclude it)}


\bold{tab-size \italic{8}}

This adds a "tab stop" at every multiple of its specified value.  If zero, 
\italic{only} the "tab stops" \italic{explicitly} specified in the 
"tab-stops" option above will be used.  \smaller{(Note: these "tab stops" 
should not be confused with "tab \italic{characters}".  "Tab stops" only 
determine where the cursor should jump to; the characters that actually get 
\italic{inserted} are the optimal combination of space characters and tab 
characters that will \italic{get} the cursor to the next "tab stop")}


\bold{force-upper \italic{0}}

If non-zero, will default to force-upper mode, which will uppercase 
keywords as you type them.


\bold{overstrike \italic{0}}

If non-zero, will start EZ in overstrike mode.  \


}
To change any of these options, put them in an addfiletype line in your 
.ezinit file.  If you don't already have a .ezinit, you should read the 
help text on  \helptopic{initfiles}  to make sure you include global.ezinit 
in it.  Example:


\typewriter{include /usr/andrew/lib/global.ezinit

addfiletype .h ctext "template=h;level-indent=2;comment-indent=3"


}}
\section{Customizing source view key bindings}


\leftindent{Default keybindings in the source view can be found with the 
"Display Bound Keys" item on the "Misc" menu card.  Each key and menu item 
is bound to a "proc".  For example, the "Redo Styles" menu item and the 
Esc-r key are both bound to the "srctextview-redo-styles" proc.


The most common change is to bind the Enter key to do what Ctrl-J does. 
 This can be done by adding the following line to your .ezinit file:


\typewriter{addkey srctextview-newline ^M

}
See the help text on  \helptopic{initfiles}  for more information.

}
\section{Customizing source view templates}


\leftindent{The "template" is a file with a .tpl extension containing the 
example code that appears when editing a nonexistent file, as well as style 
information.  Users who wish to create their own templates should first get 
some background information from the  \helptopic{initfiles} , 
 \helptopic{templates} ,  and  \helptopic{lookz}  help files.  Generally, 
you should copy whichever template is \italic{currently} used into your own 
~/tpls subdirectory.  (The name of the template that is currently used can 
be found on the "addfiletype" line in the appropriate initfile.)  Edit your 
own copy using EZ, and select "Edit Styles" from the "File" menu card.  You 
can then change the appearance (font, color, and size) of the **comment** 
style, for example.

}
\section{Related tools}  \



\leftindent{Move your mouse cursor to one of the following names and click 
your left mouse button to see the help file for:


\leftindent{\helptopic{compile}

\helptopic{dogtags}

\helptopic{ez}

\helptopic{ez-diff}

\helptopic{initfiles}

\helptopic{preferences

}}
Click one of the following names to see more information on a specific 
language's source view:


\leftindent{\typewriter{\helptopic{apftext}    }(for Alternate Part Files)

\typewriter{\helptopic{asptext}    }(for Alternate Search Path Files)

\typewriter{\helptopic{asmtext}    }(for Assembly Language Programs)

\typewriter{\helptopic{cpptext}    }(for C++ Programs)

\typewriter{\helptopic{ctext}      }(for C Programs)

\typewriter{\helptopic{idltext}    }(for SOM IDL Programs)

\typewriter{\bold{\helptopic{ltext}}      }(for Lisp Programs)

\typewriter{\helptopic{m3text}     }(for Modula-3 Programs)

\typewriter{\helptopic{mtext}      }(for Modula-2 Programs)

\typewriter{\helptopic{ncsidltext} }(for NCS IDL Programs)

\typewriter{\bold{\helptopic{ptext}}      }(for Pascal Programs)

\typewriter{\helptopic{perltext}   }(for perl Programs)

\typewriter{\helptopic{plmitext}   }(for PL/MI Programs)

\typewriter{\helptopic{plmptext}   }(for PL/MP Programs)

\typewriter{\helptopic{plx400text} }(for PL/X-400 Programs)

\typewriter{\helptopic{rexxtext}   }(for REXX Programs and Macros)

\typewriter{\helptopic{roftext}    }(for Routing Files)

\typewriter{\helptopic{rprcltext}  }(for Reprocess Lists)

\typewriter{\helptopic{tstrtext}   }(for Test Case Files)

\typewriter{\helptopic{vhdltext}   }(for VHSIC Hardware Design Language 
Files)


}}\
\begindata{bp,538210560}
\enddata{bp,538210560}
\view{bpv,538210560,0,0,0}
Copyright 1992, 1994 Carnegie Mellon University and IBM.  All rights 
reserved.

\smaller{\smaller{$Disclaimer: 

Permission to use, copy, modify, and distribute this software and its 

documentation for any purpose is hereby granted without fee, 

provided that the above copyright notice appear in all copies and that 

both that copyright notice, this permission notice, and the following 

disclaimer appear in supporting documentation, and that the names of 

IBM, Carnegie Mellon University, and other copyright holders, not be 

used in advertising or publicity pertaining to distribution of the software 

without specific, written prior permission.



IBM, CARNEGIE MELLON UNIVERSITY, AND THE OTHER COPYRIGHT HOLDERS 

DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING 

ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS.  IN NO EVENT 

SHALL IBM, CARNEGIE MELLON UNIVERSITY, OR ANY OTHER COPYRIGHT HOLDER 

BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY 

DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, 

WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS 

ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE 

OF THIS SOFTWARE.

 $

}}\enddata{hlptext,538398720}
