Most of the documentation currently on the site is aimed at Xilize 2.0 users who are transitioning to 3.0. This document is a first attempt at helping new users get started with Xilize.
On this page:
This page covers install, setup, and usage of the Xilize plugin (version 3.0.2) for jEdit. (While version 3.0 does not include the XAA, Xilize Author Assistant, component of version 2.0, it does provide plugin, context, and file system browser menus not present in version 3.0.1. These menus offer most of the functionality found in XAA which in version 3.0 will ship as a separate plugin
Once Xilize is in jEdit Plugin Central you will be able to install it from within jEdit using Plugins > Plugin Manager.... Until then — or to use a more recent version — copy
xilize-jEdit.jar to jEdit's "user settings jar" directory which you can find under Utilities > Settings > jars.
Normally, Plugin Manager will show Xilize in a "loaded" state like this:
Before setting up keyboard shortcuts, try creating and xilizing a simple "hello world" file.
hw.xil, the source file you created:
Hello World This is the obligatory first example of an Xilize source file. bq. *Life* is too _short_ to drink cheap beer.
hw.html, the XHTML file Xilize created:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> <title>Hello World</title> </head> <body> <h1>Hello World</h1> <p>This is the obligatory first example of an Xilize source file.</p> <blockquote><p><strong>Life</strong> is too <em>short</em> to drink cheap beer.</p></blockquote> </body> </html>
View it with your web browser.
Let's review the translation line-by-line.
By default, Xilize will take the first line in a source file as a level-one heading:
<h1>. Like most of Xilize's default behaviors this can be changed. Also by default, Xilize will use the first line for the page title. Look for
<title>Hello World</title> in the HTML listing.
Blank lines are the fundamental separator in Xilize. Just as when writing an email message you use blank lines to separate paragraphs, Xilize understands blanks lines as separating blocks which it takes by default to be paragraphs. Thus,
This is the obligatory first example of an Xilize source file. becomes a
<p> element in the XHTML.
Blocks may begin with a signature like
bq. Signatures correspond to HTML block-level elements.
*Life* is too _short_ to drink cheap beer. translates as
<blockquote><p>...</p></blockquote>. A large number of signatures are built into Xilize which you can both customize and add to.
Notice also how the markup in
_short_ is translated to
<em> elements. This is called phrase or inline markup and corresponds to XHTML inline elements. Xilize has markup for a wide variety of HTML inline elements.
This section provided a quick exposure to
There is much, much more you can do with Xilize, but first let's get jEdit setup more efficiently and look at how you can use Xilize in that fine editor.
The primary Xilize menu is under the "Plugins" submenu of jEdit's main menu bar. Two other Xilize menus contain a subset of the primary menus items.
While not always the most convenient way to interact with Xilize, all Xilize functionality can be accessed through this menu. It is always useful as a reference of last resort. As you can see in the screen shot below, keyboard shortcut assignments are shown next to the menu item labels. You are free to assign shortcuts of your own choice; these are examples.
This menu pops-up in the main text area just below the edit cursor (i.e. insertion point). Assign a keyboard shortcut (see below) to the popup action for most convenient use.
Since several of the most frequently used Xilize commands act on directories and files, Xilize provides a menu attached to the File System Browser.
Keyboard shortcuts are the most efficient way to issue Xilize commands. Use Utilities > Global Options... > Shortcuts to set them up.
Here is one possible set of shortcuts:
Notice the command "Xilize popup" is assigned a shortcut in this example. You will want to do this too so you can popup the Xilize context menu in the text editing area from the keyboard.
It can be convenient also to put the "Xilize popup" on the text area's right-click menu. Just right-click in the text area and select "Customize This Menu...".
Use Plugins > Plugin Options... > Xilize — or alternatively Plugins > Xilize > options — to change Xilize configuration options.
Keeping the default settings is recommended.
Note, if you do not have an Xilize mode file, Xilize will ask for permission to install the one it ships with (bound in xilize-jEdit.jar). It is highly recommended you permit this. The mode file provides syntax highlighting and other settings that make working with Xilize files inside jEdit quite effective.
jEdit has an amazing set of editor configuration options which can be daunting to a new user. See this page for tips on configuring jEdit to get most from Xilize.
The translate command set offers varying degrees of granularity.
|pinned||translates the "pinned" item. See the pinning section below.|
|project||starting from the current directory, locates the project root and translates all the files in that directory and its subdirectories|
|branch||translates all the files in the current directory and its subdirectories|
|directory||translates all the files in the current directory|
|file||translates the current file|
|selection||translates the selected text either in place (replacing it) or to the clipboard|
The "current directory" is the directory containing the current file in the editor.
The project root directory is identified by the presence of a file named
root.xilconfig which may be empty. By default, whenever a non-selection translation command is given, Xilize searches up the directory tree for the root directory. This allows it to process any dir.xilconfig files higher in the directory tree that may effect the current branch, directory, or file being translated. It also allows you to translate a entire project when any of its files is current in the editor, even if the file is in a subdirectory of the project.
When a project, branch, directory, or file is "pinned", the translate > pinned command will translate the pinned item rather than acting on the location of the editor's current file.
|signature||submenus list all built-in signatures, selecting one inserts that signature at the current location in the file|
|modifier||submenus list all modifiers, selecting one inserts that modifier at the current location in the file|
|color value||pops-up a color chooser dialog, inserts the hex color value at the current location in the file. Selecting a hex color value before choosing this menu item will seed the dialog with that value.|
|relative path||pops-up a file selection dialog, inserts the relative path from the current file to the selected file at the current location in the file|
The signature and modifier submenus are intended as memory aids since Xilize provides so many possibilities. Once you become familiar with Xilize syntax, you will discover the subset of signatures and modifiers that you use frequently and type them in directly.
The create commands are a convenience for creating any of the several files that Xilize treats specially. create > project fileset prompts for directory and creates a complete set of initial files as a starting point for a new project. Any of these files may be deleted or changed to suit your needs.
Note: the create commands will not overwrite existing files.
See starting a new project below for more information.
A new project can be started by simply creating a new file, however, using the create > project fileset... can facilitate the process.
First popup the context menu and select project fileset..:
Use the new project dialog to navigate to an appropriate directory.
Press New... to create a subdirectory. Press Select to create the new fileset in the chosen directory. Xilize creates the fileset and loads the new
index.xil into the editor.
With index.xil in the editor, issue the translate > file command — or any of translate > project/branch/directory — generate index.html. Now you can experiment as much as you like: delete or change any of the files, add additional *.xil files, add subdirectories, etc.
The Xilize home page contains pointers to all documentation — much of which is still transitioning from v2.0 to 3.0. Still, there is much to get you going. Links of particular interest to new 3.0 users:
Xilize v2.0 users should look at the migration notes before translating 2.0 projects with the 3.0 engine.