Tutorial: Subsetting the DITA User Interface in XMetaL Author

[Su-Laine Yeo]

If your team doesn’t need to use all of the menu items and toolbar buttons in XMetaL, you can safely hide the ones that writers don’t need. For example, if you are using XMetaL to edit DITA topics but there are DITA element types that you never use, you can remove their corresponding menu items from the Insert menu. Doing this will generally give you a simpler user interface for writers, without needing to specialize DITA or modify the DITA DTDs at all. 

All menu and toolbar settings for a particular document type are stored in a single file with a .TBR extension.  When you open a document, XMetaL looks at the .TBR file for that document type in order to determine which menus, menu items, and toolbar buttons to display.

Purpose: In this tutorial, you will remove the “Programming Elements” items from the Insert menu for all DITA topic types.

Prerequisites:
- XMetaL Author Enterprise 5.0 or higher

Procedure 1: Remove the “Programming Elements” menu items for one DITA topic type
1) Make a backup of your C:\Program Files\XMetaL x.x\Author\DITA\XACs folder.
2) Start XMetaL.
3) Click File > New.
4) Click the DITA Topic tab, select the Concept icon, and then click OK.
5) Right-click anywhere in the toolbar, and choose Customize.



6) In the Toolbar and Menu Customization dialog, click the Menu tab.
7) Expand the tree view by clicking the + button next to the &Insert option.
8) Scroll down until you can see the &Programming Element option, and then click it to select it. The dialog should now look like this:



9) Click the Remove button.
10) Click Close.
11) Click the Insert menu. You should no longer see the “Programming Elements” submenu.
12) Right-click in the document. In the right-click menu, you should no longer see "Programming Elements" within the Insert submenu.

Procedure 2: Remove the “Programming Elements” menu items for all other DITA topic types
Do steps 3 to 11 in Procedure 1 for each of the following document types that are in the File > New dialog:
- Composite
- Concept
- Generic Topic
- Reference
- Task
- Glossary-Multiple
- Glossary-Single

Procedure 3 (optional): Copy .TBR files to the Program Files directory
If you are using XMetaL Author Enterprise 5.0 or 5.1, skip this procedure.
If you are using XMetaL Author Enterprise 5.5 or 6.0 and have changed your XMetaL55.ini or XMetaL 6.0.ini file to make it run in “default” mode, skip this procedure.

If you are using XMetaL Author Enterprise 5.5 or 6.0 and have never changed your XMetaL55.ini or XMetaL 6.0.ini file, then your machine will have two copies of the .TBR file for each document type. For example, there will be two copies of the .TBR file used for Concept topics:

C:\Documents and Settings\<username>\Application Data\SoftQuad\XMetaL\6.0\gen\C\Program Files\XMetaL x.x\Author\DITA\XACs\concept\concept_ditabase.tbr

and

C:\Program Files\XMetaL x.x\Author\DITA\XACs\concept\concept_ditabase.tbr


The changes that you made in Procedure 1 are recorded in the copy of the concept_ditabase.tbr file that is in the Documents and Settings folder.  XMetaL looks at this copy when you open a Concept topic.

The copy of the concept_ditabase.tbr file that is in the Program Files folder is used only in fairly rare cases, such as if you were to configure XMetaL to use a new DITA specialization that is based on the Concept topic type. If you want to be sure that the correct copy of a customized .TBR file is always used, you can copy the .TBR file from the Documents and Settings folder to the Program Files folder.

Procedure 4 (optional): Copy configuration files to another machine

After configuring XMetaL on one machine, you can copy configuration files to the machines used by other team members so that their user interface looks and behaves the same as yours.

For XMetaL Author Enterprise 5.0 and 5.1:
1) Copy the contents of the following folder to the other machine: C:\Program Files\XMetaL x.x\Author\DITA\XACs

For XMetaL 5.5 and 6.0:
1) Copy the contents of the following folder to the other machine: C:\Documents and Settings\<username>\Application Data\SoftQuad\XMetaL\6.0\gen\C\Program Files\XMetaL x.x\Author\DITA\XACs\ .

If you do not see this folder, it means you you have changed your XMetaL55.ini or XMetaL 6.0.ini file to make it run in “default” mode. In this case, copy the C:\Program Files\XMetaL x.x\Author\DITA\XACs folder instead.

Procedure 5: Reconfigure XMetaL whenever you upgrade

Before installing a new version of XMetaL, always uninstall the old version first. After running the installer, you will need to redo all of the above procedures, as .TBR files that have been customized for one version of XMetaL might not work properly with another version.

[Su-Laine Yeo]

A related topic for subsetting XMetaL Author is this one: Info: Customizing document templates for efficient writing. If your writers never use a particular topic type, you can remove its icon from the File > New dialog by deleting its template file.

[patrickq]

Is it also possible to remove elements from the Element List window?

[Derek Read]

XMetaL Author itself has APIs that let you manipulate what is listed in the Element List (adding and removing the items listed), so in theory this could be done. However, in practice we have not officially tested this with the DITA solution that ships with XMetaL Author Enterprise, which is essentially a very complex XMetaL Author customization and doing this is not yet supported (as of 6.0).

We are aware that this is something people may wish to do and so are looking at ways that will make it easy to configure this (ideally all in one place). I don't see that occurring too soon though.

If this was not for DITA then you could incorporate the API ElementList.RemoveItem("elementname") into an event macro called in On_Update_ElementList in your customization.

However, because this is for DITA it needs to play well with the rest of the DITA solution, and there is no proper way to do that at the moment. Ideally (if we had implemented something) it would probably be another prototype method as described in the documentation inside the following file C:\Program Files\XMetaL 6.0\Author\DITA\XACs\ditabase\ditabase_ditabase.off.js though ultimately this feature may be implemented another way.

Also, simply removing the elements from the Element List may not be good enough for some people, as that will not stop people from adding these elements in PlainText view, pasting them in, or opening documents that contain them. Varying degrees from "completely ban them even though they are allowed by the DTD" to "warn me" (perhaps with some kind of additional customizable business rules logic) might also be desired by different clients (and we are thinking about this stuff).

[simonbate]

Once a menu item is deleted as per Procedure 1, is there any way to restore the menu item?

Is there a way to restore the entire .tbr file (without re-installing XMEE)?

[Su-Laine Yeo]

I don't know of a way to restore a single menu item, however you can restore all the default menu items by deleting the relevant .TBR file from your Documents and Settings folder. For example, to restore all default menu items for DITA Concept topics, exit XMetaL Author and then delete or rename the following file:

C:\Documents and Settings\<username>\Application Data\SoftQuad\XMetaL\6.0\gen\C\Program Files\XMetaL x.x\Author\DITA\XACs\concept\concept_ditabase.tbr

The next time you start XMetaL, it will use the following file to generate menus:

C:\Program Files\XMetaL x.x\Author\DITA\XACs\concept\concept_ditabase.tbr

And then when you exit XMetaL, you'll see that it has generated a new copy of the following file:

C:\Documents and Settings\<username>\Application Data\SoftQuad\XMetaL\6.0\gen\C\Program Files\XMetaL x.x\Author\DITA\XACs\concept\concept_ditabase.tbr

I should mention that XMetaL menu items are generated dynamically through some fairly sophisticated code, and although the above method works for me, we haven't thoroughly tested it. Good luck.

Su-Laine

[simonbate]

Thanks, Su-Laine.  I figured the delete trick soon after I posted my query.

Works for me.

[simonbate]

What are the pros and cons about deleting menu commands (per procedure 1), versus creating macros that turn off the visibility for (or even delete) controls? 

I'm looking to hide things from users and realize that even if I delete some commands from the menus, many of the commands that I want to hide still exist as pop-ups ("Insert" on the right-click menu). 

(Also, it would be helpful if "Pop-Ups" was a fourth tab on the Toolbar and Customization dialog.)

[Su-Laine Yeo]

If you can figure out how to hide menu items via a script, this is probably the better approach because you can do it for all document types in one file. Also, for the commands that are visible when no documents are open, the only sure way to consistently hide them is via script.

We'd like to post a tutorial and some sample code for a menu-hiding macro at some point, but I don't know when. Adding a more first-class feature for choosing what to show or hide in different parts of the UI is a good idea too. Thanks for the suggestion.