Structured Authoring

Tip

Posted on January 14th, 2011

Written by douglaspaulwade

Related Posts
Single-Sourcing Solutions – Monster Garage

Inspired by the popular “Monster Garage” television show on the Discovery Channel, today Single-Sourcing Solutions is launching a new webinar series: “Arbortext Monster Garage.” On the TV show, a team of people with mechanical, fabricating, or modifying expertise gathers together to modify a vehicle into a “monster machine.” In our new webinar series, we’re gathering people from the Arbortext community who have modified, streamlined, co-opted, and wrenched their applications to achieve outstanding, interactive, and impressive content and highly effective content creation-publication workflows.

Single-Sourcing Solutions, we always talk about the ease of use and the out-of-the box advantages to Arbortext suite of products. We don’t always talk about the sizable API that opens the entire application to developers. Yet, for many of us, this was one of the primary advantages that drew us to the Arbortext platform. This last year, we discovered that this ability to tweak every aspect of the product and the content that comes out as a result is no longer so obvious to people who are new to the eco-system.

With any dynamic publishing system, you get the benefits of reuse and topic-based authoring. The Arbortext API is one of the real differentiators. It’s one of the true advantages you get by choosing Arbortext: Nearly every corner of the application is open to developers at no additional fee. An Arbortext customer’s ROI improves as they grow because the platform is open to them and grows with you.

Thus, the Arbortext Monster Garage is born!

This new series is designed to teach Arbortext users how to leverage their investment in the Arbortext product line so as to continually grow their ROI. The series will showcase users from the communitydemonstrating techniques, tips and tricks that they have used in the past, discoveries they have made, and showcasing new features.

The series will run twice a month, on the second and fourth Fridays. Each session is scheduled to run in 30 minutes including set up and questions. The calendar has been published in advance, so that you can see what’s coming and sign up for the sessions you’re most interested in. Because the sessions are pre-scheduled, we figure it will be easy to attend because you can block out that 30 minutes on your calendar well in advance.

The series includes sessions for beginners as well as for expert users. It is divided into several tracks that are titled with the same sense of humor that inspired the series, such as “Content Paint Job”, “Cafe con UI”, “Living the XUI”, “Experimenter’s Lab”, “Composition Drag Race”. All sessions are intended to address those areas where the rubber meets the road. The series will draw “shop coach” presenters from the community, including staff from PTC, Single-Sourcing Solutions, customers, and other PTC partners.
Structured Authoring

Posted on August 17th, 2010

Written by douglaspaulwade

Related Posts
Properly Removing Attributes

Often elements will have attributes, which are extra bits of information. Attributes appear inside the opening tag and their value is always inside quotation marks. They look something like this:
<tagname attribute="value">content</tagname>

Often, writers will remove the value, but not the attribute. The proper way is to delete the unnecessary attribute.

Improper Method of Deleting Attributes

When an attribute is not required, it is important to delete the attribute and not null it out (as just remove the value).
For example below, the label attribute has been nulled out.

In this example, the label attribute has been deleted.

Proper Method of Deleting an Attribute

To delete an attribute, place the cursor inside the start tag of the element, open the Modify Attributes dialog box (CTRL-D), and click inside the attribute text box for the attribute to be deleted. Then click Delete and finally click OK to close the Modify Attributes dialog box.

Tip: Attributes that have been modified are displayed in blue text in the Modify Attributes dialog box.
Arbortext Editor, Tip

Posted on June 25th, 2010

Written by JeffStein

Related Posts
Arbortext Editor Tip – Easing the Burden of Spell Check

Checking a document for spelling errors is not one of my favorite tasks. I usually receive a lot of false hits, thanks to the nature of the technical manuals in my current job. For example, some manuals include a long series of part numbers that would never appear in the official dictionary used by the spell checker. Clicking the Ignore All button helps, but it can still feel like wading through a swamp.

Recently I have changed my overall approach. Instead of waiting until a document is nearly finished, I look for errors throughout the process of working on the document. This approach requires that Arbortext Editor’s preferences be set to check spelling as you type.

As you work on a document, watch out for words that have red squiggly lines beneath them. Arbortext uses these lines to highlight possible errors.

When you right-click a word that has been highlighted, a context menu appears with spelling suggestions (if available) and various spell check options, such as Ignore All and Add to Dictionary.
Arbortext Editor, Tip

Posted on April 25th, 2010

Written by JeffStein

Related Posts
Arbortext Editor Tip – Completeness Errors Window

Arbortext Editor has a nice feature that enables you to check a document for various types of errors. To use this feature, go to the Tools menu and click Check Completeness.

If any problems are found, Arbortext displays a window that lists the errors. I usually find that my document contains a bunch of broken cross references.

Notice the first sentence in the upper part of the window: “Double click the left mouse button on any object in error to position the cursor at the point of error, or to cycle through occurrences of the error.”

This statement is not particularly helpful with respect to broken cross references. What you need to do is double-click the underlined phrase “show ids”. This action causes the IDs and ID References dialog box to appear. From there, look for any rows that have the word “MISSING” in the Element column.
Arbortext Editor, Tip

Posted on March 26th, 2010

Written by JeffStein

Related Posts
Arbortext Editor Tip – Fun with Macros

As I was glancing through the Arbortext Editor menus not long ago, I came across the macro feature. Where I work, we are always looking for ways to do things more efficiently, so I decided to check out this tool.

To record a macro, you go to the Tools menu, point to Macros, and click Record New Macro. The dialog box that appears allows you to specify a name, the file where the macro will be stored (more on that in a second), and a description.

For the macro storage location, you need to determine the scope. The default choice enables you to use the macro with any file. The other two choices enable you to use the macro only with the current document, or with all documents of the same type. I haven’t yet felt the need to change the default choice.

Specify the information, click OK, and then perform the actual steps. When you are done, click the Stop Recording button.

To run a macro, place your cursor in the appropriate place and use the Alt+F8 keyboard shortcut to display the list of recorded macros. Select the desired macro and click Run. The macro does its thing.
Arbortext Editor, Tip

Posted on February 21st, 2010

Written by JeffStein

Related Posts
Arbortext Editor Tip – More on Collapsing and Expanding

In an earlier post, Douglas Wade reviewed the basics of collapsing and expanding in Arbortext Editor. I would like to add a few thoughts about this feature as it relates to tables.

I recently started working on some SGML files that have large tables. I’m talking really large. I found that the performance of Arbortext Editor slowed considerably whenever I encountered one of these tables.

Then I received a great piece of advice: If you’re not working on tables, collapse them.

You can start by closing all of the tables in your file. Go to the View menu and select Collapse/Expand Divisions. Select the table element and click Collapse.

Now when you need to work on a specific table, expand that table, do whatever you need to do, and collapse it again when you’re done.
Arbortext Editor, Tip

Posted on January 16th, 2010

Written by JeffStein

Related Posts
Arbortext Editor Tip – Identifying Text Entities

In Arbortext Editor, a text entity is a named piece of content. For example, you could create a text entity called Product Name with the content Widget Analyzer 2010. Text entities help you to achieve consistency both within and across documents. Simple enough, right?

Let’s assume that you have an SGML file open and you know that a particular phrase or sentence is already a text entity — but you don’t know the unique name of the text entity. How can you easily figure out the name?

One of my co-workers said that she goes to the View menu and selects Text Entities. The content of the text entity is replaced by a tag that displays the name.

Then I told her my approach. Place your cursor inside the phrase or sentence and choose Entities > Text. The Text Entities dialog box appears with the entity highlighted.

My co-worker said that she liked my approach better. Sweet!
Podcast, Structured Authoring

Posted on November 10th, 2009

Written by douglaspaulwade

Related Posts
PubWright Podcast

My friend Liz Fraley of Single-Sourcing Solutions asked to interview me in a podcast. We have chatted over the last few months on how we wanted to do this. I knew I want to, I needed to learn that medium. So, we played with some technology, and using Skype, and recorders on both ends and we hammered out the first podcast.

Liz took the raw recordings and enhanced them and the conversation sounded good. The podcast collection is called PubWright Podcasts; it is mostly about the Arbortext community. The PubWright podcast interviews Arbortext implementers, customers, and experts in an attempt to share knowledge with the greater Arbortext community. The first podcast featured me. I wanted few more episodes to be released, before I mentioned anything, (the quality of the guest can only go up). So check out the podcast.

This is a Podcast series available here and on iTunes here.

http://podcast.single-sourcing.com
ACL, Arbortext Editor, Perl, Structured Authoring

Posted on November 9th, 2009

Written by douglaspaulwade

Related Posts
Wiki Help Files

One thing that I think about all the time is how to improve documentation. One thing I would like to have is documentation that is context sensitive in Arbortext and collaborative. At work we have a style guide which determines “what” we are to do but rather than “how” to do it. Many years ago, I placed all of the “how to” documentation into Microsoft Word, saved it out as PDF, yet I struggled with this. Next, I desired to work more in XML, so I adopted Docbook. All the Microsoft documents were converted to Docbook which I pushed out, HTML pages, PDF files, and Microsoft Help (.chm) files.

The biggest issue was that I was the single bellybutton to all the documentation. I strived for a collaborative solution. I worked with Wiki’s and set out to install one. Our corporate structure would not allow me to install one. The company had just created one, and they only wanted one in the company culture. I was not sure that I wanted all my documentation out there for all to see. Because I work for a large aerospace company. However, I got over it; it was more important to have collaborative tools rather than my pride. I imported all the docbook information into our Wiki.

The biggest complaint of the wiki was its weak search. I wanted a way for a writer who is authoring in a SGML/XML file, to hit the help button and go to an exact area in the documentation. The Arbortext Editor has the Shift-F1 to present a customized help. I played with it trying to add hyperlinks to those files. With the help of the adepters mailing list and Clay Helberg (a Arbortext guru), he mentioned a few things, one being of which is remapping the Shift-F1 key. The other is how to open a file. So, I used the browse_url function which launches a HTML page, in my case a Wiki page. I needed to add more information in the URL based on the two things: the DTD name and element name. In the Wiki, I am using subpages which are like a collection. All pages will be a subpages grouped in “Structured-Elements” and also “38784″ (the DTD name) followed by the tag name. The tag is found using the ACL functions of oid_name(oid_caret()). The oid_caret is the cursor position and oid_name is the name of the element. So below is the code snippet: I placed it inside my ACL file located at (<arbortext-home>/custom/editinit) which gets sourced when a document is opened.

$dtd = public_id();
if (match($dtd,"38784" )) {
map shift-f1 { browse_url("http://wiki.yourcompany.com/wiki/Structured-Elements/" . "38784/" . oid_name(oid_caret()) ) }
}

When the writers place the cursor inside an element, for example, <title>, and then does a Shift-F1, the Arbortext Editor will open to a Wiki page by element and DTD name.

That was the easy part, now is the hard part; populating the Wiki with content on the elements. With Mil-Spec DTD’s (some of our work uses them), we have a TDT file (it contains all the element names and attributes with descriptions). My co-worker, Joe, our other Software Engineer, wrote a Perl script to convert each element to a Wiki page. I will import a couple of hundred new Wiki pages here in the next few days.

The final part is adding extra links in these new pages to the established Wiki pages, therefore linking the entire project together.
ACL, Structured Authoring

Posted on November 5th, 2009

Written by douglaspaulwade

Related Posts
Removing Unused Graphics

In SGML files graphics are declared. Once they are declared they can be referenced in elements such as <graphic> or whatever your DTD declares. Often during the development of the files, some graphic declarations are created but never used. It is a good practice to remove graphic declarations that are not required.

I came across this ACL file from Karl Johan Kleist (original code by Rune Kallhovd) on Adepters website, listed below.

I named that code below as removeUnusedGraphics.acl and placed it in <arbortext home>/custom/scripts folder. I tied it to a menu on init ACL file (<arbortext home>/custom/editinit) that runs when a document is opened. It has these items added in the menu. First, the file is sourced. second, call the function, clean_unused_gfxents() when the menu item is selected.

Remove Unused Graphic Menu Pick

Items to add to the Menu*

source removeUnusedGraphics.acl
menu_add ".TechData." "Remove all unused graphic entities" -cmd { clean_unused_gfxents() }

Code File

# Rune Kallhovd and Karl Johan Kleist
# Posted 2006-06-18 to adepters.org

function clean_unused_gfxents(doc,op) {

local entArr[], gfxArr[];
local entArrlen = 0;
local gfxCnt = 1;

if (op != 2) {
return 0;
}

# Building an Array of declared entities:

entArrlen = graphic_entity_names(entArr, doc);

# Building an Array of used entities:

for (o = oid_first(doc); oid_valid(o); o = oid_forward(o)) {

# Do we have a Graphic tag?

if (graphic_tag(oid_name(o))) {

# Get the attribute name holding the ENTITY

local gfxentnam = graphic_entity_attr_name(oid_name(o));

if (gfxentnam != "") {
gfxArr[gfxCnt] = oid_attr(o, gfxentnam);
gfxCnt++;
}
}
}

# Iterate over declared entities, and delete unused ones:

for (i = 1; i <= entArrlen; i++) {

local found = 0;

ent = entArr[i];

for (gfx in gfxArr) {
if (gfxArr[gfx] == ent) {
found = 1;
}
}

if (!found) {
undeclare_entity $ent; # NOTE: dollar sign needed here / kjk
}
}
}

# Add the following to e.g. a init() function:
doc_add_callback(0, ‘save’, ‘cor_utils::clean_unused_gfxents’, ‘PREPEND’);

* Menu article coming soon…
Older Posts Yeah! There are more posts, check them out.