# &appfull;

User Manual

# &appfull; Manual &manrevision;

This is the User Manual &manrevision; to the &appfull; &appversion;, a free software that provides a user-friendly tool for editing DocBook and other document types created in the Extensible Markup Language Format (XML). It aims to hide the complexity and jargon of XML behind a friendly Graphical User Interface (GUI).

Sean Wheller
1999-2004 The Conglomerate Team
0.1
2003-12-30
SW Manual V0.0.1 correlates to software V0.7.10
This manual describes version &appversion; of &app;.
¬icefdl; ¬icegpl;

## Preface

### About the &app; Project

text

### Getting Involved

The &app; project is managed as an open source initiative to develop the ultimate user-friendly XML editing system. As such, help in the form of productive contribution is always welcomed.

The first step in joining the project, is to join the conglomerate-devel mailing list. This is where our development discussion happens.

Next, it is recommended that you join the conglomerate-auto mailing list, which receives email every time something changes in our bug database.

Then proceed to download a copy of the latest source code as described in .

Things you can do to help:

- Development: Add support for new XML document types, fix bugs and implement new features. If you're a programmer, looking for something to get stuck into, we've prepared a list of easy-to-fix bugs, which should let you become familiar with the code without having to look at all of it at once.

- Testing: Test the various functions of the editor, report replicable bugs not already listed in the bug tracking system, please refer to the list of things we already know about.

- Localization (I10n): Localize &app; into your own language. Localization is being co-ordinated by the Gnome Translation Project.

- Translation (I18n): Translate the &app; User Manual and other documents into your own language.

- Documentation: Write articles, add new sections, and improve on exiting sections within the documentation.

- General: Suggest new features that would make it easier to use get your work done - or are just simply cool!

### Acknowledgments

Text

&conventions;

## Introduction

The &appfull; is a free, user-friendly XML editor, for DocBook and other XML document types. It aims to hide the complexity and jargon of XML behind a friendly GUI.

&appfull; is one part of the &app; project to create a complete structured information authoring, management, archival, revision control and transformation system. The &appfull; uses XML semantics and powerful graphical editing, coupled with a centralised storage model and a flexible transformation language to create an environment that is easy to use, produces high-quality structured output, and lets the user target several formatted output file types from a single XML source.

### Requirements

The &appfull; can be run on any Linux system that has Gnome 2.4 or higher installed. When this condition is met &app; can be run under the Gnome or KDE desktops.

&app; is dependant of the following libraries and their development versions:

- libxml-2.0 >= 2.0.0

- libxslt >= 2.0.0

- libbonobo-2.0 >= 2.0.0

- libbonoboui-2.0 >= 2.0.0

- libgnomeui-2.0 > 2.0.0

- libglade-2.0 >= 2.0.0

- intltool-0.2.8 > 0.2.8

&app; &appversion; is an unstable release. Current releases are intended as previews that some people may find useful.

### Installation

If &app; was shipped with your distro then you should be able to install it from the distibution source using a Software Installer. Please refer to your distro documentation for information on how to install new packages.

Alternative methods of installation include installation from or .

#### Installation from tarball

Releases are frequently packaged into tarballs and placed on the project CVS at SourceForge.

When a new release is announced the tarball may take upto 24 hours to display in the Web based CVS interface.

General installation overview

- Start a Bash session.

- Login as root.

- Copy the tarball to a location such as `/usr/src/packages/`.

  `cp filename-0.2.3.tar.gz /usr/src/packages/`

- Change to this directory.

  `cd /usr/src/packages/`

- Extract the tarball. This will create a new folder `filename-0.2.3`

  `tar xzvf filename-0.2.3.tar.gz`

- Change to the new folder.

  `cd filename-0.2.3`

- Type the following, followed by Enter.

  `./configure`

- If there are no errors, type the following, followed by Enter.

  `make`

  If there are errors, resolve them if required.

- Type the following, followed by Enter.

  `make install`

  This will install to the default path `/usr/local/bin` which should already be in your environment `PATH`, type `echo $PATH` to view your `PATH` if you are not sure.

#### Installation from CVS

If you don't mind running on the "bleeding-edge" of development, you may also run your installation from the project Concurrent Versioning System (CVS) located at Gnome.

As a result of the ongoing application of patches and addition of new components to the source, installation from CVS is not guaranteed to work.

### Getting Started

You can start &app; in the following ways:

From the Applications menu

  Choose Main Menu Utilities Texteditor Conglomerate XML Editor .

From the Command Prompt

  To start &app; from the command prompt, type `conglomerate`, then press Enter.

  You can also open an XML file directly from the command by passing the name of the XML file to open when &app; starts, like this `conglomerate filename.xml`.

When you start &app;, the following window is displayed.

&app; Start Up Window

This is the main window of the &appfull;. It provides basic options that can be used to create, open and import files when the &app; is first started. It also provides options to close the main window, exit the &app; and to access the user manual and about dialog which displays version and related information about the &app;. The main window becomes the editing interface when a new document is created or an exiting document is opened. New options will then be displayed, they are described in .

If you want to quickly get a glimpse of the editor window, create a new document as follows. Documents are create with the help of templates, skeleton files that provide a basic structure from which to start documenting. &app; provides several templates, to get us started we will use the "Docbook Article" template.

Create a new document

- Choose File New ( Ctrl N ). A wizard dialog is displayed. This will assist you in selecting a template to start your document.

- Click Forward to display the list of available templates.

- Select the `Docbook Article`, then click Forward. The wizard now has all the information required to create a new Docbook XML Document of the type "Article".

- Click Apply to create the Article. This will open the .

Congratulations you have just created your first document with &app;. Now you will have to learn to get arround the and perform common operations such as , , and generally your text.

### Supported XML Document Types

Ulimately the &appfull; is being developed to support creation and editing of any XML wide variety of data or document orientated XML instances.

The following XML document types are currently supported, with time more will be added:

A full list of the the XML Document Types supported can be found in . This document also provides an introduction to each of the document types and references where you can find more information.

## Editor Window

As the name implies, the editor window is used to edit documents. This window is displayed when a new document is created or an exiting document is opened and has more options than the main window. The figure below shows the editor window after a new "Docbook Article" has been created.

&app; Editor window

The editor window is comprise of the following elements:

Window titlebar

  The window titlebar shows the filename of the document being edited. If the document has not been saved to a file the default document name will be `(Untitled)`. The window titlebar also provides the standard menus and controls of the Window Manager.

Menubar

  The Menubar provides menus that arrange and provide access to all the functional operations of the &appfull;. The menu options are described in the .

Toolbar

  The Toolbar provides quick access to the most commonly used operations of the &appfull;. The menu options are described in the .

Document Area

  The Document Area is the main workspace.

Status bar

  The Status Bar shows the "Document Type" of the open document and provides a window "Resize" control with which to increase or decrease the size of the editor window.

### Editor Window Menus

The Menubar provides menus that arrange and provide access to all the functional operations of the &appfull;. The following options are available:

Editor Window Menus and Options

File

  Use the File menu, to perform the following tasks:

Edit

  Use the Edit menu, to perform the following tasks:

Tools

  Use the Tools menu, to perform the following tasks:

Help

  Use the Help menu, to display the &appfull; "About" dialog and access the Online Help.

### Editor Window Toolbar

The Toolbar provides quick access to the most commonly used operations of the &appfull;. The following options are available:

Editor Window Toolbar Options

Open

  Use the Open button, to that already exists.

Save

  Use the Save button, to that is already save to a new file with a different filename.

Undo

  Use the Undo button, to .

Redo

  Use the Redo button, to .

Cut

  Use the Cut button, to .

Copy

  Use the Copy button, to .

Paste

  Use the Paste button, to .

### Editor Window Document Area

The document area is the main workspace. It provides two views of the open document:

- (left-pane)

- (right-pane)

Each view is shown in a pane. The separator between the panes can be used to adjust how much of the document area is taken up by each of the views.

#### Outline view

Shows the structure of the document in a "Tree View" control. The outline view provides two XML tree perspectives of the open document:

- (left-tab)

- (right-tab)

Both perspectives enable the tree structure of the open document to be navigated. Starting from the root node of the tree, elements that have "child" or "sibling-elements" can be expanded and collapsed.

A context-sensitive pop-up menu is available when a selected node is right-clicked with the mouse.

The options displayed on the pop-up are dependent on the selected node type. For example, when nodes that are representative of the tree root, XML declaration, or document type declaration are selected, the Cut, Copy, Paste into, Paste before, and Paste after options are not displayed. When nodes that are representative of an XML element that forms part of the vocabulary of the "Document Type" are selected, these options will be available as shown in the figure below.

Outline view pop-up menu

Use the outline view pop-up menu to perform the following tasks:

- Insert a after the current element.

- Insert a directly under the current element.

This pop-up menu is also available when an XML element is right-clicked in the .

##### Overview tree perspective

In Overview perspective the tree nodes of the open document are shown by their Docbook element name using a logical view. The value, or text, contained by the element is not displayed. For this reason, paragraph or para elements within the tree cannot be expanded.

The element name shown in the tree view is not always the same as that shown in the . This is because &app; renames elements according to the information provided by a "Display Specification" which can define an alternate bame for any element type. These names are not valid element names and are therefore not used to created XML elements within the XML source file. Instead they are mapped to valid Docbook elements which are what is created in the open XML source file or document. If they were to be inserted using the names provided by &app;, the document would be invalid against the rules specified by the documents Document Type Definition (DTD). A listing of the mappings for various document types is provided in .

Outline view in Overview perspective

##### Raw XML tree perspective

In Raw XML perspective the tree nodes of the open document are shown using the full XML syntax, so the "greater-than" (<) and "less-than" (>) characters the surround element names are shown. The value of the element, the tagged text, is also shown alongside the element in inverted commas (see ).

Outline view in Raw XML perspective

#### Page view

The page view shows the content of the open document and the elements in which various content typesare tagged.

Block elements such as article, sect1, sect2, and figure are shown in "structural element borders" and inline elements are displayed with a line beneath the tagged text (see ).

The "structural element borders" for nested block structures are alternately colored to help readability. The captions used, correspond to the &app; equivalent of the Document Type elements. For example, in the following figure the &app; "Paragraph" caption will correspond with the Docbook `<para>` element. For inline elements the caption name is written in the center of the line beneath the tagged text. A listing of the &app; names is provided in for each of the .

Page view display of elements

Wrapped captions can be expanded or collapsed by clicking the mouse on the caption label. In both states are shown. Notice that the content for "Subtitle", "Title" under the articleinfo, and the "Author" has been hidden. Inline elements cannot be collapsed.

Wrapped caption states - expanded and collapsed

Two pop-up menus are available in the page view, each is associated with a different object:

Block Element Menu

  This is the same menu that is available when an XML element is right-clicked in the , only this time the menu is displayed when the caption label is right-clicked. Use the block element menu to:

  - Insert a after the current element.

  - Insert a directly under the current element.

Text Menu

  This menu is displayed when text contained in a block element is right-clicked. It displays a list of options that allow you to:

### Window Management

The &appfull; uses your chosen Window Manager to create the main and editor windows. Multiple instances of &app; can be run at the same time and multiple editor windows can be opened, each editor window displaying a single document. With so many windows open, window management can become a problem. Fortunately, most desktops like GNOME and KDE have a Taskbar with powerful desktop management features. These should enable you to maximize the usage of your screen real-estate. The standard window controls of your desktop environment will also help you to define the behavior of your &app; windows.

Within &app; there are two options for window and application management:

#### Close

As multiple editor windows can be opened, editor windows can also be individually closed by selecting File Close or using the keyboard combination Ctrl W .

This option should not be confused with the `Exit` option, which will close all &app; windows associated with a &app; instance and terminate the application.

#### Exit

Selecting File Quit or using the keyboard combination Ctrl Q on the main window and any editor window will close all windows associated with the &app; instance and exit the application.

## Performing Tasks

### File Management

#### Create a document

When &app; is first started main window does not provide editing functionality. To display the editor window Create or .

Creating a Document

- From the main window menu select File New . The Create New File wizard is started.

- Click the Forward button. The wizard displays alist of document type templates.

- Select a suitable template from the list, then click the Forward button. The final dialog of the wizard is displayed.

- Click the Apply button. The Editor Window is displayed with the selected template ready for editing.

#### Open a document

The option to open an exiting document can be performed from the main and editor windows. The following procedure is performed from the main window.

Opening a Document

- From the Menubar select File Open . The Select an XML File dialog is displayed.

- Use the Folders list view to Navigate to the folder containing the required file.

- Use the Files list view to select the file, then click OK.

- The selected file is opened in the editor window.

#### Save a document

The first time you save a document you will be required to provide a file name and select a location where the file will be written to disk (see ). Once a document is saved to disk, the save operation will write directly to the open file.

Save your document before you start and regularly there after to avoid loosing work due to unexpected software failure.

#### Save As new document

It is sometimes convenient to save an exiting file to a copy using a new filename or to a different location.

Assuming that a document is already open proceed as follows.

Save As new document

- Select File Save As ( Ctrl+Shft+S ). The Save XML As dialog is displayed.

- Use the Folders list to navigate to the folder where the new copy of the file will be saved.

- Enter a filename in the Selection field.

- Click OK to save a new copy of the file.

#### Import a document

text

#### Export a document

text

#### Inspect document properties

text

### Editing

#### Typing text

text

#### Undo actions

Text

#### Redo actions

Text

#### Cut text and elements

text

#### Copy text and elements

text

#### Paste text and elements

text

#### Paste into an element

text

#### Paste before an element

text

#### Paste after an element

text

#### View XML source

text

### Markup

text

#### Insert Elements

text

##### New sibling-element

text

##### New sub-element

text

##### Insert inline elements

text

##### Remove inline elements

text

#### Cleanup XML source

text

#### Modify Element Properties

text

##### About XPath

text

##### Scope

text

##### Language

text

##### Revisions

text

##### Advanced

text

### Validating

text

#### About validation

text

#### Validate a document

text

## Designing Display Definitions

Display specifications are XML files saved with the extension `XDS`. They hold various types of information, that annotate a one or more Document Types that may be edited with the &appfull;.

Display specifications do not take the place of DTD, XML Schema, or XSL files. Their function is only to provide information to &app; when editing a given XML instance.

Because display specifications are XML, they can be easily modified in order to customize the &app; editing environment to the particluar requirements of a user or a specific XML file.

A complete definition of the &app; XDS DTD is available in .

The following operations can be performed on XDS files:

### Edit a Display Spec

text

### Dump a Display Spec

text

&doctype_supp; &xds_ele_ref; &xds_dtd_def;
Dummy

  Now you see me, next you won't