Adobe,RoboHelp,Technical Communication

Here is a good chance for people in Australia to check out the new features of RoboHelp 8 and TCS 2. If you are in Melbourne during 20th to 22nd May, visit the 12th Australasian Online Documentation and Content Conference 2009 at the Savoy Vibe Hotel.
Tony Self and Matthew Ellison will be presenting the key features of RoboHelp, Captivate and the Technical Communication Suite.

The capabilities they will cover include
1) AIR Help as the new output format
2) FM to RH import for online output
3) Enhanced review workflows in TCS for authoring collaboration
4) FrameMaker live link support in RoboHelp

If you are unable to visit the conference and still have some questions on RoboHelp or TCS 2.0, you can reach out to me or Mahesh Kumar Gupta. I am available at "dhirenj at adobe dot com", while Mahesh can be reached at "mahesh at adobe dot com"

Dhiren Jani
RoboHelp Product Manager

Posted by Dhiren Manubhai Jani at 11:39 AM | Permalink | Comments (0)

Adobe,RoboHelp,RoboHelp Server 8, Technical Communication

By default RoboHelp Server 8 gets installed with MS Access as the database which is suitable for internal use or in a development environment.
But for production environment, users should use Microsoft SQL Server/Oracle/SQL Server Express.

Steps to configure oracle/sql server as database –

1) Launch the Config Manager and select File > Open Context and select the context for which you want to configure the database.

2) Select radio button "Oracle 9i or higher/Microsoft SQL Server/SQL Server Express Edition".

3) Create a system DSN using ODBC administrator. To do so, click on the “ODBC Admin” button. This will launch the “ODBC Data Source Administrator”. Click on the “System DSN” tab and then click on “Add” button and select the driver type depending on the kind of database your are using. Then give the Database server details and the user name and password to connect to the database. Press OK.

4) Now select this newly created DSN from the “Select DSN” drop down.

5) In the username, password fields, specify the username and password used to create the DSN.

6) Click “Save”.

7) You can verify if RoboHelp Server has all the information to connect to the database by clicking “Test Connection”. If connection details are OK, it should show a dialog box saying “Successfully connected to database”.

8) Close Config Manager using File>Exit.

Posted by Tulika Garg at 12:50 PM | Permalink | Comments (0)

Structured FrameMaker,Technical Communication,Adobe Technical Communication Suite,XML Authoring

Authors can use the Hierarchical Books in Adobe FrameMaker 9 as XML Authoring Projects. They can keep structapps, EDD, Template, Read Write rules etc inside the book component hierarchy.

Fig 1. Snapshot of a Book which contains XML files and all other structured application files in a logical Folder.

If the author is working on a book which is composed of XMLs the author can add the files necessary for authoring structured applications for XML documents. Standard book operations can be performed over such a book while keeping the Structured Application files in Excluded state. These files would then not be included during book operations like TOC, Lists and Index generation.

Fig 2. A book which has an excluded Folder that contains all the files necessary to open the XML document in FrameMaker.

Keeping the structured application files in such a manner would ease the accessibility to these files. Locating and editing these files would be more efficient as different projects can maintain the associated EDD’s, templates and RW rules as projects using books in FrameMaker.
Moreover the XML’s lying in a book can be associated with a particular application furthur easing the author in remembering the application to open different XML files with.

To set application to use for an XML file inside a book-
Select File> Right Click-Select Properties.
Select application in the Use Structured Application dialog.
Select continue to associate the XML file with an Application.

Also an author can maintain an image repository which might be used frequently. These can be added as unsupported files in an excluded Folder inside a hierarchical book improving accessibility and efficiency.

Fig 3. A book that contains all the images used in the book in an excluded Folder. The images can even lie on web servers.
Similar repositories can be created for other such commonly used files in an authoring project.

Please let me know your comments and suggestions.

Thanks and Regards,
Nakshatra Bhardwaj
FrameMaker Engineering

Posted by Nakshatra Bhardwaj at 12:58 PM | Permalink | Comments (0)

FrameMaker,
Technical Communication,
FrameMaker Specialization,
Specialization,
DITA Specialization,

What is specialization

Specialization is the process by which new designs are created based on existing designs, allowing new kind of content to be processed using existing processing rules.Specialization allows you to define new kinds of information (new structural types or new domains of information), while reusing as much of existing design and code as possible, and minimizing or eliminating the costs of interchange, migration, and maintenance.

FrameMaker provides special handling for many objects in DITA like Table, Image, Title, Indexterm, Xref etc. so when we specialize any such element which have some special handling, same handling should be available for it. E.g. When we insert a crossref in any DITA document (xref or fm-xref element from element catalog or Special->Cross Reference), DITA-Cross reference dialog shows up. Same should happen if we insert any specialized xref element in any DITA document and name of specialized element should also show in DITA <xref> Element drop down.

Types of specialization

Specialization can be broadly categorised into two types
• Structural Specialization
• Domain Specialization

Structural specialization defines new types of structured information, such as new topic types or new map types. Structural types define structures for modules of information, such as concept or task or reference, which often apply across subject areas. When doing structural specialization we generally create new specialized elements from top (Map or Topic) and then create specialization till the element required so essentially with structured specializtion, we create a whole new hierarchy e.g. if we have to create a new structurally specialized UIControlWindow element for uicontrol element, we should create Specialization of Topic, body, p, uicontrol elements.

Domain specialization creates new markup that can be useful in multiple structural types, such as new kinds of keywords, tables, or lists, or new attributes such as conditional processing attributes.Domains typically define markup for a particular domain or subject area, such as programming, or hardware. Domain elements become available wherever their ancestor elements are allowed once the domains are integrated with the structural specializations in a document type. E.g. if we create domain specialized table element <DTable>, it should be available whereever table element is, in the element hierarchy.

NOTE: We dont support attribute based specialization in FrameMaker.

How to specialize DITA elements in FrameMaker

When we are specializing DITA elements, the most important and tedious process is defining the new specializing elements and deciding where they will fit in the existing DITA hierarchy. Some times we can get carried away and specialize elements more than what's required or can create crude specializations. So most effort should be put in carefully designing the specialized elements required and should avoid creating specialized elements when the existing elements could suffice. Once we have the list of elements we want and defined where they will fit in the existing DITA elements hierarchy, 75% task is done and rest is moreover following the following mechanical steps.

1. Create new set of DTD’s defining the new set of elements derived, from existing element types. The Detailed steps for this are listed at the end.
2. Combine the specialized DTDs into a base dtd.
3. Create a new Read Write Rule file using the existing standard Topic/Map read write rule file and add the element mappings for specialized elements derived from DITA elements, which have some mappings defined. Its like if we have any declaration in read write rule file for the base element and we want the element derived from that to have similar functionality, we need to add the same declaration for child element as well e.g. If we have mapped DITA image element to FrameMaker Graphic element then the specialized image element need to have same declaration in read write rule file to have special image handling. If there is unwrap statement for any element, then elements derived from that should be unwrapped as well.
4. Import the base DTD as EDD in FrameMaker using the read write rule file and DTDs created in step 1-3.
5. Check the class attributes of all the specialized elements in EDD. The correct element hierarchy should be created from the base element to the specialized one. Its the only criteria for Frame to map specialized element to its parent element.
6. Make FrameMaker specific changes in the EDD file as listed below

   - For topic specialization :-

• Copy All the elements starting from "FM-" from standard Topic EDD to the New EDD generated. These are all FrameMaker specific elements which are declared to handle special objects like table, crossref, image etc.
• Change the content model of element properties to "fm-propheading?, fm-propertybody+".
• Change the content model of element choicetable to "chhead, fm-chbody" and simpletable to "sthead, fm-stbody.
• Change the content model of sthead to "fm-stheadrow" and chhead to "fm-chheadrow".
• Add fm-xref element to the content model of xref, syntaxdiagram, synblk, groupseq, groupchoice, groupcomp andfragment elements and all the elements where xref is valid. We need to do the same for specialized xref elements as well i.e. whereever any element of type xref is allowed, fm-xref should also be allowed.
• Add fm-linktext where ever linktext or any specialization of linktext is allowed.
• Hide the elements fm-graphic, alt, index-base, index-see, index-see-also and index-see-also using conditional tag.

- For Map specialization :-

• Change the content model of reltable to (fm-reltablemeta)?,( relheader)?,(fm-reltablebody).
• Change the content model of relheader to (fm-relheaderrow).
• Copy elements fm-relheaderrow and fm-reltablebody from standard Map edd to current EDD.
• Add fm-topicreflabel to content model of topicref.
7. Copy the element formatting of standard DITA elements from the default DITA Topic/map EDD to the new EDD and also define the formatting rules for the new specialized elements.
8. Import EDD into new template file, import paragraph and character formats from standard DITA template into this new template and create new structured application for specialized elements using the template, read write rule and the integrated DTD file created from step 1-7. Add new topic type as doctype in the application definition and also replace the name of ditabase.dtd with the new integrated DTD created in step1. We also need to change the value of ‘writer external dtd‘ in the read write rule file to the new integrated dtd name.
9. Change the new application name in DITA option dialog (DITA-Topic Application, DITA Map Application) and click on save.
10. You should be able to see your specialized Topic/Map in the DITA->New DITA file submenu. Start authoring. Its simple.

DITA elements with special handling in FrameMaker for specialization

For special elements like table, image, indexterm, footnote etc. the EDD contains special information denoting its type. All specialized elements for such special elements should also have corresponding information in EDD then only the special handling can be provided to the specialized elements. Following is the list of elements with special handling and the needful for specialization

1. topicref:- User should include fm-topicreflabel as the valid first element in the general rule of its specialized topicrefs. The functionalities like update reference, open all topicref, conref topic ref, navtitle update etc. are also available for specialized topicrefs.
2. indexterm:- If indexterm import and export processing is ON in DITA options then the nesting of indexterm and Index-see, index-see-also, index-sort-as processing etc. is also available for specialized indexterms.
3. table/simpletable/reltable/choicetable:-DITA table elements doesn’t contain numCols and colWidth properties which need to be set explicitly in ditafm.ini for reltable/simpletable and for elements specialized from them. While specializing reltable, simple table etc., user need to add elements parallel to fm-reltablemeta, fm-chheadrow etc with similar structure in the EDD file (as we have for standard elements) and need to make similar declarations in read write rule file for the new elements. When we insert specialized table/simpletable/reltable elements, the name of specialized elements also appears in insert table dialog.
4. topic/map:- If correct specialized topic/map application is set in DITA options, the specialized topic/map name appears in DITA->New DITA file submenu. Composite FM doc/ Book with FM doc etc functionality is available for the specialized topics as well.
5. image/alt:-We need to make declaration in read write rule file for specialized image element to work as Frame graphic object. We don't support specialization of alt element.
6. xref/link:- When a specialization of xref element is created, in the EDD file, we need to make element fm-xref available whereever the specialized xref is available. When we insert specialized xref/link element in DITA document, DITA-CROSS REFRENCE dialog opens and name of specialized xref/link element is available as DITA <xref/link> element.
7. linktext:- We need to add fm-linktext in the EDD, as a valid choice, at all occurrences of specialized linktext element.
8. prolog/draft-comment:- If the DITA option for conditionalize prolog/comments on file open is selected, then the specializations of prolog and draft-comment elements are conditionalized as well.
9. fn:-We need to declare specialized fn element as footnote in read write rules file. NOTE: For all the above elements with some special handling, empty class attribute is allowed for the base element.

NOTE: For all the above elements with some special handling, empty class attribute is allowed for the base element.

Download PDF for this Topic

How to make changes in DITA DTDs for specialization

DITA dtds are divided into smaller modules, based on the base elements hierarchy (Topic and Map) and their respective domain and structural specializations like Task, Concept, BookMap, UIDomain, Programing Domain etc. There are fixed set of changes which need to be done in DTDs which are defined below.

Making changes in DTDs for structural specialization

For structural specialization, we need to create a new DTD file with specialized elements and then we have to integrate it with the existing DITA DTDs , the way we want our final output to work. If we want to make our specialized elements types work with the existing topic/map hierarchies, we can add our specialization to ditabase.dtd or we can create a separate dtd. We will take an example where user want to define a new specialized object element with only specialized xref and footnote elements as its content model. The Steps to perform are :-

1. Copy any existing MOD file and rename it. e.g. refrence.mod to objectsp.mod.
2. Open the new mod file e.g. objectsp.mod and in section "SPECIALIZATION OF DECLARED ELEMENTS", change infotype declaration to the newly declared structured type, which will be required for integrating the specialized modules with the existing ones.

<!--========================================================-->
<!-- SPECIALIZATION OF DECLARED ELEMENTS -->
<!--======================================================= -->
<!ENTITY % objectsp-info-types "%info-types;" >


ADDITIONAL INFORMATION: In next 3 steps, remove the existing stuff in the respected heads and add the new elements related information. We copy existing DTds mainly for the purpose that we get a formatted structure defined for declaring our new elements.

3. Declare the new entities for the specialized elements required till the top of the hierarchy.
   <!--====================================================== -->
   < !-- ELEMENT NAME ENTITIES -->
   <!--=======================================================-->
   <!ENTITY % myobjecttype "myobjecttype" >
   <!ENTITY % mybody "mybody" >
   <!ENTITY % myp "myp" >
   <!ENTITY % myobject "myobject" >
   <!ENTITY % myxref "myxref" >
   <!ENTITY % myfootnote "myfootnote" >
   <!--======================================================= -->
   
4. Declare the new specialized elements.
   <!--======================================================= -->
   <!-- ELEMENT DECLARATIONS -->
   <!--======================================================= -->
   <!-- LONG NAME: myobjecttype -->
   <!ELEMENT myobject ((%myxref;)*, (%myfootnote;)*)>
   <!ATTLIST myobject
   declare (declare) #IMPLIED
   classid CDATA #IMPLIED
   codebase CDATA #IMPLIED
   data CDATA #IMPLIED
   type CDATA #IMPLIED
   codetype CDATA #IMPLIED
   archive CDATA #IMPLIED
   standby CDATA #IMPLIED
   height NMTOKEN #IMPLIED
   width NMTOKEN #IMPLIED
   usemap CDATA #IMPLIED
   name CDATA #IMPLIED
   tabindex NMTOKEN #IMPLIED
   longdescref CDATA #IMPLIED
   %univ-atts;
   outputclass CDATA #IMPLIED
   longdescre CDATA #IMPLIED >
   --------------------------- and so on for other elements
   
5. In "SPECIALIZATION ATTRIBUTE DECLARATIONS" section, declare the element from which the specialized element is derived from. We have to declared the hierarchy till the base topic/Map type (starting with a "-" for structural specialization) e.g. if the specialized element is derived from any reference element, we have to define the complete hierarchy from specialized element to reference to topic (as reference is again specialized from topic).
   <!--====================================================== -->
   < !-- SPECIALIZATION ATTRIBUTE DECLARATIONS -->
   <!--=======================================================-->
   <!ATTLIST myobjecttype %global-atts; class CDATA "- topic/topic myobjecttype/myobjecttype " >
   <!ATTLIST mybody %global-atts; class CDATA "- topic/body myobjecttype/mybody " >
   <!ATTLIST myp %global-atts; class CDATA "- topic/p myobjecttype/myp " >
   <!ATTLIST myxref %global-atts; class CDATA "- topic/xref myobjecttype/myxref " >
   <!ATTLIST myobject %global-atts; class CDATA "- topic/object myobjecttype/myobject " >
   <!ATTLIST myfootnote %global-atts; class CDATA "- topic/fn myobjecttype/myfootnote " >
   
6. Integrate the new mod file with the existing ones by modifying ditabase.dtd. For the specialization in the example stated above, add entry in the “TOPIC NESTING OVERRIDE" section for declaring the new type with the base types and in "TOPIC ELEMENT INTEGRATION" section for importing the mod file
   <!--========================================================-->
   <!-- TOPIC NESTING OVERRIDE -->
   <!ENTITY % info-types "topic | concept | task | reference | ? myobjecttype | glossentry" >
   <!--========================================================-->
   <!-- TOPIC ELEMENT INTEGRATION -->
   <!--========================================================-->
   <!-- Embed topic to get generic elements -->
   <!ENTITY % topic-type PUBLIC ?"-//OASIS//ELEMENTS DITA Topic//EN" ?"topic.mod" >
   %topic-type;
   <!ENTITY % objectsp-type PUBLIC ?"-//OASIS//ELEMENTS DITA Topic//EN" ?"objectsp.mod" >
   %objectsp-type; HOW TO MAKE CHANGES IN DITA DTDS FOR SPECIALIZATION MAKING CHANGES IN DTDS FOR DOMAIN SPECIALIZATION
   ---------- and the other existing ones

   ADDITIONAL INFORMATION: If we want to restrict multiple topic types in a single topic type we can create a new integration file and not pull in all the topic types together like we did in the current example.

Making changes in DTDs for domain specialization

For domain specialization, we need to create 2 DTD files. In first file we declare the specialized elements and in the second dtd we declare the entities for integration related information as domain specialized elements should be available where ever their base element is. We will take an example where user want to define 3 new domain specialized elements for image, prolog and link respectively. The Steps to perform are :-

1. Copy any existing MOD file and rename it. e.g. utilitiesDomain.mod to domainsp.mod.

   ADDITIONAL INFORMATION: In next 3 steps, remove the existing stuff in the respected heads and add the new elements related information. We copy existing DTDs mainly for the purpose that we get a formatted structure defined for declaring our new elements

2. Open the new mod file e.g. domainsp.mod and in section "ELEMENT NAME ENTITIES", declare the new entities for the specialized elements.
   <!--====================================================== -->
   < !-- ELEMENT NAME ENTITIES -->
   <!--=======================================================-->
   <!ENTITY % Dlink "Dlink" >
   <!ENTITY % Dprolog "Dprolog" >
   <!ENTITY % Dimage "Dimage" >
   <!--=======================================================-->
3. Declare the new specialized elements.
   <!--======================================================= -->
   <!-- ELEMENT DECLARATIONS -->
   <!--======================================================= -->
   <!-- LONG NAME: Dimage -->
   <!ELEMENT Dimage (%alt;) >
   <ATTLIST Dimage href CDATA #REQUIRED
   keyref NMTOKEN #IMPLIED
   alt CDATA #IMPLIED
   longdescref CDATA #IMPLIED
   height NMTOKEN #IMPLIED
   width NMTOKEN #IMPLIED
   align CDATA #IMPLIED
   scale NMTOKEN #IMPLIED
   placement (inline | break | -dita-use-conref-target)
   "inline"
   %univ-atts; outputclass CDATA #IMPLIED >
   --------------------------- and so on for other elements.
4. In "SPECIALIZATION ATTRIBUTE DECLARATIONS" section, declare the element from which the specialized element is derived from. We have to declared the hierarchy till the base topic/Map type (starting with a "+" for domain specialization) e.g. if the specialized element is derived from any other utility domain element, we have to define the complete hierarchy from specialized element to utilities domain to topic (as utilities domain is again specialized from topic).
   <!--====================================================== -->
   < !-- SPECIALIZATION ATTRIBUTE DECLARATIONS -->
   <!--=======================================================-->
   <!ATTLIST Dprolog %global-atts; class CDATA "+ topic/prolog
   domainsp-d/Dprolog " >
   <!ATTLIST Dlink %global-atts; class CDATA "+ topic/link
   domainsp-d/Dlink " >
   <!ATTLIST Dimage %global-atts; class CDATA "+ topic/image
   domainsp-d/Dimage " >
5. Next we need to define the ENT file which allows the elements to be substituted instead of being aggregated i.e. wherever the parent element is allowed, the specialized one should be allowed as well. Create a new ENT file (or copy any existing one).
6. Open the ENT file and declare the entities for integration of new elements with the existing one (using domain extensions)
   <!--====================================================== -->
   < !-- ELEMENT EXTENSION ENTITY DECLARATIONS -->
   <!--=======================================================-->
   <!ENTITY % domainsp-d-image "Dimage" >
   <!ENTITY % domainsp-d-link "Dlink" >
   <!ENTITY % domainsp-d-prolog "Dprolog" >
7. In same ENT file, decare the domain attribute entity to define the ancestry till the root from which the elements are derived. If you are specializing any element from some domain extension, then you need to declare till the top.
   <!--====================================================== -->
   < !-- DOMAIN ENTITY DECLARATION -->
   <!--=======================================================-->
   <!ENTITY domainsp-d-att "(topic ank-d)">
8. Integrate the new mod file with the existing ones by modifying ditabase.dtd. For domain specialization we need to integrate both element definition dtd and the ENT file we created so we need to modify at 4 different places
• First we need to do the vocabulary declaration and define the new domain.
  <!--========================================================-->
  <!-- DOMAIN ENTITY DECLARATIONS -->
  <!--========================================================-->
  <!ENTITY % domainsp-d-dec PUBLIC "-//domainsp//ENTITIES DITA
  domainsp Domain//EN" "domainsp.ent" >
  %domainsp-d-dec;
  -------- and the other existing ones.
• Do the vocabulary substitution and define the elements from the which the domain specialized elements are extending from.
  <!--========================================================-->
  <!-- DOMAIN DOMAIN EXTENSIONS-->
  <!--========================================================-->
  <!ENTITY % image "image | %domainsp-d-image;" >
  <!ENTITY % prolog "prolog | %domainsp-d-prolog;" >
  <!ENTITY % link "link | %domainsp-d-link;" >
  -------- and the other existing ones
• Do the vocabulary attribute declaration.
  <!--========================================================-->
  <!-- DOMAINS ATTRIBUTE OVERRIDE-->
  <!--========================================================-->
  <!ENTITY included-domains "&ui-d-att; &hi-d-att; &pr-d-att;
  &sw-d-att; &ut-d-att; &indexing-d-att; &domainsp-d-att;" >
• Finally put the vocabulary definition and pull in the mod file for domain element integration. It will pull in all the specialized elements declared in the mod file.
  <!--========================================================-->
  <!-- DOMAIN ELEMENT INTEGRATION -->
  <!--========================================================-->
  <!ENTITY % ank-d-def PUBLIC ?"-//domainsp//ELEMENTS DITA User
  Interface Domain//EN" "domainsp.mod" >
  %domainsp-d-def;
  -------- and the other existing ones

Thanks and Regards,
Ankur Singla

FrameMaker Engineering

Posted by Ankur Singla at 12:14 PM | Permalink | Comments (0)