Table of Contents
The in-place editor is a text editor designed to integrate with the KMT and streamlines the process of editing DocBook articles by providing functions for validation, formatting, and some quality checks.
The in-place editor (IPE) is packaged as a [ http://help.unc.edu/?id=3669 ] Java Web Start application which is launched from within the KMT. When you click the button on the "Edit Content" screen in the KMT, a new Java application is launched. In order to use the IPE, you will need a recent (1.5 or greater) version of the [ http://help.unc.edu/?id=3599 ] Java plugin installed.
Note
The IPE also requires access to functions that Java regards as "dangerous"; the idea is that the application resides on a server you may or may not be able to trust, and so when such an application requests permission to read or write files on your hard drive or send data over the network (both of which the IPE does), Java requires that the user explicitly grant this permission. To make use of the IPE easier, ITS Knowledge Management has signed the application and registered the signature with a certificate authority that Java trusts. So, the first time you start up the IPE (assuming Java is installed and working), you will see a dialog similar to the following:
If you wish to use the IPE, you
must
select either
or
from the security dialog window. Be sure to verify that the question asserts that
kmt.unc.edu has signed the application. If you select
, the IPE will not start.
The application window divides into four functional parts.
Screenshot of the in-place editor opened to this document
At the top is the menu bar. The menu is where you'll find entries for reading the last working copy from the KMT, saving your current work to the KMT, saving a local copy (to your hard drive), and closing the editor window (which exits the application). The window contains the cut, copy, paste, and undo commands. The menu collects the various "XML-aware" features, including the validate, format, preview, and various insert commands. Take a note of the keystrokes you can use as shortcuts for these features, we think you'll find editing goes much faster if you don't have to take your hands off the keyboard to grab the mouse.
To the right of the menus are some few shortcut buttons for inserting XML structures: from left to right, the actions are Add Paragraph Tags, Add hyperlink, Add Image, Add Section, and Preview.
For Macintosh Users
Where keystroke commands refer to the Ctrl key, substitute the Apple Command key.
Below the menu bar is the text editing window, which provides a basic text editor that includes the familiar cut/copy/paste text editing features and adds a few DocBook-related ones.
In addition to basic text editing functions, the editor window supports adding DocBook image tags via drag and drop. Basic use of this feature is simple: locate an image file on your hard drive, drag it into the editor window, and "drop" it. The editor will pop up a dialog asking you to describe the image (the text you supply is the textual alternate for the image, so please make sure your description is useful in a non-visual context). Once you've supplied a description, an image tag that points to the file you dropped is created and inserted into the document at the "drop-in" point (note that it can be hard to target things finely, so it will probably help if you clear out a little empty space in the document before you drop an image onto it).
Although using drag-and-drop to add images to your documents helps to keep filenames in your document and in the KMT straight, the in-place editor does not provide a feature for automatically synchronizing the images referred to by your document with the ones the KMT stores in the file bin, so remember to upload any images you add to the document's file bin.
Below the editor area is the error list window. Any errors detected during validation will be displayed in this window. For each error message (and note that one mistake might generate multiple error messages), a line and column number will be shown, along with the content of the message. Clicking on a message in the error list window will move the cursor to the line in the text area associated with the error message. This lets you quickly jump around your document and fix multiple errors.
Below the error list is the message and status area, which appears as a thin gray bar. On the left hand side of this area is where you'll see messages pertaining to various commands, such as "your text was not found" or "save to KMT succeeded" or "validation failed." If you let the mouse hover over this area, you will be able to see the full text of any messages that might be too long to show in their alotted space. The next space over is a progress bar that shows the progress for processes that don't complete (nearly) instantaneously, such as loading/saving to KMT, checking links, and formatting. Next to the progress bar area is the status area, which shows you whether your document is known to be valid, known to be invalid, or whether its validity is unknown. Finally, on the bottom right of the application window, is the line number indicator, which shows you which line the cursor is on.
The in-place editor may be launched from the "Edit Content" page in the KMT, and it is only available for "Full" documents. The application is designed primarily around two functions : loading and saving XML documents from and to the KMT. It can also load and save files that are stored on your computer, by selecting or from the menu. It is important to keep in mind that what you're working with is the working copy of your document. Changes you make with the editor will only be made permanent after you select on the "Edit Content" page (this is the same web page from which you launch the in-place editor).
The keystrokes and commands for doing basic editing procedures are similar to those in most text editors and word processors. Cut , Copy , Paste , and Undo are all available from the menu; you can also use the familiar keystrokes Ctrl - X , Ctrl - C , Ctrl - V , and Ctrl - Z for these commands, respectively.
Simple searching is supported through the → command (keystroke: Ctrl - F ). However you activate the feature, the application will pop up a dialog that lets you customize your search for case sensitivity, direction, and whether the search should 'wrap' around if it your search text is not found. To quickly scroll through all the occurrences of your search text, just keep hitting Enter or clicking the button until you find the occurrence you're looking for.
The editor is also DocBook (and KMT)-aware in a number of ways.
DocBook-related features
-
Tag Completion. While you are entering text, if you type in
</(i.e. you begin to close an XML tag), it will attempt to 'auto-complete' that tag for you, searching backward through the document for the last tag that was opened. This helps you keep your tags balanced, which is the source of much XML editing heartache. Note, though, that the tag-completion feature is not (as of the time of writing) aware of which tags are valid DocBook, so mind your spelling! -
Validation. Validation checks will be run whenever you pause typing for a short period, or when you try to save the document to the KMT, or when you select the (keycode: F1). An icon at the bottom of the screen indicates whether the validation succeeded or failed, and if the document is not valid, the error will be indicated in the error list window.
-
Formatting. (keycode: F2) The editor can format or pretty-print the document for you, indenting tags and wrapping lines where appropriate. The contents of elements with a literal layout
progamlistingandliterallayoutwill not be re-formatted when you use this command (some additional attributes will be added to such elements). Note that the document must be well-formed in order to be re-formatted. -
Link Checking. (keycode: F3) The editor can detect and check a wide range of links from your document, including links to other KMT documents, as well as to other sites. To check links, select from the menu. Your document will be scanned for
ulinktags, which will all be tested (checking links can take quite a while, so keep an eye on the progress bar at the bottom of screen), and a new window with the results will be shown. Just as with the format command, link checking requires that the document be well-formed in order to succeed. -
Preview. (keycode: F12 ) You can generate a preview that approximates how your document will look when it is transformed to XHTML for display on help.unc.edu and other sites. To activate this, select → . When the preview XHTML is ready, a new browser window or tab (depending on your operating system and settings) will open.
-
Insert DocBook XML structures. A number of different DocBook constructs can be inserted quickly using keystrokes or menu commands.
-
Add Paragraph Tags. (keycode: Ctrl - P ) Surrounds the currently selected text with opening and closing
paratags. If no text is currently selected, inserts the opening tag before the current cursor position, and the closing tag after the cursor position. -
Add List Item. (keycode: Ctrl - E ) In a manner similar to the 'add paragraph' function, turns the currently selected text into a complete
listitementry. This should reduce the amount of typing needed to enter both ordered (numbered) and unordered (bulleted) lists. -
Add hyperlink. (keycode: Ctrl - L ) Turns the currently selected text into the text of a
ulinktag. -
Add Section. (keycode: Ctrl - Alt - S ) Inserts a skeletal
sectionelement set, complete withtitleelement (which will contain the currently selected text, if any) and an emptyparaelement. -
Add Image. (keycode: Ctrl - Alt - I ) Inserts the basic tags necessary to place an image in the document. If any text is selected when this command is entered, it will form the
textobjectportion of the image (this is the text of thealtattribute value when the item is displayed in HTML format).Note you can also add the tags necessary to support embedding images via Drag and Drop.
-
Insert Table. Pops up a dialog that allows you to enter an (optional) title, and (required) number of rows and columns for the table. If no title is supplied, a DocBook [ http://help.unc.edu/?id= ] [ http://www.docbook.org/tdg/en/html/informaltable.html ]
informaltablewill be inserted, otherwise a DocBook [ http://help.unc.edu/?id= ] [ http://www.docbook.org/tdg/en/html/table.html ]tablewill be the result. In either case, the created table will be inserted into the document at the cursor position. Select Adds the basic tags necessary to place an image in the document. If any text is selected when this command is entered, it will form thetextobjectportion of the image (this is the text of thealtattribute value when the item is displayed in HTML format). -
Link To Document. (keycode: F4 ) Pops up a dialog that allows you to enter the ID of a KMT document. If the document ID is found, a
ulinktag whose content is the document's title will be inserted into the document at the current position. If the document ID is unknown, then nothing will be inserted.
-
If validation fails, you will not be permitted to save the editor's contents to your working copy (you will still be able to save it to your local machine, however). If you can't figure out how to fix the problem by looking at the error messages in the error window , save a local copy, you can close the editor without saving to the KMT, and get in touch with your liaison editor (be sure to send your editor a copy of the document that wasn't validating).
About The Editor
- Q: What is the intended use of this tool?
- Q: This is pretty neat, but why doesn't it have <feature>?
- Q: Why do I have to save my changes to the KMT after saving them to my working copy?
- Q: I clicked on the link to start the editor, but the editor doesn't start. How do I fix this?
- Q: What do I do if the editor starts but can't load the content from the KMT?
- Q: Help! It won't let me save my work to the KMT!
- Q: Can I use this application to edit documents other than Full documents?
- Q: How Do I Preview My Work?
The integration of the IPE with KMT and DocBook documents is fairly tight; it's designed, first and foremost, to make it as easy as possible to do touch-up work, i.e. updating existing KMT documents. That said, some of its features (e.g. link checking) can be useful in more full-featured editing. That said, for 'heavy' editing purposes, [ http://help.unc.edu/?id=5909 ] XMLMind XML Editor is probably a better choice.
As mentioned above, this tool is not intended to be the be-all and end-all of your XML editing needs. We want it to be useful, but we also want the KMT and associated applications to be useful, and developing GUI applications is time-consuming. We do want to hear your comments and suggestions for improvements!
Doing things this way allows smoother usage of the KMT's feature (see How Do I Preview My Work? for more information). We're also trying to encourage you to use the document checking facilities the KMT provides to ensure your document is correct before saving your changes to the KMT.
The [ http://help.unc.edu/?id=3669 ] ITS knowledgebase article on Java Web Start can be your starting point for troubleshooting problems running the editor. Things you should try, in order:
-
Make sure the Sun JRE and JWS are installed on your system
-
Make sure your browser properly associates JNLP files (files ending in
.jnlp) with Java. -
Make sure that you haven't refused permissions to code signed by
kmt.unc.edu.
If following these steps and, as a last resort, reinstalling the Java Plugin (see the Java Web Start document referenced above for basic instructions) does not solve the problem, please send a Remedy ticket to ITS Knowledge Management.
Older versions of the Java plugin may be unable to communicate with the KMT. Usually this can be fixed by [ http://help.unc.edu/?id=3599 ] updating your Java plugin to the latest version. If you still encounter the same problem after upgrading the plugin (and shutting down and restarting your browser), send a Remedy ticket to ITS Knowledge Management.
This can happen for a few reasons; one of which is that you left the editing application window open, got called away from your keyboard for a while, and your KMT session expired. Another of which is that your document is invalid (see above). Finally, it could be that a bug in the system or a network glitch is preventing the application from communicating with the KMT. If any of these happen and you don't know how to fix the problem, save your work using the "save local copy", and get in touch with your liaison editor. If it's a matter of your session timing out or there being a temporary network glitch, log back in to the KMT, upload the file with your saved work into a working copy, and then re-open the working copy in the in-place editor.
If the builtin Preview is not working for you (in which case, send a Remedy ticket to ITS Knowledge Management with your OS and browser version details), or you want a more faithful representation, then you can select Ctrl - S in the editor, and open or reload the "Preview Document" screen (a link to this screen is available from the "Edit Content" screen). As you save your updates to the working copy, you can simply refresh the preview page to see the effect your changes have. (Don't forget to return to the "Edit Content" screen and save your document, however!).
Document Overview
Tags: Docbook, editingSubjects: Knowledge Management Tool (KMT)
Genre: Tutorial
Audience: Everyone
This work is licensed under a Creative Commons Attribution 3.0 United States License.
Copyright 2002-2007 The University of North Carolina at Chapel Hill.
This
work is licensed under a
Creative Commons Attribution 3.0 United States License.
