Return to jove.3 CVS log

Up to [CSRG BSD Unix] / 43BSDReno / contrib / jove / doc

Annotation of 43BSDReno/contrib/jove/doc/jove.3, revision 1.1

1.1     ! root        1: .NH 1
        !             2: Directory Handling
        !             3: .XS \n(PN
        !             4: \*(SN Directory Handling
        !             5: .XE
        !             6: .LP
        !             7: To save having to use absolute pathnames when you want to edit a nearby file
        !             8: \s-2JOVE\s0 allows you to move around the
        !             9: .UX
        !            10: filesystem just as the c-shell does.
        !            11: These commands are:
        !            12: .IP "cd dir" 15n
        !            13: Change to the specified directory.
        !            14: .IP "pushd [dir]"
        !            15: Like \fIcd\fP, but save the old directory on the directory stack.
        !            16: With no directory argument, simply exchange the top two directories
        !            17: on the stack and \fIcd\fP to the new top.
        !            18: .IP "popd"
        !            19: Take the current directory off the stack and \fIcd\fP to the directory now
        !            20: at the top.
        !            21: .IP "dirs"
        !            22: Display the contents of the directory stack.
        !            23: .LP
        !            24: The names and behavior of these commands were chosen to mimic those in the c-shell.
        !            25: .NH 1
        !            26: Editing C Programs
        !            27: .XS \n(PN
        !            28: \*(SN Editing C Programs
        !            29: .XE
        !            30: .LP
        !            31: This section details the support provided by \s-2JOVE\s0
        !            32: for working on C programs.
        !            33: .NH 2
        !            34: Indentation Commands
        !            35: .XS \n(PN 5n
        !            36: \*(SN Indentation Commands
        !            37: .XE
        !            38: .LP
        !            39: To save having to lay out C programs "by hand", \s-2JOVE\s0
        !            40: has an idea of the correct indentation of a line,
        !            41: based on the surrounding context.
        !            42: When you are in C Mode, \s-2JOVE\s0 treats tabs specially \(em
        !            43: typing a tab at the beginning of a new line means "indent to
        !            44: the right place".
        !            45: Closing braces are also handled specially, and are indented
        !            46: to match the corresponding open brace.
        !            47: .NH 2
        !            48: Parenthesis and Brace Matching
        !            49: .XS \n(PN 5n
        !            50: \*(SN Parenthesis and Brace Matching
        !            51: .XE
        !            52: .LP
        !            53: To check that parentheses and braces match the way you think they do,
        !            54: turn on \fIShow Match\fP mode (ESC X show-match-mode).  Then, whenever
        !            55: you type a close brace or parenthesis, the cursor moves momentarily to
        !            56: the matching opener, if it's currently visible.  If it's not visible,
        !            57: \s-2JOVE\s0 displays the line containing the matching opener on the message
        !            58: line.
        !            59: .NH 2
        !            60: C Tags
        !            61: .XS \n(PN 5n
        !            62: \*(SN C Tags
        !            63: .XE
        !            64: .LP
        !            65: Often when you are editing a C program,
        !            66: especially someone else's code,
        !            67: you see a function call and wonder what that function does.
        !            68: You then search for the function within the current file and if you're
        !            69: lucky find
        !            70: the definition, finally returning to the original spot when you are done.
        !            71: However, if are unlucky, the function turns out to be external
        !            72: (defined in another file) and
        !            73: you have to suspend the edit,
        !            74: \fIgrep\fP for the function name in every .c that might contain it,
        !            75: and finally visit the appropriate file.
        !            76: .LP
        !            77: To avoid this diversion or the need to remember which
        !            78: function is defined in which file,
        !            79: Berkeley 
        !            80: .UX
        !            81: has a program called \fIctags(1)\fP, which
        !            82: takes a set of source files and looks for function
        !            83: definitions, producing a file called \fItags\fP as its output.
        !            84: .LP
        !            85: \s-2JOVE\s0 has a command called C-X T (\fIfind-tag\fP)
        !            86: that prompts you for the name of a function (a \fItag\fP), looks up
        !            87: the tag reference in the previously constructed tags file, 
        !            88: then visits the file containing that tag in a new buffer,
        !            89: with point positioned at the definition of the function.
        !            90: There is another version of this command, namely \fIfind-tag-at-point\fP,
        !            91: that uses the identifier at 
        !            92: .I point.
        !            93: .LP
        !            94: So, when you've added new functions to a module, or moved some old
        !            95: ones around, run the \fIctags\fP program to regenerate the \fItags\fP file.
        !            96: \s-2JOVE\s0 looks in the file specified in the \fItag-file\fP variable.  The
        !            97: default is "./tags", that is, the tag file in the current directory.  If you
        !            98: wish to use an alternate tag file, you use C-U\ C-X\ T, and \s-2JOVE\s0 will
        !            99: prompt for a file name.  If you find yourself specifying the same file again
        !           100: and again, you can set \fItag-file\fP to that file, and run
        !           101: \fIfind-tag\fP with no numeric argument.
        !           102: .LP
        !           103: To begin an editing session looking for a particular tag, use
        !           104: the \fI\-t tag\fP command line option to \s-2JOVE\s0.
        !           105: For example, say you wanted to look at the file containing the tag
        !           106: \fISkipChar\fP, you would invoke \s-2JOVE\s0 as:
        !           107: .DS I
        !           108: .I
        !           109: % jove \-t SkipChar
        !           110: .R
        !           111: .DE
        !           112: .NH 2
        !           113: Compiling Your Program
        !           114: .XS \n(PN 5n
        !           115: \*(SN Compiling Your Program
        !           116: .XE
        !           117: .LP
        !           118: You've typed in a program or altered an existing one and now you
        !           119: want to run it through the compiler to check for errors.
        !           120: To save having to suspend the edit,
        !           121: run the compiler,
        !           122: scribble down error messages, and then resume the edit,
        !           123: \s-2JOVE\s0 allows you to compile your code while in the editor.
        !           124: This is done with the C-X C-E (\fIcompile-it\fP) command.
        !           125: If you run \fIcompile-it\fP with no argument
        !           126: it runs the
        !           127: .UX
        !           128: \fImake\fP
        !           129: program into a buffer;
        !           130: If you need a special command or want to pass arguments to \fImake\fP,
        !           131: run \fIcompile-it\fP with any argument (C-U is good enough) and you
        !           132: will be prompted for the command to execute.
        !           133: .LP
        !           134: If any error messages are produced, they are treated specially by \s-2JOVE\s0.
        !           135: That treatment is the subject of the next section.
        !           136: .NH 2
        !           137: Error Message Parsing and Spelling Checking
        !           138: .XS \n(PN
        !           139: \*(SN Error Message Parsing
        !           140: \*(SN Spelling Checking
        !           141: .XE
        !           142: .LP
        !           143: \s-2JOVE\s0 knows how to interpret the error messages from many
        !           144: .UX
        !           145: commands;
        !           146: In particular,
        !           147: the messages from \fIcc\fP,
        !           148: \fIgrep\fP and \fIlint\fP can be understood.
        !           149: After running the \fIcompile-it\fP command,
        !           150: the \fIparse-errors\fP command is automatically executed,
        !           151: and any errors found are displayed in a new buffer.
        !           152: The files whose names are found in parsing the error messages are each
        !           153: brought into \s-2JOVE\s0 buffers and the point is positioned at the first error
        !           154: in the first file.
        !           155: The commands \fIcurrent-error\fP, C-X C-N (\fInext-error\fP), and
        !           156: C-X C-P (\fIprevious-error\fP)
        !           157: can be used to traverse the list of errors.
        !           158: .LP
        !           159: If you already have a file called
        !           160: \fIerrs\fP containing, say, c compiler messages then you can get \s-2JOVE\s0 to interpret the messages by
        !           161: invoking it as:
        !           162: .DS I
        !           163: .I
        !           164: % jove \-p errs
        !           165: .R
        !           166: .DE
        !           167: .LP
        !           168: \s-2JOVE\s0 has a special mechanism for checking the the spelling of a document;
        !           169: It runs the
        !           170: .UX
        !           171: spell program into a buffer.
        !           172: You then delete from this buffer all those words that are not spelling
        !           173: errors and then \s-2JOVE\s0 runs the \fIparse-spelling-errors\fP command to
        !           174: yield a list of errors just as in the last section.
        !           175: .NH 1
        !           176: Simple Customization
        !           177: .XS \n(PN
        !           178: \*(SN Simple Customization
        !           179: .XE
        !           180: .LP
        !           181: .NH 2
        !           182: Major Modes
        !           183: .XS \n(PN 5n
        !           184: \*(SN Major Modes
        !           185: .XE
        !           186: .LP
        !           187: To help with editing particular types of file, say a paper or a C program,
        !           188: \s-2JOVE\s0 has several \fImajor modes\fP.
        !           189: These are as follows:
        !           190: .NH 3
        !           191: Text mode
        !           192: .XS \n(PN 10n
        !           193: \*(SN Text mode
        !           194: .XE
        !           195: .LP
        !           196: This is the default major mode.  Nothing special is done.
        !           197: .NH 3
        !           198: C mode
        !           199: .XS \n(PN 10n
        !           200: \*(SN C mode
        !           201: .XE
        !           202: .LP
        !           203: This mode affects the behavior of the tab and parentheses characters.
        !           204: Instead of just inserting the tab, \s-2JOVE\s0 determines
        !           205: where the text "ought" to line up for the C language and tabs to that position
        !           206: instead.  The same thing happens with the close brace and close parenthesis;
        !           207: they are tabbed to the "right" place and then inserted.
        !           208: Using the \fIauto-execute-command\fP command, you can make \s-2JOVE\s0 enter
        !           209: \fIC Mode\fP whenever you edit a file whose name ends in \fI.c\fP.
        !           210: .NH 3
        !           211: Lisp mode
        !           212: .XS \n(PN 10n
        !           213: \*(SN Lisp mode
        !           214: .XE
        !           215: .LP
        !           216: This mode is analogous to \fIC Mode\fP,
        !           217: but performs the indentation needed to lay out Lisp programs properly.
        !           218: Note also the \fIgrind-s-expr\fP command that prettyprints an
        !           219: \fIs-expression\fP and the \fIkill-mode-expression\fP command.
        !           220: .NH 2
        !           221: Minor Modes
        !           222: .XS \n(PN 5n
        !           223: \*(SN Minor Modes
        !           224: .XE
        !           225: .LP
        !           226: In addition to the major modes,
        !           227: \s-2JOVE\s0 has a set of minor modes.
        !           228: These are as follows:
        !           229: .NH 3
        !           230: Auto Indent
        !           231: .XS \n(PN 10n
        !           232: \*(SN Auto Indent
        !           233: .XE
        !           234: .LP
        !           235: In this mode,
        !           236: \s-2JOVE\s0 indents each line the same way as that above it.  That is,
        !           237: the Return key in this mode acts as the Linefeed key ordinarily does.
        !           238: .NH 3
        !           239: Show Match
        !           240: .XS \n(PN 10n
        !           241: \*(SN Show Match
        !           242: .XE
        !           243: .LP
        !           244: Move the cursor momentarily to the matching opening parenthesis when a closing
        !           245: parenthesis is typed.
        !           246: .NH 3
        !           247: Auto Fill
        !           248: .XS \n(PN 10n
        !           249: \*(SN Auto Fill
        !           250: .XE
        !           251: .LP
        !           252: In \fIAuto Fill\fP mode,
        !           253: a newline is automatically inserted when the line length
        !           254: exceeds the right margin.
        !           255: This way,
        !           256: you can type a whole paper without having to use the Return key.
        !           257: .NH 3
        !           258: Over Write
        !           259: .XS \n(PN 10n
        !           260: \*(SN Over Write
        !           261: .XE
        !           262: .LP
        !           263: In this mode,
        !           264: any text typed in will replace the previous contents.
        !           265: (The default is for new text to be inserted and "push" the old along.)
        !           266: This is useful for editing an already-formatted diagram in which you
        !           267: want to change some things without moving other things around on the
        !           268: screen.
        !           269: .NH 3
        !           270: Word Abbrev
        !           271: .XS \n(PN 10n
        !           272: \*(SN Word Abbrev
        !           273: .XE
        !           274: .LP
        !           275: In this mode, every word you type is compared to a list of word
        !           276: abbreviations; whenever you type an abbreviation, it is replaced
        !           277: by the text that it abbreviates.
        !           278: This can save typing if a particular word or phrase must be entered
        !           279: many times.
        !           280: The abbreviations and their expansions are held in a file that looks like:
        !           281: .DS I
        !           282: abbrev:phrase
        !           283: .DE
        !           284: This file can be set up in your \fI~/.\|joverc\fP with the \fIread-word-abbrev-file\fP command.
        !           285: Then, whenever you are editing a buffer in \fIWord Abbrev\fP mode,
        !           286: \s-2JOVE\s0 checks for the abbreviations you've given.
        !           287: See also the commands
        !           288: \fIread-word-abbrev-file\fP,
        !           289: \fIwrite-word-abbrev-file\fP,
        !           290: \fIedit-word-abbrevs\fP,
        !           291: \fIdefine-global-word-abbrev\fP,
        !           292: \fIdefine-mode-word-abbrev\fP,
        !           293: and \fIbind-macro-to-word-abbrev\fP,
        !           294: and the variable \fIauto-case-abbrev\fP.
        !           295: .NH 2
        !           296: Variables
        !           297: .XS \n(PN 5n
        !           298: \*(SN Variables
        !           299: .XE
        !           300: .LP
        !           301: \s-2JOVE\s0 can be tailored to suit your needs by changing the
        !           302: values of variables.
        !           303: A \s-2JOVE\s0 variable can be given a value with the \fIset\fP command,
        !           304: and its value displayed with the \fIprint\fP command.
        !           305: .LP
        !           306: The variables \s-2JOVE\s0 understands are listed along with the commands
        !           307: in the alphabetical list at the end of this document.
        !           308: .NH 2
        !           309: Key Re-binding
        !           310: .XS \n(PN 5n
        !           311: \*(SN Key Re-binding
        !           312: .XE
        !           313: .LP
        !           314: Many of the commands built into \s-2JOVE\s0 are not bound to
        !           315: specific keys.
        !           316: The command handler in
        !           317: \s-2JOVE\s0 is used to invoke these commands and is activated
        !           318: by the \fIexecute-extended-command\fP command (ESC X).
        !           319: When the name of a command typed in is unambiguous,
        !           320: that command will be executed.
        !           321: Since it is very slow to have
        !           322: to type in the name of each command every time it is needed,
        !           323: \s-2JOVE\s0 makes it possible to \fIbind\fP commands to keys.
        !           324: When a command is
        !           325: \fIbound\fP to a key any future hits on that key will invoke that command.
        !           326: All the printing characters are initially bound to the
        !           327: command \fIself-insert\fP.
        !           328: Thus, typing any printing character causes it to be inserted into the text.
        !           329: Any of the existing commands can be bound to any key.
        !           330: (A \fIkey\fP may actually be a \fIcontrol character\fP
        !           331: or an \fIescape sequence\fP as explained previously under
        !           332: \fICommand Input Conventions\fP).
        !           333: .LP
        !           334: Since there are more commands than there are keys,
        !           335: two keys are treated as \fIprefix\fP commands.
        !           336: When a key bound to one of the prefix commands is typed,
        !           337: the next character
        !           338: typed is interpreted on the basis that it was preceded by one of the
        !           339: prefix keys.
        !           340: Initially ^X and ESC are the prefix keys and
        !           341: many of the built in commands are initially bound to these "two stroke" keys.
        !           342: (For historical reasons, the Escape key is often referred to as "Meta").
        !           343: .NH 2
        !           344: Keyboard Macros
        !           345: .XS \n(PN 5n
        !           346: \*(SN Keyboard Macros
        !           347: .XE
        !           348: .LP
        !           349: Although \s-2JOVE\s0 has many powerful commands,
        !           350: you often find that you have a task that no individual command can do.
        !           351: \s-2JOVE\s0 allows you to define your own commands from sequences
        !           352: of existing ones "by example";
        !           353: Such a sequence is termed a \fImacro\fP.
        !           354: The procedure is as follows:
        !           355: First you type the \fIstart-remembering\fP command,
        !           356: usually bound to C-X (.
        !           357: Next you "perform" the commands which as they are being executed are
        !           358: also 
        !           359: remembered, which will constitute the body of the macro.
        !           360: Then you give the \fIstop-remembering\fP command, usually bound to
        !           361: C-X ).
        !           362: You now have a \fIkeyboard macro\fP.
        !           363: To run this command sequence again,
        !           364: use the command \fIexecute-keyboard-macro\fP, usually bound to
        !           365: C-X E.
        !           366: You may find this bothersome to type and re-type,
        !           367: so there is a way to bind the macro to a key.
        !           368: First,
        !           369: you must give the keyboard macro a name using the
        !           370: \fIname-keyboard-macro\fP command.
        !           371: Then the binding is made with the \fIbind-macro-to-key\fP command.
        !           372: We're still not finished because all this hard work will be lost
        !           373: if you leave \s-2JOVE\s0.
        !           374: What you do is to save your macros into a file
        !           375: with the \fIwrite-macros-to-file\fP command.
        !           376: To retrieve your macros in the next editing session (but not their bindings),
        !           377: you can simply execute the \fIsource\fP command on that file.
        !           378: .NH 2
        !           379: Initialization Files
        !           380: .XS \n(PN 5n
        !           381: \*(SN Initialization Files
        !           382: .XE
        !           383: .LP
        !           384: Users will likely want to modify the default key bindings to their liking.
        !           385: Since it would be quite annoying to have to set up the bindings
        !           386: each time \s-2JOVE\s0 is started up,
        !           387: \s-2JOVE\s0 has the ability to read in a "startup" file.
        !           388: Whenever \s-2JOVE\s0 is started,
        !           389: it reads commands from the file \fI.\|joverc\fP in the user's home directory.
        !           390: These commands are read as
        !           391: if they were typed to the command handler (ESC X) during an edit.
        !           392: There can be only one command per line in the startup file.
        !           393: If there is a file \fI/usr/lib/jove/joverc\fP,
        !           394: then this file will be read before the user's
        !           395: .I .\|joverc
        !           396: file.
        !           397: This can be used to set up a system-wide default startup mode for
        !           398: \s-2JOVE\s0
        !           399: that is tailored to the needs of that system.
        !           400: .LP
        !           401: The \fIsource\fP command can be used to read commands from a specified file
        !           402: at any time during an editing session,
        !           403: even from inside the \fI.\|joverc\fP file.
        !           404: This means that a macro can be used to change the key bindings,
        !           405: e.g., to enter a mode,
        !           406: by reading from a specified file which contains all the necessary bindings.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.