Organize your syntax notes and code
Several good text editors are available on the market, but I've been using Notepad as my editor of choice for command-shell scripting. I chose Notepad primarily because it's already installed on any PC or server on which I need to knock out a few quick lines of code. But one important limitation of Notepad (and many other editors) is that it doesn't provide an easy way for you to quickly scan existing scripts for a particular piece of code that you want to work with or that you might need to complete a new script.
I often find snippets of code on the Internet that I save and plan to test when I have the time. Those snippets usually get lost in all the scripts that are on my home and work PCs. To find the code I'm looking for, I typically scan several files in the most likely locations, such as My Documents or the Desktop, then become frustrated when I come up empty-handed. The administrative servers that run many of my scripts are the epitome of organization, with each script in its own folder inside a logical hierarchy of directories. Unfortunately, I haven't been as successful at organizing my development environmentâ€”until now.
Recently, I obtained a beta version of the new Microsoft Office OneNote 2003 note organizer software. I looked at OneNote and thought that although it seemed to be a powerful note organizer, it was unlikely to be of any use to me for writing scripts. But I had OneNote open one day while I was working on a script, and I pasted some code into the application. I was instantly hooked on the interface and the possibilities for organizing my command-syntax notes and code samples.
OneNote lets you organize your notes in folders, sections, pages, and subpages. OneNote's tabbed interface makes all the sections and pages easily accessible. Figure 1 shows how I've set up OneNote to hold my command-syntax notes.
The system tray icon gives me a quick way to launch OneNote and copy some code into an organized framework. In the past, I've tried to use Microsoft Word as a code editor or code organizer, but Word often introduces problem characters such as double quotes that look like ASCII characters but that cause the code to fail when I use it in a script or paste it into a command-shell prompt. I've written scripts in OneNote, and the only problem area that I encountered was a minor difficulty with the way the application handles tabs. When you paste code that contains tabs, OneNote introduces a carriage return after the tab. But I use very few tabs in my command-shell scripts, and this idiosyncracy is a minor problem considering the advantages of using OneNote to organize my scripts and code snippets.
OneNote lets me spell-check my scripts, which I find handy for the code comments and header information. This capability has saved me much embarrassment by helping me discover and correct all typos in code comments before I send the script to my boss. I also find OneNote's ability to search for words useful. The search results highlight the search terms so that I can easily see the word matches. I use OneNote's highlighting and font colors to help me delineate code sections and match up parentheses within For loops. And I use the application's Note Flags to highlight important lines of code or syntax information. I can even capture a picture of a command-shell window or of some results that go with a snippet of code and paste the picture into my OneNote page.
A OneNote Starter Kit
I've put together a set of 15 starter files that you can use with the OneNote beta, trial, or production software. These files provide some examples of how you might want to customize OneNote to serve as your script organizer. To download the starter files, go to http://www.winnetmag.com/windowsscripting, enter 41199 in the InstantDoc ID box, click the
When you open the starter files in OneNote, you'll see that I've created tabs for the most common shell-scripting commands. Each tab contains pages that include syntax notes about the command from the online Help files and some samples of code use. Double-click any file that has the .one extension to launch OneNote and access the file's tabbed scripting content. You can add more commands, scripts, and code snippets to the files to create a well-organized and invaluable scripting repository.
You'll notice I've included a Universal Environment Variables tab in the starter files. Code reuse is something most scriptwriters strive for, and thoughtful use of universal environment variables can help make your code more modular and easily portable. For some suggestions about using these variables, see the sidebar "Universal Environment Variables."
You can download OneNote 2003 trial software for free at http://www.microsoft.com/office/onenote/prodinfo/trial.mspx. The OneNote 2003 Evaluation Kit is also available on CD-ROM for a nominal charge. To use OneNote, you must be running Windows 2000 Service Pack 3 (SP3) or later.
OneNote has helped me take substantial steps toward organizing my code collection, and I think you'll find it can do the same for you. You'll probably also discover many more ways this application can be a great companion scripting tool for your favorite code editor.