\begindata{hlptext,538076416}
\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{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{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.

}
\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 up between several lines.


\bold{comment-indent} <varies by language>

Determines how far a comment is indented from the opening delimiter, when 
Ctrl-J is used to continue it on a new line.


\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{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".  This is usually used 
for code that must also be viewed on fixed-width terminals.  When non-zero, 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 ident 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{reindent-comments \italic{0}}

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.


\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;reindent-comments=1"

}}
\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{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{\helptopic{apftext}  (for Alternate Part Files)

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

\helptopic{asmtext}  (for Assembly Language Programs)

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

\helptopic{ctext}  (for C Programs)

\helptopic{idltext}  (for Idl Programs)

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

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

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

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

\helptopic{roftext}  (for Routing Files)

\helptopic{rprcltext}  (for Reprocess Lists)

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

\smaller{\smaller{$Disclaimer: This software is part of version 6.1 of the 

Andrew User Interface System and is 

the property of IBM, Carnegie Mellon University, 

and the other copyright holders.  The source 

code of this version is for the sole use of 

the individual named in ./config/allsys.h.  

This source code is not to be redistributed.  

Binary object code compiled or derived from 

these sources is not to be distributed to non-

members.  Members may have additional 

distribution rights granted by prior written 

permission of Carnegie Mellon University.



IBM, CARNEGIE MELLON UNIVERSITY, 

AND THE OTHER COPYRIGHT HOLDERS

 DISCLAIM ALL WARRANTIES WITH 

REGARD TO THIS SOFTWARE, INCLUDING 

ALL IMPLIED WARRANTIES OF MERCHANT-

ABILITY AND FITNESS. IN 

NO EVENT SHALL  IBM, CARNEGIE 

MELLON UNIVERSITY, OR ANY OTHER 

COPYRIGHT HOLDER BE LIABLE FOR 

ANY SPECIAL, INDIRECT OR CONSE-

QUENTIAL 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,538076416}
