quick start guide

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:

introduction

You can get jEdit here and the latest version of Xilize here.

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

install

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.

Plugin Manager showing xilize-jEdit.jar library as "Not Loaded". Notice "Hide Libraries" is not checked.

Normally, Plugin Manager will show Xilize in a "loaded" state like this:

Plugin Manager showing Xilize as "Loaded".

hello world

Before setting up keyboard shortcuts, try creating and xilizing a simple "hello world" file.

  1. create a new directory
  2. create a new file in that directory named, for example, hw.xil
  3. enter the text below (or copy/paste from this page)
  4. select Plugins > Xilize > translate > 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.

notes

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 *Life* and _short_ is translated to <strong> and <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.

summary

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.

menus

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.

plugins menu

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.

Plugin > Xilize > translate menu.

context menu

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.

translate > selection context-menu.

file system browser menu

Since several of the most frequently used Xilize commands act on directories and files, Xilize provides a menu attached to the File System Browser.

Xilize menu in the File System Browser (docked view)

keyboard shortcuts

Keyboard shortcuts are the most efficient way to issue Xilize commands. Use Utilities > Global Options... > Shortcuts to set them up.

Utilities > Global Options... > Shortcuts showing Xilize commands and one possible set of keyboard shortcut assignments.

Here is one possible set of shortcuts:

key assignment
F7 context popup
F8 translate pinned
F9 translate file
F10 translate directory
F11 translate branch
F12 translate project

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...".

xilize option pane

Use Plugins > Plugin Options... > Xilize — or alternatively Plugins > Xilize > options — to change Xilize configuration options.

The Xilize option pane showing default settings.

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.

general jEdit settings

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.

command overview

translate

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.

pinning

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.

insert

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.

create

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.

starting a new project

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..:

The create submenu with project fileset.. selected.

Use the new project dialog to navigate to an appropriate directory.

The directory selection/creation dialog launched by create > project fileset...

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.

File System Browser showing default files generated by create > project fileset...

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.

next steps

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.