Evaluation Manual DITAWorks

Transcription

1 Evaluation Manual DITAWorks instinctools GmbH, Sophienstr. 17, D Stuttgart Phone: , contact@instinctools.com, Copyright 2009 * instinctools GmbH

2 Table of contents DITAworks User Interface... 5 DITAworks Infrastructure Features... 6 Project Based Organization... 6 Model Project... 6 Content Project... 7 Create Content Project... 7 Adjusting Content project settings... 8 ID Conventions... 9 File Naming Conventions Storing Policies Mandatory classifications File Name Decorations Preview Functionality Editorial Features... Importing existing DITA content... Creating A New Topic Or Map... Working With DITA Topics... Working With DITA Maps... Visual DITA Map Editor... Map Manager View... Content Validation Link Management And Refactoring Refactoring Functionality Example Working With Tags and Conditional Processing... About Conditional Processing... Tags View... Tagging Example Working With Reusable Content Challanges of DITA Content Reuse Reuse View Publishing... Publishing Configurations... Conditional Profiles... Creating New Conditional Profile... Running publishing Updating The Application Eclipse help support... About Eclipse Help... Eclipse Help specializations... Creating Eclipse Help Content Project... Working with Eclipse Help Plugin Map... Working with Eclipse Help contexts... Active Help... Working with live actions... Working with cheat sheets... Publishing Eclipse Help... Cross-plugin link management... Table of contents

3 Features in developement Table of contents 3

4 Document Purpose This document helps to start using DITAworks application. It doesn't provide complete description of DITAworks but rather guides readers through most important functions. Document Purpose 4

5 DITAworks User Interface DITAworks user interface is based on the Eclipse user interface concept. An application window contains so called perspectives. A perspective (number 1 on the figure below) is an adjustable visual container for a set of views and content editors. Each perspective provides a set of functionality aimed at accomplishing a specific type of task, or it works with specific types of resources. It defines the set and layout of views in the application window. Editors (number 2 on the figure above) appear in the middle pane with tab navigation. Tabs in the editor area indicate the names of resources that are currently open for editing. An asterisk (*) indicates that an editor has unsaved changes. For example in figure below two DITA topics are opened for editing. Any number of editors can be open at once, but only one can be active at a time. The main menu bar and the toolbar (number 3 on the figure below) contains operations that are applicable to the active editor. Views (number 4 on the figure above) support editors and provide additional information, alternative presentation as well as alternative ways to navigate the information. Views also have their own menus. Some views also have their own toolbars. The actions represented by buttons on view toolbars only affect the items within that view. A view might appear by itself, or might be stacked with other views in a tabbed notebook. You can change the layout of a perspective by opening and closing views and by docking them in different positions inside the perspective. DITAworks User Interface 5

6 DITAworks Infrastructure Features This section provides a short overview of main infrastructural concepts of DITAworks and it also explains set of features that are designed to enforce certain infrastructural rules. Project Based Organization All elements, that DITAworks is dealing with, are organized in projects. There are 2 types of projects: Content Project. This project type is a container for content that will be managed in DITAworks. Content project can consist of sub folders that store files of different content type. Content project is a minimal work element in DITAworks. Model Project. In this project, elements of the model are stored. Model is set of descriptive elements that define metadata, rules and parameters for content projects. E.g. inside the model project, all DITA information types as well as transformation templates, content processing rules and s.o are defined. One Model project can be used in several content projects. All projects are displayed in Project Explorer. Set of currently open projects form so called workspace. Only one workspace can be open in DITAworks at a time. But workspaces can be easily switched using File/Switch workspace menu point. New projects can be created using menu action File/New/DITA Content project or by using New action on Main Action bar. Model Project Model project is a special type of project used for definition of model information like DITA elements (specialized DITA types, domains and s.o.), classification, templates, reuse and conditional processing attributes (tags) information. Model projects are referenced by Content projects later on. In this way DITAworks tools working with Content projects will use Modeling meta-information to handle edited content appropriately. To start working with information models, user should create new Model project or use one of the existing Model projects. Modeling project comes with certain predefined structure shown on screenshot below: There are several folders created in Model project: templates folder. Serves as container for topic and map templates. Any topic or map created in this folder will be available in "New Topic Wizard" in any Content project that is referencing current Model. customization folder. Usually contains elements of customized Extended model(like customized xsl files and s.o.) New model elements can be created in root or in any sub-folder of model project. DITAworks User Interface 6

7 Model project also displays a virtual folder representing the DITA Model package. This virtual folder is marked with icon: and displays the name of the DITA modeling package. Under this virtual folder several sub-folders are displayed: dependents This sub-folder shows dependent model packages referenced by current model. By default this is standard DITA_1.1 package. modules Displays all structural and domain modules available in current model project. templates Displays all Topic and Map templates created in current model project. types Displays all document types(infotypes) defined in current model project. To get more information about modeling possibilities of DITAworks see DITAworks Modeling guide. Content Project Content projects are used to store content. To start working with content, user should start with creation of new Content project or use some existing one. DITAworks defines set of project level parameters. Among them, there are several groups of settings that help to promote a homogeneous structure of content inside of the projects. These include: ID conventions Naming conventions Storing policies Mandatory classifications Create Content Project To create a new Content project: 1. On the main tool bar, open "New" drop down menu and select DITA Content project. New Project wizard will open. 2. In the Project name field, type a name for your new project. 3. Click Next. 4. In the next step, select model that will be used as a base for created Content project. Additionally, project template can be selected to create a project based on the template. 5. Click Finish. Note: Depending on selected project template "Next" button can be enabled and some template-dependent steps can be available. The new content project will be created and is listed in the Project Explorer. / Content Project 7

8 Adjusting Content project settings To adjust Content project properties: 1. Locate Project in Project Explorer. 2. Right click on it and from context menu select Properties command. / Adjusting Content project settings 8

9 Dialog for editing project properties will open. ID Conventions ID conventions are rules that are used every time new ID needs to be generated by DITAworks. ID conventions can be adjusted on project level. Two types of IDs are distinguished: Topic IDs. IDs that are assigned to DITA topics(f.e. when creating new topics). Element IDs. IDs that are assigned to XML elements inside of the DITA topics(f.e. when conref is made to element that does not have ID yet). Settings of ID conventions can be adjusted on "DITA/ID Generation" page of project properties. / Adjusting Content project settings 9

10 ID conventions can be defined with template expression that uses a set of variables. Variables are referenced using square brackets"{}". List of variables can be seen by pressing on "Add variable" button. {Title}_{GuidProjectScope}- will be expanded into ID consisting of topic title, followed by underscore sign and than unique numeric Id. File Naming Conventions File naming conventions define rules for file names of new topics that will be created in the project. These rules can also be applied during content import into the project. Settings for Naming conventions can be adjusted on "DITA/Name Conventions" page of project properties. / Adjusting Content project settings 10

11 Here, rules for naming can be defined with use of template expressions and variables. Variable list can be see by pressing "Add variables" button. Naming conventions can be separately defined for DITA topics, DITA Maps and Images/Graphics. For DITA topics additionally to naming convention, default extention can be specified (.xml or.dita) {INFOTYPE}_{Title} - will be expanded to infotype name in capital letters, followed by underscore sign and than by topic title. {FLInfoType}_{Title} - will be expanded to first letter of infotype name in capital letters, followed by underscore sign and than by topic title. Storing Policies On "DITA/Storing policy" page of project properties, there is a possibility to define rules for storing new files in a project. Mandatory classifications On "DITA/Classification" page of project properties, there is a possibility to define a set of mandatory classification groups. If some category groups are defined as mandatory, DITAworks will force user to provide classifications for these groups when creating a new topic. Note: "DITA/Classification" property page is available when optional Classification module is installed in DITAworks. File Name Decorations DITAworks provides possibility to adjust the way how files are shown in project explorer. By default, only file names are displayed in project explorer tree. This can be changed by adjusting settings in Window/Preferences/ DITA/Label decoration: / File Name Decorations 11

12 By selecting "Enable decoration of dita files" checkbox and providing a template, user has possibility to control the information that is shown in project explorer. In our example {INFOTYPE}{Name}- {Title} will mean that infotype and title of topics will be dynamically displayed next to file name. Preview Functionality DITAworks provides very convenient possibility to fast preview different files in project explorer and other tools. In every object list in DITAworks (in Project explorer, search results and s.o.) or in every tool in DITAworks where there is a reference to topic or map (in topic or map editor and s.o.), fast preview of listed or referenced object can be engaged by holding "Ctrl" key and moving the mouse to that object in list or reference. / Preview Functionality 12

13 Another possibility to see preview is by using special "Preview" view: / Preview Functionality 13

14 Editorial Features This section shortly describes main editorial featuresditaworks provides. Challenges: Fragmented editorial tooling Authoring in XML Need of control over granular content Standard DITA Maps cannot store unstructured content Advantages All needed editorial tools are integrated in one infrastructure All tools are model-driven Easy creation of topic and maps by using templates WYSIWYG editors, Drag-and-Drop operations Integrated previews Visual Map Editor that can be used as a MindMap for intermediate storage of unstructured content Map Explorer view Importing existing DITA content Existing DITA content can be easily imported into Content project using Content import wizard. To import DITA content: 1. Right click on Project Explorer and select "Import..." menu item 2. In opened dialog select "DITA/Import DITA content" item and press Next 3. Import Dialog will open. Editorial Features 14

15 In this dialog following import parameters can be adjusted: Import from - is a source directory for import. This directory should contain DITA content. Import to - is a name of target project for import. All imported topics and maps will be placed there Need to apply name conventions - if this check box is selected, naming conventions defined on target project will be applied to imported content. Effectively this will mean that every topic and map will be renamed. Existing links inside of the imported content will be preserved. Topics should be stored in project according to storing policy - if this check box is selected, storing policies defined on target project will be applied. After selecting all parameters click "Next". 4. On next wizard step DITAworks will offer a preview of content that will be imported. User have a possibility to select subsets of imported content. 5. Press Finish DITA content will be imported into selected project. Creating A New Topic Or Map To create a new DITA topic or map, special wizard can be used. It can be started in several ways: By pressing on button "New DITA topic" or "New DITA Map" on main action panel Via main menu File/New../DITA Map (DITA Topic) Via context menu in project explorer New../DITA Map (DITA Topic) This will start New Topic Wizard. Editorial Features / Creating A New Topic Or Map 15

16 On the first step of wizard user has the possibility to: Provide Title on new topic or map Select type for it. Note: Available types in this list are determined by models linked to current content project. Select a template if available. Note: Templates are also coming from model level and amount of templates will be determined by assigned models. Select project where new topic will be placed. Pressing "Next" will open a second page. Editorial Features / Creating A New Topic Or Map 16

17 This wizard step will appear if no templates were selected. In this step, user has the possibility to select a root element for new topic/map and provide some extra settings for generation of XML according to infotype definition. In next step, system will ask for classification information. If project has mandatory classification defined, system will require these classification groups to be specified by user. Otherwise step is optional. Editorial Features / Creating A New Topic Or Map 17

18 Note: This wizard step is optional and will appear only when optional Classification module is installed. This step provides possibility to: Select the place where topic will be created. If storing policies are defined, system will offer the place for storing the topic. If storing policies are mandatory, then user will not have the possibility to change this proposed location. Provide File name for new topic. File name is automatically generated using naming convention rules. User has a possibility to adjust proposed name in this step. After pressing on "Finish" button, new topic/map will be created. Working With DITA Topics DITAworks integrates oxygen XML editor and provides a set of convenient functionality for working with topics. To open a topic editor, double click on one of the topics in project explorer. Editorial Features / Working With DITA Topics 18

19 Editor provides 3 editing modes: Source. XML can be authored directly in XML here Grid.XML is presented in grid form here Author.XML document is presented in WYSIWYG form here Source mode In source mode, editor provides a lot of useful support functions like: Content assist. When typing new XML elements or attributes, editor will propose only valid options. Integrated selectors. Easy selection of valid objects when defining href or conref attributes. Integrated preview for referenced topic. Hold "Ctrl" and move mouse over reference to a topic. Automated source formatting. Press Ctrl + Shift + F. Customized highlighting. On-the-fly validation. Set of refactoring operations. Available via context menu. and s.o. Example of integrated selector functionality: Let's try to define a conref for one of our content elements. Let's say, for step inside of the task. For this: 1. We open existing task in topic editor in Source mode. 2. Find a "step" element and type "conref" there 3. Selector opens where we can browse for appropriate task topic and step element inside of it. Preview is available on the right side of the selector and fitting "step" elements are highlighted by green line on the left side. Editorial Features / Working With DITA Topics 19

20 4. In case selected "step" does not have ID assigned, it will be generated automatically according to defined ID convention and assigned to selected element. This id will be used in conref reference. 5. Valid conref value is set. 6. If you try to change something in this value and save, validation will detect errors in reference and report it to you. Author mode In Author mode, editor provides a convenient way that enables user to focus on entering the content. Editor will hide most of the markup and give the possibility to enter the content in Word processor-like mode. Editorial Features / Working With DITA Topics 20

21 Author mode hides complexity of XML structures and provides a lot of useful features like: Tag display control. Using button on main tool bar the way how topic editor displays XML tags can be adjusted. Tool bar buttons for fast access to certain editing operations like making links, conrefs, table operations and s.o. Available buttons are adjustable on model level. Use different WYSIWYG styles. Styles(CSS)can be selected in drop down menu on main tool bar. Additional styles can be defined on model level. See DITAworks Modeling guide for more details. Tracking changes. Editor can be switched into "tracking changes" mode and in this case it will record any changes done in Author mode. Tracking changes can be activated using "Track changes' button on main tool bar of the editor. Additional views Additionally, a set of useful views are available. These views work in context of topic editor and change their content depending on position in the document. Here are some of them: Outline view: Displays structure of the XML file and provides possibility to navigate over it. It also gives the possibility to add new elements or delete existing ones using context menu actions. Editorial Features / Working With DITA Topics 21

22 Elements view: Provides the list of valid elements that can be inserted in/before/after current caret position according to content model. Properties view: Displays the list of possible attributes for currently selected element. Editorial Features / Working With DITA Maps 22

23 Working With DITA Maps DITAworks provides 2 main tools that help working with DITA maps: Visual DITA Map Editor. This editor is designed to support authors on planning stage of DITA Map creation. It helps user to work with DITA Map as a user would with Mind Map. Focus On Map view. This view helps to browse DITA Maps and navigate through linked content. It is useful when author needs to concentrate on content creation. Visual DITA Map Editor By double-clicking in Project Explorer on one of the DITA maps, visual map editor opens. Visual Map editor works in 2 modes: visual ("DitaMap Editor" tab) and source (XmlEditor tab). In source mode, DITA map can be edited in its native XML representation. Editor provides standard features like Source view for topic editor. In visual mode, DITA map editor represents each of the DITA Map structural element (like topicref)as a separate visual node. Nodes form tree structure. Representation of node can be different depending on element type it is representing and can be customized on Model level(see DITAworks Modeling guide). Each of the nodes can be displayed in collapsed and expended mode. User has also the possibility to collapse and expand levels of the tree structure. Nodes can be rearranged using drag and drop operations. Attributes of the existing nodes can be changed using "Properties" view. Alternatively, some attributes can be edited directly in visual node representation. Example: navtitle for topicref element. Other attributes can be edited in "Properties" view. Editorial Features / Working With DITA Maps 23

24 New nodes can be added using context menu "Add child..","insert before.." or "Insert after.." action or by pressing "Ins" or "Enter" keys. Content can be linked to in several ways: Using selector. Expand the node and press on "..." button. This will open new window where selection of existing topic or creation of new topic will be possible. When creating new topic, content entered in the map will be reused (like Title of the topic will be taken from navtitle of the topicref). By drag and drop. Topics can be dragged to area of visual editor on existing nodes or empty canvas. This will link topic to topicref or create new topicref with linked topic respectively. If topicref node does not define navtitle attribute but is linked to a topic, title will be extracted from this topic and shown on diagram node. Relationship table of DITA map can be managed in several ways: Using lining tool. New relationships between nodes can be defined in visual mode by selecting one of the nodes and clicking on small arrow icon on the right side from the node. By dragging the link sign to other node, new relationships can be defined. Using "Relationship table editor" view. If not open already, this view can be activated using "Show view" button. This view displays entries of relationship table. Note: This functionality is still in beta stage. Any ideas and feedbacks on improving it are welcomed. Visual DITA map editor also provides possibility to define some additional information for elements of the map like comments, graphical icons and s.o. This can be done using palette on the right side of the editor. Note: Set of available graphical icons and markers are configurable on model level. See DITAworks Modeling guide. Map Manager View Map Manager view can be activated in 2 ways: Using context menu "Map Manager". This action is available in context menu on every DITA map in project explorer. By pressing "Map Manager" button in visual map editor. This button is available on top-left corner of visual Map editor. Map Manager view looks like this: It browses the selected map and allows user to navigate through contents of the map. Double clicking on the nodes of the tree will open linked topic in editor area. View also allows basic editorial operations with the map. Editorial Features / Working With DITA Maps 24

25 Content Validation DITAworksvalidates all content inside of content projects. Set of rules that are used during validation can be defined in Model projects(see DITAworks Modeling guide). By default DITAworks runs 3 sets of validations: Document structure validation. This is validation according to infotype structure defined by DTD/Schema DITA rules validation. Set of validations that are specific to DITA. E.g. validity of conrefs, validity of IDs and s.o. Link integrity validation. System will check availability of referenced resources and validity of links. Other rules can be defined on model level. Validation is started automatically each time system detects changes to a file. Validation can also be started manually using context menu point "Validate" on project, folder or file level. All detected errors or warnings are reported to user in a special view called "Problems". User can double click on one of the reported errors or warnings to jump to problematic place in the invalid document. Editorial Features / Content Validation 25

26 Link Management And Refactoring Due to high granularity of content managed in DITA, problem of link consistency becomes very important. This problem is addressed by link management facility of DITAworks. All links are extracted from the source files into special index and consistency of links is constantly controlled. Challenges Hard to keep overview of links between granular content Advantages Automatic link extraction and check Visualization and navigation through links Preserving links during rename and move operations Extracted links can be browsed in project explorer Under each file in project, two types of links can be seen: Direct links. Outgoing links from current file. These can be xrefs, hrefs or related links in topics or topicrefs Inverse links. Incoming links to current file. These are present when other files are referencing this file. By double-clicking on the links, other end of the link is opened in editor area allowing fast navigation over linked content. Extracted link data is used in DITAworks in several other modules. Some of these use cases include: Link validation. Link data is used to report information about broken links. Building dependency graphs. Refactoring operations. DITAworks tries to preserve link integrity even in operations that usually would lead to broken links. Refactoring Functionality Example The example below shows refactoring functionality in practice. We will rename and move an image that is referenced from DITA topics. DITAworks will automatically update all DITA links to the image. 1. Let's find a picture that is used in several topics... Link Management And Refactoring 26

27 As you can see in the picture above, the image "logowithtext.jpg" is referenced from 6 topics. 2. Right click on the picture and select Rename action. 3. Enter a new name and make sure that update references checkbox is selected. Press Ok button Image file was renamed and all references to it got properly changed. You can check it by navigating the dependency links. Note: The same approach can be used when moving resources as well as in some other functional areas, where an operation (move or rename) might lead to broken links. Link Management And Refactoring / Refactoring Functionality Example 27

28 Working With Tags and Conditional Processing Conditional Processing tag management is important tool in DITAworks that enable DITA conditional processing. Conditional Tags that are used in a documentation need to be centrally managed in order to reduce amount of errors related to tag misuse. Challenges in working with tags Tag creation and usage needs to be managed Misuse of tags Proper tag and condition definitions on target document generation DITAworks functionality that simplify work with Conditional Processing Tags Centrally define used tag groups and tag values Visual support of tagging in editors Tag usage validation Search for tag usage and tag refactorings Configure conditional processing during document generation (Publish to different formats) Tips Tags can be defined on model or content project levels. When a tag is defined on a model project level, it will be available in all content projects where the model is used. Data from the tag registry will also be later used in definition of conditional profiles (or ditaval files) for content publishing / documents generation. About Conditional Processing Conditional processing involves filtering or flagging content based on processing-time criteria, such as a target audience, platform, product or any other user-defined criteria. You can use metadata on elements to filter or flag content, and to show revised content. You can use attributes to provide information about what product, audience, or platform an element applies to, or what revision it belongs to. Say you have a need for two versions of your installation instructions, one for Windows and one for Linux. You can create a topic file with both sets of instructions (with each set properly labeled as either Windows or Linux), and then use a Conditional Profiles to specify your processing rules (for example, whether to produce a Windows or Linux version of the document, or whether to produce a single output file with the content flagged appropriately with Windows and Linux icons). You can exclude content based on its metadata. By default, all content is included. You can flag content based on metadata. By default, no content is flagged. You can show the revision information for your content. All revision information is hidden by default. Tags View DITAworks provides central registry for Conditional Processing tags that can be used in one or several projects. This registry is presented to the user in Tags View that is shown in the picture below. The view can be opened through the main menu Window -> Show View -> Tags. In this view, user has possibility to: Use this view to tag content in editors. Define new tag groups and allowed tags values. Manage tags inside of existing tag groups. Search for usages of separate tags or tag groups in projects. Tags View should be used to simplify tagging process. Working With Tags and Conditional Processing 28

29 Standard DITA tag groups (attributes) are already defined in the central tags repository and visible in the Tags View. These are: audience platform product rev All user defined Conditional Processing tag groups will be mapped by the system to "otherprops" DITA attribute. Note: Tags view also displays specialized attributes defined using Attribute Specialization on Model level. See DITAworks Modeling guide for details. Tagging Example The example below shows how to use Tagging functionality of DITAworks 1. Open one of the DITA topics using topic editor and go to the source view. 2. Position the cursor on one of the XML elements you would like to tag and double-click on needed tag in "Tags" view. 3. Alternatively you can drag&drop tag from "Tags" view on XML element. 4. Element will be appropriately tagged. 5. By selecting tag in "Tags", editor will highlight all occurrences of this tag in document. Working With Tags and Conditional Processing / Tagging Example 29

30 6. Now let's try to provide invalid value to attribute platform. We change platform="macos" and save. Working With Tags and Conditional Processing / Tagging Example 30

31 As a result, we immediately get an error reported in editor as well as in "Problems" view about invalid tag value. Working With Tags and Conditional Processing / Tagging Example 31

32 Working With Reusable Content For effective management of reusable elements, DITAworks defines a central repository for them. Reusable elements can be defined on model or project level, thereby allowing different scope of reuse. DITAworks supports 3 types of reusable elements: Variables. These are elements that are defined as changeable parameters and can be used in different places of documentation. Variables have default value, but can be redefined on Publishing step. Text blocks. These are often reused pieces of text that point to other topics. These are convenient wrappers around often used conrefs in your projects. Text templates. These are pieces of XML that you often use and get tired to reproduce again and again. Text templates are just copied in current cursor positions. Challanges of DITA Content Reuse Challenges of working with reusable content Misuse of conref attribute Reuse needs to be stimulated and supported Creation of reusable content and its usage needs to be managed DITAworks features that address reuse challenges Centrally defined reusable content elements Fast search and easy usage of reusable elements Search for places where reusable blocks are used Validation of reusable block references Variable values are defined inside the transformation profile Functions for extracting reusable blocks Reuse View Reuse View provides access to reusable blocks registry. It can be opened through the main menu Window Open View Reuse Working With Reusable Content 32

33 The view provides possibility to add, rename and delete different types of reusable elements. It also provides possibility to search for usages of reusable blocks in DITA topics. Fast lookup possibility helps you to locate needed reuse block faster. Reusable blocks can be used in context of DITAworks editors. While in editor, double click or drag reusable block to editor and it will placed inside of the document. In case of reusable text block (based on conref attribute), it is not always possible to insert it in every context. will try to find valid way to insert conref-based text block. If this is not possible, user will get appropriate error message. Working With Reusable Content / Reuse View 33

34 Publishing For publishing of resulting documents, DITAworks integrates DITA Open Toolkit 1.5 with some enhancements. Challenges Generation configurations need to be defined once and reused each time a document needs to be generated. Standard PDF generation in OT has quite a lot of problems, especially with advanced features (i.e. toc, index) Management of Eclipse Help contexts and cheat sheets Advantages OT 1.5 is integrated into DITAworks and set of problems are fixed Style sheets can be customized directly in DITAworks using friendly UI Generation profiles store all needed parameters for document generation (i.e. variables, conditional processing and s.o.) Extended support for Eclipse Help (contexts and cheat sheets) Publishing Configurations DITAworks provides an easy-to-use publishing configuration management that helps define publishing profiles once and run them several times as needed. You can open Publishing Configuration Manager: via main tool bar. Find button Publish and press on small down arrow next to it. From dropdown select Configure. via context menu on DITA map. Find any DITA map in your project and in context menu for it, select Publish/Configure... Configuration dialog will open. Dialog lists all Publish configurations of current project. For each configuration there is a possibility to define following parameters: Name. Name of publish profile. Can be set manually or generated automatically. Input file. Points to source DITA Map that will be used during transformation. Type. Defines a transformation type that will be executed. Dropdown lists all transformation types defined in your model. Out of the box, all types are supported that are part of OpenToolkit. Other transformation types can be defined on model level(see DITAworks Modeling guide). To. Folder where results will be stored. This can be folder inside workspace or outside somewhere on local disk. Profile. Possibility to select one of the Conditional profiles. New profiles can be defined by pressing on "..." button. Resolve links. This option tells publish engine to validate links before transformation. Besides others, engine will also check for links going outside of the scope of current map. Advanced. This opens additional dialog where additional advanced parameters can be provided: Publishing 34

35 Dita.variables page provides the way to redefine variable from Reuse module. You can redefine any variable and new value will be used only for configured publishing. Dita.out page gives a possibility to provide more parameters to Open Toolkit. Links resolving page adjusts parameters of link resolution. After setting all aspects of transformation, profile can be saved using Save button. Conditional Profiles Conditional profiles simplify customization of Conditional Processing parameters(conditional Profiles contain similar information to ditaval file from DITA Open Toolkit.) Using Conditional Profiles content tagged with Tags view can be filtered out in certain publications. Creating New Conditional Profile To be able to use conditional processing in publishing Conditional Profile has to be created. Follow these steps to create new Conditional Profile: 1. When editing Publishing Configuration Press on "..." button next to "Profile" field. New window will open. Publishing / Conditional Profiles 35

36 2. Press on New profile button. 3. In opened window provide a new name for Conditional Profile and select actions for conditional elements. You can include or exclude any of the tags defined in Tags view. Note: By default only tags actually used in your content will be displayed in the list of available tags. To see all tags defined in Tags View select Show all tags combo box. 4. Click Ok New Conditional Profile will be created. You will be able to select it in Profile field of Publishing Configuration. Running publishing Publishing process can be started in following way: 1. Via main tool bar. Find button Publish and press on small down arrow next to it. From dropdown select need export profile. 2. Via context menu on DITA map. Find any DITA map that has export profile defined in the project and in context menu for it, select Publish/[Publish profile name]. This will start publishing process. You can see its progress in transformation console: Note: Console view is designed to display different consoles and DITA transformation console is one of them. If you do not see publish log in Console view but publish process is still running, try pressing on Display selected console and select DITA transformation console. At the end of publishing, DITAworks will offer to open resulting file. Publishing / Running publishing 36

37 Publishing / Running publishing 37

38 Updating The Application DITAworks provides a convenient update mechanism that allows user to get latest updates for application. Note: In case you have no direct connection to Internet and using Proxy server, before using Update functionality you should setup Internet connection settings in Window->Preferences General->Network Connection 1. Go to the Help/Software Updates/Find and Install 2. Select search for updates for currently installed features and press Finish System will ask you for your login and password. After that, the system will check for available updates. If new updates are available, system will guide you through update procedure. 3. After update installation the application needs to be restarted. Updating The Application 38

39 Eclipse help support This section will explain specific features developed in DITAworks to support Eclipse Help publishing from DITA source. There is a special video screen cast available on topic of Eclipse Help support in DITAworks under this URL: About Eclipse Help Eclipse Platform includes its own help system based on an XML table of contents referencing HTML files. This is a standard way to document Eclipse-based software products. But eclipse help format is not reduced to usages only inside of Eclipse platform. It is available as standalone server solution and can be used for providing ANY help content via Web server. Eclipse help system provides such important functions like navigation through TOCs, search, indexing, bookmarking and s.o. When Eclipse help is used for documentation of Eclipse-based software, it allows much more sophisticated mechanisms for context-dependent help definitions like: search expressions, contexts, so called cheat sheets and s.o. Additionally, due to component-oriented architecture of Eclipse, Eclipse help is structured in form of plugins that can be independently deployed and interlinked. This enables creation of scalable documentation that fits to complex product configurations. Eclipse Help and DITA DITA as single-source architecture opens a promising approach for maintaining all your documentation in single format. Eclipse help as one of the publishing formats can address needs of context dependent application help as well as generic online help. DITA Open Toolkit provides a way to transform DITA maps and topics into Eclipse help plugins, but these possibilities are quite limited. Namely DITA OT will generate a TOC file and set of HTML topics linked to source map, but it does not address following important specifics of Eclipse Help: Definition of contexts (used for context-dependent help) Interlinking topics between several Eclipse help plugins Definition of search phrases Definition of cheat sheets Tuning of plug-in contents (Manifest properties, amount of TOCs, indexes, contexts and s.o.) Some other advanced features of eclipse help These limitations are hindering adoption of Eclipse help as publishing output format for DITA content. They need to be addressed in order to full capability of Eclipse help system and this issue can be seen as a current challenge for DITA-oriented tooling. Eclipse Help and documentation process Another challenge in the area of Eclipse help can be found in organization approach to documentation process. In tasks that require definition of context-sensitive help, authoring team needs to work closely together with software development teams. This is required because software developers need to integrate IDs of help topics and contexts inside of software UI code. Same IDs should be mapped to help content created by authoring team. The documentation process and software development process very often have iterative nature. So the synchronization of IDs, which are defined in software code and in documentation itself, can become a serious quality issue. Documentation management tools have to support documentation team in this process and provide efficient ways to automate this process. It needs to be ensured that all software UI components are assigned with the contextual help IDs and these IDs are linked to help content. Eclipse Help specializations Eclipse Help Model To define missing semantics and data structures that are needed for Eclipse Help features, new Eclipse Help DITA model (specialization)was created. Model in DITAworks is a container for meta information(see DITAworks Eclipse help support 39

40 Modeling guide) that includes various elements like DITA infotypes, transformation styles, templates, editorial tools configurations and s.o. Eclipse Help model includes a set of specialized DITA infotypes: eclipsehelpplugin - specialization of DITA map covering the specifics of Eclipse help plug-in descriptors eclipsecontexts - specialization of DITA map that is used to model context sensitive help contexts Eclipse help Model also defines: Eclipse Help domain containing elements specific for Eclipse Help like liveaction Transformations for Eclipse Help specific infotypes. Set of visualization settings for map editor, preview templates, content validation rules and s.o. Eclipse Help project template that makes it easy for the user to start working with Eclipse Help projects. Transformations are adjusted to resolve cross plug-in links in Eclipse Help properly. See section Cross-plugin link management for more details. Below there is an example of eclipsehelpplugin DITA Map describing target Eclipse help plugin: <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE eclipsehelp PUBLIC "-//XDOC//DTD DITA EclipseHelpPlugin 1.0//EN" ""> <eclipsehelp id="org.eclipse.plugin1"> <manifest-info> <Bundle-Version>1.0</Bundle-Version> <Bundle-Name>Default bundle name</bundle-name> <Bundle-Vendor>Default bundle vendor</bundle-vendor> <Bundle-SymbolicName>org.eclipse.plugin1</Bundle-SymbolicName> </manifest-info> <plugin-properties> <property propvalue="plugin-name" propname="default plugin name"/> <property propvalue="plugin-providername" propname="default plugin provider name"/> </plugin-properties> <tocs> <tocfile format="dita" href="../bookmap/bookmap_evaluation_manual_bookmap.ditamap" primary="true"/> <tocfile format="dita" href="../bookmap/bookmap_getting_started_with_ditaworks.ditamap" primary="false"/> <tocprovider classname="com.java.classname"/> </tocs> <contexts> <contextsfile format="dita" href="../contexts/modeling_contexts.ditamap"/> </contexts> </eclipsehelp> And another example of eclipsecontexs DITA Map that is a container for Single eclipse contexts: <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE contexts PUBLIC "-//XDOC//DTD DITA EclipseContexts 1.0//EN" ""]> <contexts id="id4"> <context id="modeling_general"> <description>topics about modeling functionality</description> <helpkey id="modeling_general_alternative"/> <topic href="../../topics/task/task_model_publishing.dita" navtitle="model publishing"/> <topic href="../../topics/task/task_model_testing.dita" navtitle="model testing"/> </context> <context id="modeling_specialization"> <description>topics about specialization support</description> <helpkey id="modeling_specialization_legacy_key"/> <topic href="../../topics/task/task_specialization.dita" navtitle="infotype specialization"/> </context> </contexts> Creating Eclipse Help Content Project Creating an Eclipse Help content project is basically similar to creating of ordinary Content project except that special project template has to be selected. Eclipse help support / Creating Eclipse Help Content Project 40

41 1. On the main tool bar, open "New" drop down menu and select DITA Content project. New Project wizard will open. 2. In the Project name field, type a name for your new project. 3. Click Next. 4. In the next step, select a project template "Eclipse Help Plugin". 5. Click Finish. New content project with predefined structure of eclipse help maps will be created. You can use pre-created objects as starting point for your deliverables. Working with Eclipse Help Plugin Map Eclipse help plugin map(eclipsehelpplugin)is a specialized type from Eclipse Help Model that is used to describe Eclipse Help plugins. Structure of this infotype is very similar to structure of Eclipse plugin manifest file. Creating new Eclipse Help Plugin Map New Eclipse pluginn Maps can be created using "New Topic Map" wizard and selecting eclipsehelpplugin infotype there. Editing Eclipse Help Plugin Map As any DITA maps in DITAworks Eclipse help Plugin map can be edited in several ways: Using Visual Map editor. When editing Eclipse help Plugin in this mode Visual Map editor displays data of the map in optimized way. Eclipse Help model defines special decorations for map editor. Using Map Manager View. Eclipse Help Plugin Map provides possibility to define following aspects of future Eclipse Help plugin: Properties of Plugin Manifest. Different elements under info element. References to one or more tables of content(tocs).these are modeled using tocfile element. href attribute of tocfile element should point to map or specialization of the map. There could be several TOCs defined for one plugin. One of them should be primary that can be set by type attribute. References to context definitions. Plugin map can reference several context definitions that are described using eclipsecontexts DITA map. See Working with Eclipse Help contextsfor more detail. Eclipse help support / Working with Eclipse Help Plugin Map 41

42 Working with Eclipse Help contexts A focused set of help topics that is related to the current context can be shown to users on demand using contextsensitive help. This form of user assistance is delivered to users when a platform-specific trigger is activated (e.g. F1 key on Windows, Ctrl+F1 on GTK, Help key on Carbon). Context-sensitive help can be associated with UI widgets statically using context IDs. Content-sensitive help is described by associating the context id declared in the UI code with a description and list of links to related topics or commands in the online help. In target Eclipse Help format these associations are made inside an XML file located within the plug-in that contains the topics in question. You can create any number of XML files containing context help associations for each plug-in. The description and links for each context id is made inside <context> elements in the XML file. Each context element can have an optional <description> element which is used to describe the UI object and any number of <topic> elements which link to the on-line documentation, as well as command links to perform any operation for the user, e.g. open a cheat sheet. To enable definition of Eclipse help contexts using DITA a specialized infotype was developed(eclipsecontexts)as a part of Eclipse Help DITA Model. Structure of this infotype is very similar to target structure of Eclipse help context file. There are some differences though coming from the in specialized map not every attribute is possible. One eclipsecontexts DITA map can contain definitions for many contexts. Each context defines description and set of topics that form this help context. Below there is an example of eclipsecontexts DITA map : <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE contexts PUBLIC "-//XDOC//DTD DITA EclipseContexts 1.0//EN" ""]> <contexts id="id4"> <context id="modeling_general"> <description>topics about modeling functionality</description> <helpkey id="modeling_general_alternative"/> <topic href="../../topics/task/task_model_publishing.dita" navtitle="model publishing"/> <topic href="../../topics/task/task_model_testing.dita" navtitle="model testing"/> </context> <context id="modeling_specialization"> <description>topics about specialization support</description> <helpkey id="modeling_specialization_legacy_key"/> <topic href="../../topics/task/task_specialization.dita" navtitle="infotype specialization"/> </context> </contexts> In example below we see that topic names are defined using DITA specific navtitle attribute instead of Eclipse help label attribute. Note: Feature in development: In case navtitle is not defined it will be pulled from referenced Topic title in similar way as for any DITA map. Another difference is the fact that href attributes of topic elements are referencing DITA topics instead of html files. Creating new Eclipse Contexts Map New Eclipse contexts Map can be created using "New Topic Map" wizard and selecting eclipsecontexts infotype from list of infotypes. Editing Eclipse Eclipse Contexts Map As any DITA maps in DITAworks Eclipse help contexts map can be edited in several ways: Using Visual Map editor. When editing eclipsecontexts map in this mode Visual Map editor displays data of the map in optimized way. Eclipse Help model defines special decorations for map editor. Eclipse help support / Working with Eclipse Help contexts 42

43 Using Map Manager View. Active Help Active help is the ability to invoke Eclipse code from on-line documentation. Originally in Eclipse Help System it is implemented by including some JavaScript in your documentation that describes a class that should be run inside the Eclipse platform. For example, instead of writing, "Go to the Window Menu and open the message dialog," your on-line/context help can include a link that will open your application's message dialog for the user. Active help links look like hyperlinks in the on-line help. In DITAworks active help is supported by introduction of new domain elements that describe active help actions using DITA. Example of such element is liveaction element. Working with live actions Live actions are references from help content to certain dynamic actions or commands in Eclipse Application. To be able to reference such action or command it should be defined in Eclipse application first. How this can be done is explained here: ua_help_content_active_action.htm. In DITA content live actions can be defined in following way: 1. Open one of the topics using DITA Topic editor in Author mode 2. Select a text you would like to make as live Action 3. From context menu select Refactoring --> Surround with tags.. or press Alt-Shift-E and select liveaction element from the list. 4. Set attributes for newly created element. Table1. liveaction element paramaters Attribute name Description la-classname the name of the class that implements the action la-plugin the ID of the plug-in that contains the action Eclipse help support / Active Help 43