Emacsish Documentation

Documentation

The seven features included with this plugin were inspired by my transition from Emacs to Eclipse. Eclipse is a great IDE, but there are things in Emacs that I miss. Here's an overview of the seven features added by this plugin:

Shell Selection

This is probably the most interesting and useful feature. When the shell button is pressed (Edit / Shell Selection or Ctrl+Alt+|) a dialog is displayed that allows the a subshell to work with the current selection in various ways The command to be run may either be the specified explicitly, or it may be the selected text. Likewise, the standard input to the command may either be specified explicitly or it may be the selection. By default the selection is replaced with the standard output from the command.

Shell selection may also be used to run commands where the output is not needed. Also, the output may be displayed in a new window, which is useful when the intent is to see the output of the command, not to alter the document.
The command is tokenized strictly by whitespace. Only two additional changes are made by substituting the following tokens with their values:

  • %d - The fully qualified directory of the file.
  • %f - The fully qualified filename of the file.

The regular expression support ("Expand REs" in the preference page) is an admittedly unintuitive attempt and providing something like wildcard support in a platform independent manner. For example, if you wanted to list all the *.C files in the current directory you could do so with the following as the command (assuming you have "ls" or "ls.exe"):

    ls -l .*\.C

Some possible usages include.

  • Running the "date" command (Linux) to insert the date into the current document.
  • Using "diff" (Linux) to see the difference between the current document and previous versions with something like this:
          diff -uw %f.orig %f

    as the command.
  • Getting a quick listing of the directory that the file is in:
          ls -l

    This feature is similar to Emac's shell-command-on-region.
  • Sort Selection

    This small feature sorts the selected text by strict ASCII order. When the sort button is pressed (Edit / Sort Selection or Ctrl+Alt+1) the highlighted text is sorted. You don't have to get the selection perfectly at the start of the first line or the end of the last line. Usages include anything that you might want to sort. For example, you have a text file that has a list of names in it and you want to sort just that list without altering the rest of the document. Possible future enhancements might include other ways of sorting, such as ignoring whitespace, etc.
    Create Backup

    This small feature makes a backup copy of the current file. The contents of the current page is written to the file for the current page, but with the suffix specified. By default this feature appends ".orig". This feature may be helpful if, like me, you start each new bug fix (or whatever it is you want to do) with a clean build tree that is in sync with version control. Each file is backup up to .orig when it is first modified. The result is a build tree where it is possible to

    1. Determine the files changed by searching for *.orig.
    2. Determine if any of the files changed will require a merge by comparing version control to the *.orig files.

    This is similar to Emac's auto-save-mode (creating backup files with a suffix of "~").
    Set Mode

    This odd feature allows the mode (the editor that Eclipse thinks is appropriate for the file as a function of the files name and contents) of a file that has already been opened to be forcible changed to something else. Although it is possible to configure the file associations and contents types in Eclipse it's often the case when either working with projects that other people work on or when there are weirdly named intermediate files (MyClass.JAV.dos-new-lines, or whatever) it does not make sense to constantly reconfigure Eclipse. Update: This feature is somewhat obsolete in Eclipse 3.3 and later since Eclipse now allows files to be opened with an arbitrary editor. Possibly this feature might still be helpful if there is a need to change the editor of a file after it has been opened.

    This is similar to Emac's set-mode.

    Save As External

    Eclipse prefers that files be added to projects within the workspace prior to working with them. Although the File / File Open menu item was added as a concession to those who wanted to open external files without linking them into a project there is still not a way of creating a new external file.

    Save As External brings up the system save as dialog. The contents are directly written to the specified file using Java file IO.

    One way of creating a new file is to Use the File / New / Other / General / Untitled Text File menu item and to this use this feature to save it to some external location.

    Ideally this would work better when the page being worked with does not currently have a file. In that case perhaps it should take on the filename specified.

    This is similar to Emac's write-file.

    Save External

    This the same as Save As External except that the filename is not prompted for if it was specified previously for the current page.

    This is similar to Emac's save-buffer.

    Format Paragraph

    This command allows paragraphs (or just individual lines) to be hard-wrapped so that a given column is not exceeded. This is similar to Emac's format-paragraph command. See the "Format Paragraph" in the preference page for ways that this command can be configured.

    This command can be used while typing plain text in the same way that M-q can be used in Emacs. You probably want to keep "Break Words" off in the preference page. If "Join Lines" is off then only long lines are altered.

    There is additional work to be done. Please see the "TODO" file for details on what that work is. Feel free to send me any comments or questions you might have about this plugin at selliott4@austin.rr.com.