Readable Editor

--Stifu 16:00, 10 March 2010 (UTC)

The Readable Editor

The Readable Editor is a WYSIWYG-Editor for the readable entities in The Dark Mod and it is a feature of Dark Radiant since version 1.2.0 requiring at least version 1.01 of The Dark Mod. Up until now, the workflow for creating readables was tiresome, especially because you had to keep Dark Mod running in the background in order to be able to check if linebreaks and pagebreaks look alright et cetera. But those days are over, as we decided to provide an easy-to-use graphical user interface for creating such texts.

The new workflow

Setting up a readable is fairly easy. Just add a readable entity to your map and start the Readable Editor via the Entity-menu. Once you hit either one of the Save-buttons, the XData and Inventory Name are stored on your selected entity and the newly written text is exported to an .xd file. If you open the Readable Editor on that entity again or any other entity which was already setup with an XData definition, the corresponding definition is of course imported automatically.

Fine, but where is my new XData Definition stored?

The title-bar of the Readable Editor holds the answer to this question. New XData definitions will be added to an .xd file that is named just like your current map. If you import an existing definition (or again, if you start the Readable Editor on a readable entity already setup with an XData definition) any alterations will be stored in the file the definition originated from. This approach prevents the creation of duplicated XData definitions. Important: As soon as you change the XData Name in the editor, a new definition will be created in the file, whose name is again derived from the name of your map.

You can specify the storage folder for XData in the Preferences dialog of Dark Radiant under "Settings/Readable Editor". The pulldown menu offers options to store the files in the "xdata" subfolder of your Mod or Mod Base directory, as well as in a custom folder which can be specified below. Please note that while you can specify any folder you want for exporting, Dark Radiant and its Readable Editor can only import XData definitions that are contained in .xd files located somewhere in the "xdata" subfolder of the Base-, Mod- or Mod_Base-directory. Definitions in "base/xdata/myStuff/SomeXData.xd" for example can be found, but not if they are stored in "base/myStuff/SomeXData.xd".

Is the Preview broken? My Title overlaps with my Body!

No, it's not, the preview is very precise. The GUIs for readables have intentionally been laid out like this to allow the writing of continuous texts without titles. You just have to add some line-breaks to your body until it looks right. And since we are talking about presumably faulty previews here, please also note that some titles of GUIs do not support multiple lines, resulting in some parts of your title not being rendered.

Features, Tips and Tricks

The editing process itself is pretty straight forward. At this point I would just like to point out a few not so apparent features.

• Appending and prepending pages: If you're currently editing the first or the last page of your readable and you click on first/previous page respectively last/next page, a small convenient small popup will show up, allowing you to prepend or append a page.
• Converting the Page Layout: No content is discarded when you change the Page Layout of your readable. If you should once feel like the letter you just wrote would be much more suitable as a diary entry, feel free to just convert!
• Choosing Guis: Just like with XData definitions, you can use one gui per page. You can enter a gui by hand or choose one using the Gui-Browser, which directly previews the selected gui. The browser holds two tabs, one for OneSided- and one for Two-Sided guis. Switching the tab will also change the page layout of your readable and update the preview accordingly.
• Inserting and deleting pages: When you're writing a Two-sided readable, clicking on either one of these buttons will result in a popup, asking you whether the respective operation should be applied to the left or right side or the whole page.
• Browsing XData definitions: Well, there's not much to say about this one. Selected definitions are previewed and if you choose to import a definition, which has been defined in multiple files, another dialog will show up, allowing you to select the file to import. While the Readable Editor supports this duplicated definitions, The Dark Mod does not, so you should definitely go ahead and fix this by hand. You'd have to open the corresponding files by hand and delete the definition.
• The Tools-menu: When clicking the Tools-button a small popup menu offers you to display an import summary of the last XData import or the gui import, as well as a report of duplicated definitions found in the Virtual File System (All .xd files found in the .pk4 files or in actual folders).
• Reloading Readable Guis: All Readable Guis can be reloaded by clicking on "File/Reload Readable Guis" in the Main-menu. A similar option for XData definition is not necessary, because those are loaded completely afresh every time the Readable Editor is started.
• Automatic Page Layout Determination: When you start the Readable Editor on a newly create readable entity, its page layout will be determined automatically. However, the decision poses a rather greedy approach, as it's simply checked whether the entity name contains the string "book". So you might have to adjust the layout manually afterwards.

Known Issues

The Readable Editor is still Work-In-Progress and there will likely be many changes in the future because of that. But it is pretty much in a very well usable state, so we decided to release it to the public already. Here are some of the issues the editor still has:

• The Readable Editor seems to crash in certain circumstances when compatibility-mode is enabled on DarkRadiant.exe. Make sure to disable it if you run into any problems!
• Some two-sided guis are not yet fully supported.
• Some XData definitions can't be imported, specifically those that feature certain import-statements.

Planned Features / Ideas for the Future

• Notify the user when a character was typed that is not available in the font. Possibly even prevent adding it to the textfield.
• If the end of a page is reached in the preview, the editor should automatically jump to the next textView field and somehow notify the user about the page-break.
• Features for the Tools-menu:
  • Resolve conflicts on duplicated definitions.
  • Check XData Syntax of a specified file.
• A Readable Editor Dialog specifically for Translators with two previews, one of them for the original.

If you have any other good ideas, feel free to make a suggestion in the TDM Editors Guild.

Advise for pure Translators

Here are some steps that will make your life easier:

1. Creating a .map file and setting up Dark Radiant:
   1. In Dark Radiant right-click on one of the orthogonal views and choose "Create Entity...".
   2. Browse to "darkmod/readables" and choose a readable entity to add. It basically doesn't matter which one you pick, but it's always useful to have one that is actually visible.
   3. Move the entity directly in front of the camera by draging it on the orthogonal views. You can select an entity be shift+clicking it, deselect by pressing "Escape".
   4. Save the map under a convenient filename like "MyAwesomeReadableTranslatingMap.map".
   5. Press "P" to bring up the preferences dialog of Dark Radiant, go to "Settings/Map Files" and check "Open last map on startup". Now every time you start your Dark Radiant, your map is loaded and you can directly jump into translating.
2. Making the original Readables available to Dark Radiant and starting the translation process:
   1. Open the .pk4 file of the FM using winrar or similar and extract the contained "xdata" folder into your "darkmod"-directory. It should say "darkmod/xdata" after that! The alterations you make to the texts will be stored directly in those files, if you don't change the XData Name (which you shouldn't in most cases!).
   2. In Dark Radiant select the readable entity and click "Entity/Readable Editor" in the Main-menu.
   3. Use the XData-browser accessed by the small button in the "XData Name"-row to import the XData definitions of the FM.
   4. Start translating... It might be useful to cut and paste the original text-part you're going to edit into any random text editor beforehand.
   5. When you're done, you can click on save and directly open the next definition.

To verify your work, you can just start The Dark Mod in the end and load the corresponding FM. Because Doom 3 prefers files found in actual folders over files found in .pk4 files, your translation will be visible ingame, without destroying/altering the original FM-package.

Some mappers don't use virtual folders in their XData names, e.g. "readables/MyFM/MyReadable". So, to make the browsing of the XData files easier and quicker, you can open the .xd file(s) of the FM in any texteditor and prepend for example "translation/" before any XData name. All readables you have to translate will then be listed in the virtual "translation" folder in the XData browser of the Readable Editor. But if you want to see those translations ingame afterwards, you'll also have to delete that prefix in all those XData names later again or delete it within the Readable Editor. Please note however, that those definitions will be stored under a different filename then, as explained above. This is no problem though, I just wanted to point it out.