\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} 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} 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} 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} 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}