Hazard Statement with Framemaker DITA

Explorer ,
Jul 03, 2018

Copy link to clipboard

Copied

I am looking at using the Hazard Statement elements as part of the DITA framework. I like the idea of assigning the applicable attribute type (danger, caution, warning) and having the banner change automatically. For example, when you chose type: danger, it pulls up a red banner with a warning symbol.

Here is my question, where and how to I change how this banner looks? I like the idea of having the banner populate by simply assigning the type attribute, but I would like to change the color, symbol and placement of text. I can't for the life of my figure out where Framemaker keeps or pulls this graphic from.

I know I could use the hazardsymbol element and insert my own symbol, but this takes away from the functionality of having DITA "lock down" which symbol goes with which type of hazard statement.

Please see attached example.

Hazard Statement.jpg

TOPICS
Structured

Views

964

Likes

Translate

Translate

Report

Report
Reply
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more

1 Correct Answer

Explorer , Jul 17, 2018
vinayakrishnabhat Explorer , Jul 17, 2018
Depends on your requirement. If you are going to use all of these XML types, then it is better to configure all template files. If you are just going to use concept and task (where the warnings are normally used), then you can configure only these files. Proceed as per your requirement.Thanks,Vinay

Likes

Translate

Translate
Jump to answer Jump to answer
Contributor ,
Jul 14, 2018

Copy link to clipboard

Copied

Take a look at the reference pages.

Likes

Translate

Translate

Report

Report
Reply
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
Explorer ,
Jul 16, 2018

Copy link to clipboard

Copied

OMG thank you! I can't believe I could not find any documentation about Reference Pages. This should be what I need.

For some reason when I make changes to the Reference Page in document the changes don't stay after I save. I suspect this page resides in a linked template file somewhere.

Likes

Translate

Translate

Report

Report
Reply
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
Explorer ,
Jul 17, 2018

Copy link to clipboard

Copied

Hi Matt,

Yes, you have to change the reference page in the templates located in the Framemaker structure folder of C drive. For example, for FM 2017 version, the templates are located at:

C:\Program Files (x86)\Adobe\Adobe FrameMaker 2017\Structure\xml\DITA_1.2\app\technicalContent\template

The path may vary based on the versions. Before making any changes to these template files, make sure you take a backup of the original files.

Likes

Translate

Translate

Report

Report
Reply
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
Explorer ,
Jul 17, 2018

Copy link to clipboard

Copied

Wow, that is nested - but found it! We currently do have a separate set of templates in a Mercurial versioning system.

One last question and I think I can call this thread "answered". Do I have to update the Reference page for each .FM file?

Here would be the list:

  • concept.template.fm
  • ditabase.template.fm
  • generalTask.template.fm
  • glossentry.template.fm
  • glossgroup.template.fm
  • map.template.fm
  • reference.template.fm
  • task.template.fm
  • topic.template.fm

It's not the end of the world - could always copy and paste, but might as well as if Reference Pages can be shared/linked.

Likes

Translate

Translate

Report

Report
Reply
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
Explorer ,
Jul 17, 2018

Copy link to clipboard

Copied

Depends on your requirement. If you are going to use all of these XML types, then it is better to configure all template files. If you are just going to use concept and task (where the warnings are normally used), then you can configure only these files. Proceed as per your requirement.

Thanks,

Vinay

Likes

Translate

Translate

Report

Report
Reply
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
Advisor ,
Jul 18, 2018

Copy link to clipboard

Copied

This is one of the biggest problems with the default implementation of DITA in FrameMaker .. making the DITA structure app model parallel with the modular nature of the DITA DTDs. While logically, this makes perfect sense, it's a total train wreck from a maintenance perspective, and in reality provides virtually zero benefit. In most cases (or, all cases), the formatting and reference objects you want in your concept topics are the same as in your task and reference topics (as well as all other topic-based topic types). Forcing the user to update in parallel, all of these templates and underlying EDDs to make simple formatting changes is just cruel (and error prone). And .. when you build a book, these all get merged into the same file anyway, so any format collisions need to be resolved/normalized.

I promote using a single structure app that supports all (well, most) topic types. (One app for Map, and one for Topic.) This is possible by using the ditabase DTD instead of the topic-based DTDs. This is all perfectly valid and legal from a DITA perspective, and lets you manage one structure app rather than many.

This is the model that DITA-FMx uses (my plugin that replaces the default DITA support in FM). While you can get this using DITA-FMx, you can also do it in default FM. Grab the DITA-FMx trial and steal (clone and rename) the Topic structure app. You'll need to make slight modifications for it to work properly in default FM-DITA, but it should work fine, and will simplify your life considerably.

Cheers,

Scott Prentice

Leximation, Inc.

www.leximation.com

Likes

Translate

Translate

Report

Report
Reply
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
Explorer ,
Jul 18, 2018

Copy link to clipboard

Copied

Scott, thanks for the reply and the suggested work-arounds. I am fairly new to FrameMaker and even newer to DITA, but reading between the lines it appears that the DITA integration with FrameMaker is a bit "unfinished". And I fully agree that any reference objects should be available to all topics and should look the same. I would not want a Danger message to look on way in a Concept and another way in a Task.

Again some of this is high-level for me, but I understand that ditabase is depreciated, but it could still be used for a container for re-use information. Is this then where you suggest I keep/store my reference objects?

I think I've opened a can of worms, but we are looking at leveraging DITA and FrameMaker (which is our adopted model for single-sourcing) so we better make the most of it.

Likes

Translate

Translate

Report

Report
Reply
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
Advisor ,
Jul 18, 2018

Copy link to clipboard

Copied

To be fair .. I wouldn't say that the DITA implementation in FM is unfinished .. there are just some areas that could be improved upon.

The ditabase DTD is included with DITA 1.3. While it's not a recommended method for authoring, it is available for use where needed. I'm not seeing anything in the spec that says that this is deprecated.

However, to answer your question .. no .. you can't add your reference objects to the ditabase template and have them available in all topics. That would be nice, but the modularity of the structure apps doesn't go that far. Basically, the way the default FM-DITA is set up is to have one app for each topic type. If you look in the structure application definitions file, you'll see all of the DITA apps. Each app has a template (the files listed earlier in the thread), plus read/write rules, an app definition, and other related files. The EDD (the document that defines the rules for applying formatting/styles to elements and element structures) is embedded (imported) within the template. When making modifications to a structure app, you update the template for basic formatting changes, but you'll need to edit the EDD when you need to change the way formatting is applied to elements. The EDDs are set up as nested documents, where the common/reused bits are imported as text insets. This nesting goes up to 5 levels (I believe) deep. This is where things start to get really hairy when you want to make changes to the formatting. In theory, making a change to an underlying EDD inset, will get applied to all of the top-level EDDs in the other apps, but this isn't automatic .. you have to manually open the right files and update the insets, then you have to import the updated top-level EDDs into the appropriate templates.

If you want to avoid this maintenance mess, you might consider trying DITA-FMx, or at least adopting the structure app model used by DITA-FMx.

Contact me off list for more details.

Thanks,

...scott

Likes

Translate

Translate

Report

Report
Reply
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
Explorer ,
Jul 18, 2018

Copy link to clipboard

Copied

Hello Scott,

I completely agree with you on this. The development team has to streamline a few of the things to make a writer's life easier. But the flipside is since the help guides available for FM DITA are so badly managed, if they do any new changes to amend these flaws, the user again has to suffer finding help topics for these new changes. When I started to migrate to DITA from unstructured, I had to struggle a lot whenever I got struck.

Likes

Translate

Translate

Report

Report
Reply
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
Explorer ,
Jul 20, 2018

Copy link to clipboard

Copied

I am getting there, but any images I have added to the Reference Page in the DITA Template will show up as a gray box when I create a new topic (based on the template).


This message appears: "Cannot display some imported graphics. The images will appear as a gray box."

The thing is, my Object Properties clearly states a Referenced Path for this graphic. So I don't know why it should not render the graphic.

Likes

Translate

Translate

Report

Report
Reply
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
Advisor ,
Jul 20, 2018

Copy link to clipboard

Copied

Check the reference page in the generated FM file. I'll bet it's not there. You're adding it to one of the many templates, but I'll bet that you need to add it to the template that's used when generating a book. That's likely a different template. I don't know which one .. maybe ditabase? This is why I can't work on generating output from default FM-DITA .. the apps are too crazy. I'm sure someone knows though.

Likes

Translate

Translate

Report

Report
Reply
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
PMYM LATEST
Explorer ,
Nov 13, 2018

Copy link to clipboard

Copied

Hi

I have been searching how to use these hazard frames which can be found from reference pages. Could you be more specific, how those can be taken in use from the reference pages?

Please see my question in detail How to use hazard.notice frames from reference pages for DITA?

Likes

Translate

Translate

Report

Report
Reply
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
Explorer ,
Jul 20, 2018

Copy link to clipboard

Copied

I think I'm ready to throw in the towel with trying to create customized Hazard Statement objects.

While I know where to create/edit Reference Page items, when I try to use a them (in this case a the graphic), I get the message "Cannot display some imported graphics. The images will appear as a gray box."

This only shows when I try to create a topic based on the Template File. I tried both SVG and JPG.

Very frustrating!

Likes

Translate

Translate

Report

Report
Reply
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
Advisor ,
Jul 20, 2018

Copy link to clipboard

Copied

Hi Matti...

Not trying to push my tool (DITA-FMx), but did want to mention that with the last update I added some very cool support for hazardstatement authoring and publishing. I worked with some customers to make sure it was actually useful and usable. It's not trivial to switch to DITA-FMx, but it'll give you nice hazardstatement support plus many other nice features. Here's the documentation on the new feature ..

     http://docs.leximation.com/dita-fmx/2.0/?ditafmx_hazardstatements.html

Cheers,

...scott

Likes

Translate

Translate

Report

Report
Reply
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
Explorer ,
Jul 20, 2018

Copy link to clipboard

Copied

Hi Scott,

Appreciate it! I'd love to try out DITA-FMx, but I was hoping I could get it to work within just FrameMaker, even if only in one topic. I could then demonstrate to stakeholders that there are efficiencies in using both this element and maybe your plugin. I'll read up on your documentation! Cheers.

Likes

Translate

Translate

Report

Report
Reply
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
Adobe Community Professional ,
Jul 20, 2018

Copy link to clipboard

Copied

I can't recommend Scott's method and help on these things more highly, including DITA-FMx.

In the long run you will save an amazing amount of money and headache by following his lead.

He did an amazing job with my client a few years ago, (huge DITA conversion and implementation, including integration with Adobe Experience Manager) and is one of only a very few people I would trust for Fm DITA questions.

-Matt

Likes

Translate

Translate

Report

Report
Reply
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
Explorer ,
Jul 27, 2018

Copy link to clipboard

Copied

Hi Scott,

I have had some time to look over your documentation. Can you quickly explain what your goal was for implementing a plugin for the Hazard Statement element? It would appear that out-of-the-box, FrameMaker DITA does not allow for a lot of customization of this element (which I am learning). And I imagine your plugin allows for some standardization (and hopefully) reuse of the way the Hazard message and associated symbols display. Is this a fair interpretation?

The learning curve is big with DITA...from the .exe redirection files, to the .ini files, etc. I'm just a technical writer....lol.

Likes

Translate

Translate

Report

Report
Reply
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
Advisor ,
Jul 27, 2018

Copy link to clipboard

Copied

Hi Matti...

Note that the plugin isn't just for hazard statements .. it's a complete replacement for the DITA authoring and publishing processes in FrameMaker (and works with FM8 and later). The hazard statement support is just one of the many features. You can read the feature comparison between DITA-FMx and default FM-DITA, here..

     http://leximation.com/dita-fmx/featurecomparison.php

(This feature comparison hasn't been updated recently, so it's a bit out of date, but you'll get the idea.)

The reason I added the hazard statement support into DITA-FMx was because it was requested by customers, since they were unable to use this elements in any useful way. Most of the features in FMx are added through customer requests.

I hope that helps,

...scott

Likes

Translate

Translate

Report

Report
Reply
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more