Vicom Intelligent Line-Commenter
A programming aid for the most common programming languages.
INTRODUCTION
This program installs into the users home directory. It is meant to compliment the vimake package to create in vim a programmers workbench.
Vicom uses the <Ctrl X> and <Ctrl Y> keys to comment or uncomment lines of code in a program. It automatically selects the correct type of "comment" by examining the file before vim or gvim loads. It writes suitable key maps to a small buffer area. Allowing the same pair of keys to perform the comment or uncomment functions. The recognized file types are listed below under Filename Extensions When a non program file is loaded into vim or gvim the buffer is cleared and the comment keys are disabled. The purpose of this program is to allow sections of code to be rapidly commented out or restored during testing and debugging.
INSTALLATION
Copy or move the package vicom-1.09 to your $HOME account, then unpack it with the following command.
tar -zxvf vicom-1.09.tar.gz
Change directory to vicom-1.09 and run
./configure
make install
cd $HOME
SET ENVIRONMENT PATH
The most common shell on Linux is "bash" so the following explanation is for the bash shell. Users of other shells
should consult the appropriate documentation regarding the "setting of environment paths."
When bash is invoked as an interactive login shell, or as a non-interactive shell with the login option, it first reads and executes commands from the file /etc/profile, if that file exists. After reading that file, it looks for ~/.bash_profile, ~/.bash_login, and ~/.profile, in that order, and reads and executes commands from the first one that exists and is readable.
When an interactive shell that is not a login shell is started, bash reads and executes commands from ~/.bashrc, if that file exists.
Start by checking if the path to $HOME/bin exists in ~/.bash_profile or ~/.bashrc.
If it is in neither then
edit $HOME/.bash_profile file and add the following line.
export PATH=$PATH:$HOME/bin
Save the file then start a fresh shell for the new environment path to take effect.
To confirm the new path is set correctly, type which vcominst it should return the "home/bin" subdirectory.
If it's not found then logout and log back in again, but usually a new terminal will suffice.
To complete the installation run the following command.
vcominst <Enter>
Depending on which shells you have configured the output from vcominst
should appear similar to the following. This output is longer as my account
has bash,csh,tcsh,kcsh and zcsh shells installed.
-- Created backup file /home/mike/vimrc.bak --
-- Added r/w buffer to /home/mike/.vimrc --
-- Added vi alias to /home/mike/.tcshrc --
-- Added gvim alias to /home/mike/.tcshrc --
-- Added vi alias to /home/mike/.cshrc --
-- Added gvim alias to /home/mike/.cshrc --
-- Added vi alias to /home/mike/.zshrc --
-- Added gvim alias to /home/mike/.zshrc --
-- Added vi alias to /home/mike/.bashrc --
-- Added gvim alias to /home/mike/.bashrc --
-- Added vi alias to /home/mike/.kshrc --
-- Added gvim alias to /home/mike/.kshrc --
-- INSTALLATION COMPLETED --
vicom is now ready for use. Close all existing terminals then start a fresh
terminal or logout and log back in again. This will make the aliases active.
A backup of your .vimrc file is made before the r/w buffer is placed at the start of your .vimrc file. If at any time should you wish to remove vicom, copy your vimrc.bak file to .vimrc then comment out the alias in your shell configuration script.
Vcominst will only install gvim aliases to configuration scripts provided you have Gvim installed.
Installation Completed
VCOMINST
The installation program when run first checks for a .vimrc file. Some users of gvim won't have one, so if this is the case it
creates a default one. If the .vimrc file exists a backup is made. It then creates a small r/w buffer at the start of the .vimrc file. Next it determines if vim [and or] gvim exists, depending on this aliases will be written to each shell configuration file found. If no shell configuration files are found a default .bashrc file is created with the vicom aliases added.
Vcominst also installs in the .vimrc file maps to remove white space from a file, its use is described next.
Occasionally whist commenting out blocks of code the commenter suddenly comments out a line with no
data in it as this example shows:
;;; _start:
;;; sub esp,byte +0x18 ; dispense with the pop ebx commands(+24)
;;; mov ebx,[esp+0x20] ; [esp+24+8]=argv[1] the filename
;;; mov ecx,errmsg ;
;;;
;;; mov esi,ecx ;
;;; mov eax,SYS_open ; 5 the syscall number for open()
;;; ; we already have the filename in ebx
;;; mov ecx,0 ; O_RDONLY, defined in fcntl.h
;;; int 80h ; call the kernel
During the course of writing and saving the file some white space characters have been left in your file.
They just take up disk space and do nothing. So to remove this first uncomment the space with the <Ctrl+Y>
Keys, then use <Ctrl+W> keys to remove all unwanted space and tab characters from the file. Save the
file then comment once more, this time the comments will skip the white space area.
FILENAME EXTENSIONS
vicom uses the following types of comment characters
Comment characters differ between programming languages, Vicom uses the following comment types.
Note that each comment type has extra characters than the standard comment.
Example Perl has two ## symbols where as C has two /** .. **/ symbols. The extra symbols
are to distinguish between a comment that a user has made against a line of code and a line comment
generated by vicom. Vicom will ignore normal comments entered by the user provided they do not clash
with the style below.
COMMENT FILE SUFFIX TYPE
## pl,pm,py,rb,sh,bash
/** ... **/ c,h,H,hh
/// C,CPP,cpp,c++,cxx,cc,cp
;;; asm,s,S,inc,mac
VICOM KEYS
The first four keys are active in a Vim-Gvim session in which vicom has recognized the programming language.
The fifth key is permanently installed in the .vimrc file to remove unwanted space in a file.
Keymap <Ctrl+X> Uses any one of the four comment types above to to comment lines of code.
Keymap <Ctrl+Y> Removes comments from lines of code previously set by the [Ctrl+X] key.
Keymap < b > Returns the cursor back to the last line of un-commented code.
Keymap < t > Toggles cursor between the last line un-commented and the current cursor position.
Keymap <Ctrl+W> Removes unwanted tabs and spaces from a file.
USING VICOM
To check that the aliases were installed correctly open up a new Gnome or Kde Terminal
At the command line prompt enter
alias | grep vicom
The response should be one or both of the following determined by which editors you have installed.
alias vi='vicom -mvim -- '
alias gvim='vicom -mgvim -- '
Vicom is now ready for use.
Use Vim or Gvim in the normal way such as vi someprog.cc or gvim someprog.cpp.
In a normal Vim or Gvim session the starting procedure goes along these lines Vim starts, reads the .vimrc and or .gvimrc file which sets up vim's users parameters it finally loads and displays the file. With Vicom installed the startup is changed. Vicom runs as an alias to Vim, but before calling Vim it first examines the filename on the command line. If it recognizes the file type it immediately writes comment and un-comment strings to a buffer in the .vimrc file. It clears this buffer if the file type is
not recognized. Once this buffer has been written Vicom passes control back to Vim which then continues its normal startup.
Vicom is meant to be used to rapidly comment out or uncomment sections of code whilst testing and debugging code. Once installed vicom can be forgotten about, just use vi or gvim from the command line in the normal way. Vicom will only act upon known program file types. See the filetype extensions listed earlier.
Change to a directory containing your progam files then start a vim session on for example a cpp program:
vi someprog.cpp or gvim someprog.cpp
Use the <Ctrl+X> keys and comment out some lines of code. (about 15-20 lines)
Move the cursor midway between the lines of code that has been commented out.
Use the <Ctrl+Y> keys to un-comment the code. Note that the cursor moves down each time the keys
are de-pressed, when the last line has been uncommented the cursor will jump back to the first line
and un-commenting continues.
On large programs sometimes the cursor might jump several pages up or down the program away from the area
where you are working. You can press the b for back key to jump back, and use the t toggle
key to toggle between the two positions. These keys are only active whilst a valid program file is being
edited.
Leave that shell[terminal] open and on second shell start another vim session on say a perl program.
vi someprog.pl or gvim someprog.pl
Use the same <Ctrl+X> and <Ctrl+Y> keys, comment and un-comment lines of code.
The uncomment keys skips over uncommented sections of code searching for the commented section.
By holding the key down complete functions can be commented or uncommented rapidly. It does not effect
existing comments added manually. Each program started has its own keymap buffer allowing different
comment characters determined by the source program loaded.
Close all vim sessions once you are happy with using vicom.
Files created by this package are:
vcominst -- The installation program for vicom
vicom -- The comment and uncomment program file
xydata -- The X-Y key maps stored in a binary file.
References
1. file://localhost/home/mike/cplus/project2/doc/install.html#Filename Extensions