Copyright © 2007 Lorenzo Bettini
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".
Sourcehighlightide is an IDE for GNU Source-highlight (given a source file, produces a document with syntax highlighting); in particular, it is useful when you have to develop a new language definition file for source-highlight (Source-highlight reads source language specifications dynamically, thus it can be easily extended (without recompiling the sources) for handling new languages), modify an existing one, and, most importantly, debug a language definition file.
Sourcehighlightide home page is http://srchighliteide.sourceforge.net.
Table of Contents
Sourcehighlightide is an IDE for GNU Source-highlight (given a source file, produces a document with syntax highlighting).
Source-highlight reads source language specifications dynamically, thus it can be easily extended (without recompiling the sources) for handling new languages. It also reads output format specifications dynamically, and thus it can be easily extended (without recompiling the sources) for handling new output formats. The syntax for these specifications is quite easy (take a look at the manual).
Sourcehighlightide is useful when you have to develop a new language definition file for source-highlight. A language definition file makes use of regular expressions, and if they become complex it might be hard to understand how they are matched. Source-highlight already provides some mechanisms for debugging a language definition file; Sourcehighlightide provides a graphical interface to debug a language definition file: it will show which regular expression is matched during the formatting of the input file, and you can process the input file step by step (i.e., an expression at time), and you can also see the output while it is produced.
Table of Contents
As you can see from the following screenshot, Sourcehighlightide is a MDI (Multi Document Interface) application, so you can have many files open at one time. Moreover, it provides the basic commands that are common to every GUI application, so we will assume their knowledge throughout this manual. In the screenshow we see two opened editor windows.
The files that you open with the standard Open commands (or that you create with the New command) are intended to be language definition files for Source-highlight (we refer to Source-highlight manual for further details about such files). This file is shown in the left text area of the editor window.
On the right of the editor window we have some tabs.
The "Regex" tab permits viewing the regexp automaton created by source-highlight from the current language definition file (obtained by using the command line option
--show-regexof source-highlight). It is shown when you press the button "Regex".The "Example" tab permits opening an input file for source-highlight, i.e., a file that source-highlight must process and format with syntax highlight. You're allowed to modify this input file, and save it (or save it with a different name).
The "Formatted" tab shows the result of the formatting into HTML of the above mentioned input file.
The "Style" has the same functionalities of the "Example" tab (open/save/save as) and permits opening (and possibly editing) a style file, that Source-highlight will use for formatting the input file (we refer to Source-highlight manual for the syntax of these style files).
The "Output" tab shows the result of the formatting into HTML of the above mentioned input file. However, differently from the "Formatted" tab, here you can see the actual HTML generated code, i.e., without being rendered.
Once you opened and input file, you can press the button "Update": this will run source-highlight that will process the input file; then you can see the output HTML file in the "Formatted" tab (and the actual HTML code in the "Output" tab). This way, you can test your language definition file, by watching how the input file is formatted (according to the language definition file you're editing).
In the lower part of the editor window, the source-highlight command is shown (and if the checkbox "Verbosity" is checked, source-highlight will be run with the --verbosity option). You can clear the text area with the output using the "Clear" button.
Sourcehighlightide requires some configuration, basically related to Source-highlight itself. The configuraton dialog (shown in the following screenshot) can be accessed through the "Settings" menu.
In this configuration dialog you can specify the complete path to the source-highlight executable, the value for --data-dir source-highlight command line option (i.e., where source-highlight searches for its configuration files); concerning this option, you need to specify it ONLY if it is not the default source-highlight directory (thus, unless you want source-highlight to use a different directory for these files, or you installed source-highlight not using the standard procedure, you probably leave it empty).
Further command line arguments for source-highlight can be specified in the "Arguments" text field. Then you can specify the temporary directory that source-highlight will use for generating output files (you must be sure you have the required privileges to write in that directory). Finally, you can specify whether to save the modified files in an editor window (i.e., the opened language definition file, the example file and the style file) before running source-highlight. The verbosity check box sets the default for the verbosity check box of editor windows (of course, each editor window can override this option).
Although you can use Sourcehighlightide for testing a language definition file while you're editing it (simply press the "Update" button each time you modify the language definition file, or the input file you want to format), the feature that can be most useful is the debugging mechanism.
You start debugging by using the button "Debug" (instead of "Update"), and then press "Step" for formatting element by element the parts of the input file that is to be formatted. You can interrupt the debugging by toggling the button "Debug" again. The debugging steps at each matched regular expression and the one that was matched is shown highlighted in the text area of the language definition file. The "Formatted" tab shows the parts of the input file that are already formatted. In the screenshot above we have just matched a quoted string inside an #include environment.
Notice that if the language definition file includes another one, the editor window will open the included file containing the current matched regular expression.
Table of Contents
- -> (Ctrl+N)
Creates a new document
- -> (Ctrl+S)
Saves the document
- -> (Ctrl+Q)
Quits Sourcehighlightide
- -> (F1)
Invokes the KDE Help system starting at the Sourcehighlightide help pages. (this document).
- -> (Shift+F1)
Changes the mouse cursor to a combination arrow and question mark. Clicking on items within Sourcehighlightide will open a help window (if one exists for the particular item) explaining the item's function.
- ->
Opens the Bug report dialog where you can report a bug or request a ?wishlist? feature.
- ->
This will display version and author information.
- ->
This displays the KDE version and other basic information.
Sourcehighlightide
Program copyright 2007 Lorenzo Bettini http://www.lorenzobettini.it
Documentation copyright 2007 Lorenzo Bettini http://www.lorenzobettini.it
This documentation is licensed under the terms of the GNU Free Documentation License.
This program is licensed under the terms of the GNU General Public License.
Sourcehighlightide can be downloaded from http://sourceforge.net/projects/srchighliteide.
You can also get the latest (development) sources through CVS, you find the instructions here: http://sourceforge.net/projects/srchighliteide.
I'll describe new features in new releases also in my blog, at this URL: http://tronprog.blogspot.com/search/label/sourcehighlightide
In order to successfully use Sourcehighlightide, you need KDE libraries, of course, and an already installed version of Source-highlight (we refer to Source-highlight home page for further details about it).
If you obtained sourcehighlightide through CVS, then, you must first run
make -f Makefile.cvs
In order to compile and install Sourcehighlightide on your system, type the following in the base directory of the Sourcehighlightide distribution:
%./configure%make%make install
Since Sourcehighlightide uses autoconf and automake you should have no trouble compiling it. Should you run into problems please report them to the KDE mailing lists.
However, in order to make sure that sourcehighlightide is installed correctly in the kde path, the safest thing to do is to run the configure script as follows:
./configure --prefix=`kde-config --prefix` kde_htmldir=`kde-config --install html --expandvars`
Then, when you run make install you might have to gain superuser privileges.