Whether you are generating a standalone RH project, or merged help, you must always specify the generation output path for any output preset in Robohelp 2019.

Sometimes, but not always, you “change” the path and then Save your changes, or so you think. . . the change is actually not saved and then your generation can fail if the “old” generation path can no longer be found. For example, I had to move all my local files from one computer with a different user name to a new computer with a different user name. (It was a client-required move and I had no permission to set the username on the new computer . . . I had to go with the new user name). Accordingly, I went in to all my projects and “changed” the output path to reflect the new username, or again, so I thought. . . . and then was caught off guard when the generation failed. When I dug into each failing project, I saw that the output path had not actually been updated. RoboHelp did not recognize the change. . And this can be especially critical when using SharePoint Online for version control.

So, how you you ensure that RoboHelp recognizes it when you change the value of an generation output path? For lack of a better way of saying this, you have to “kickstart” RH into recognizing the change. Consider the figure shown below. In this figure, I manually had changed the username in the path from Spectrum Writing to u103297 and then pressed CTRL +S to “save” the change:

What I failed to notice, however, was that RoboHelp did not recognize this change, so the generation failed on the new computer. What I should have looked at BEFORE saving the change was the Change indicator (an asterisk (*)) that should have been displayed at the top of the HTML5 preset tab . . . had I looked, I would have seen that an asterisk wasn’t there, so RH wasn’t seeing any changes. But for whatever reason, when I would open another project and manually make the same change, RH would recognize the change and that would be indicated by an asterisk (*) being displayed on the HTML5 tab (as shown in the figure below.)

So, what I would wind up doing – after making the change to the output path, if I did NOT see the asterisk displayed, I simply clicked the HTML5 tab, and voila, the asterisk was displayed, indicating that RH was seeing the change and I could save it . . . for lack of a better way of saying this, I had to “kickstart” RH!!! But this one little step -just looking at the preset tab and verifying that an asterisk was present – ultimately saved me a lot of grief when generating a very involved merged help project.

Also, if you are using SharePoint Online for version control, and you make a change to anything in a project, such as the Output Path, then a Check-in dialog box should open with the affected files listed – if the Check-In dialog box opens, but no files are listed, then this is yet another indicator that the change was not recognized by RH. . .

So – the summary of this is – if you *think* that you made changes to a project, before “saving” these changes, look for an asterisk on the appropriate tab and if it’s not displayed, “kickstart” RH into recognizing these changes before saving them – and a great indicator that RH did  recognize these changes when using SharePoint Online for version control is the prompt to save these changes in a Check-In dialog box when you check the files back in to SharePoint Online!!

With RoboHelp 2019, you can ensure everyone stays on the same page by enabling version control and sharing and collaboration across your organization with SharePoint Online. Although Adobe does provide instructions about setting up your RoboHelp 2019 environment for use with Sharepoint Online (https://helpx.adobe.com/robohelp/using/sharepoint.html), in my quest to set up my working environment properly, I discovered some previously undocumented requirements and a few key steps  that you must explicitly follow to ensure a smooth integration between SharePoint Online and RoboHelp 2019. Here I summarize this information, including a few tips and tricks to make the integration easier to maintain and troubleshoot.

Note: The following notes are written from the perspective of having local RH projects that you want to upload to Sharepoint. (You can also have RH projects that are already in Sharepoint that you want to download locally.  For additional support, see the following video from Adobe: https://bluejeans.com/s/cbMCm.)

  • By default, RoboHelp 2019 saves all projects to the following root folder structure: C:\<user>\Documents\My RoboHelp Projects. You can change this location when saving a RH project, but for easier tracing and troubleshooting, ideally, you should retain this default root structure. You can make your folder structure under My RoboHelp Projects as light or deep as you need to fit your organization’s business requirements and needs.

Figure 1

 

 

  • When you create your SharePoint Online folder structure, you must create the structure under the root Documents library of SharePoint. You cannot create the folder structure anywhere else.  For example, on the dev<client>.sharepoint site shown in Figure 2 below, (https://dev<client>.sharepoint.com/testsite) you can see the folder structure set up under the root Documents library of SharePoint Online.

Figure 2

  • After you create a new SharePoint site, or are added to an existing site in an Enterprise environment, you might need to wait 10 to 15 minutes for your user information/permissions to propagate before you set up your SharePoint connection to the site; even though the site is “there,” I encountered on several occasions the message that the site could not be found and prompting me to confirm that I had access to/permissions to the site if I then immediately set up a new connection in RH to the site. When I waited about 15 minutes, and then set up the connection, the connection was successful immediately
  • The folder structure under Documents can be as light or deep as you need it to be to fit your organization’s business requirements and/or needs. What is critical is the content that is already present in the SharePoint site that maintains your RH content. The more content (folders and files) that the site contains, then based on how SharePoint makes synchronization calls, the longer it takes for synchronization to complete. The ideal setup for your SharePoint folders is a site that is dedicated solely to your RH content, even working in the enterprise world. And although not a requirement, if your organization allows it, a folder structure that is as light as possible at the Documents level.  It is required, however, that all your SharePoint folders be blank, which is not an issue when you create a folder for the first time, but can become one if you want to re-use an existing folder structure. (Case in point: In a side by side comparison of a folder structure where one was set up on a dedicated site and the same structure was set up on a site that already contained deep content (folders and files), the server syncing process for the same project was 3 minutes for the dedicated site and over 12 minutes for the multi-content site. For me, with 20+ projects required for merged output, this time difference was untenable. I had to move my content to a dedicated site.)
  • Only a single RH project is allowed per SharePoint Online folder.

Figure 3

 

  • Every time you open a RoboHelp 2019 project, a .rh folder is created. Before you can integrate a RoboHelp project with SharePoint Online, you should prep the project by deleting the .rh folder.  After the integration is complete, then when you open the Robohelp project again, the .rh folder is recreated, but it is not an issue. (Although not a requirement, there are some cases where first deleting the .rh folder is a necessity and rather than running into hassles when you encounter one of these nebulous cases, it’s just safer to always make this step a part of your process.)

Figure 4

  • In Adobe’s instructions (https://helpx.adobe.com/robohelp/using/sharepoint.html), under the section titled: Add a project to SharePoint Online, Step 2 references the option  Collaborate > Add Project; however, this option is not available on the Collaborate menu until after you open your first local project in RoboHelp for your opened SharePoint connection.  You can use any of the available means to open your first local RH project that you are adding to SharePoint Online, but the quickest and simplest way is to simply double-click the project file in Windows Explorer and RH is launched and the project is opened in RH.  As long as you remained logged in to your SharePoint Connection, then the Add Project option remains persistent for the duration of your RH instance. Going forward, any time you open a SharePoint Online connection for which a RoboHelp project has already been saved, the Add Project option is displayed on the Collaborate menu.

Figure 5

Note: Remember, the local project must not contain the .rh folder and this must be the first time that you have opened the project in RoboHelp after deleting the .rh folder. If you have opened the project for some reason before adding it to SharePoint Online, you must delete the .rh folder, and then close the project before opening it in RoboHelp.

  • When you are working with project files frequently, you want to globally/en masse apply a change to the files such as applying a new Master Page or css. The function for this is found through Reports > Topics List function and if in SharePoint, invoking this function on all files in a project >>SHOULD<< check out all files in the project but I found that it doesn’t; however, if I manually selected all the files in the contents pane using CTRL + A, and then right-clicked any selected file, and on the context menu that opened, selected Properties, then 100% of the files in the project were checked out. I confirmed this behavior for multiple projects and it was repeatable, so I have entered a bug in Adobe Tracker and you can view here – https://tracker.adobe.com/#/view/RH-7693. (As soon as I know the disposition of this bug, I will update this blog. TVB 7/15/2020)
  • Deleting a connection profile: The Collaborate menu makes it apparent where you create/add a new connection profile, open a connection, and review the profile information for a selected connection, but it is not obvious where you delete a connection. To delete a connection, on the Collaborate menu, select Connection Profiles to open the Connection Profiles dialog box, and then place your mouse pointer to the lower right of the profile that you are deleting to display the Delete icon. You can then click this Delete icon to immediately delete the connection.

Figure 6

  • After you sign in to a SharePoint Connection, there is really no need to sign out. . . in fact, you can be signed in to multiple connections as the same time; however, for whatever reason, if you want to sign out, then, open Connection Profiles, select the appropriate connection (if you have more than one connection), and then click Sign Out and then click Cancel. (It’s not obvious that this signs you out of a connection as there is no Save to confirm the sign out, but if go back to Open Connection, the option to Sign In is enabled for the connection.)

I hope you find these tips and tricks informative and that they help make the process of integrating RoboHelp with SharePoint Online simpler and easier for you!!!

Framemaker for Single Sourcing

by tammyvb on October 28, 2011

[Excerpt from the Autumn 2009 issue of Communicator Magazine]
Communicator Magazine

Text Insets and Conditional Text

For FrameMaker users seeking single sourcing on a shoestring, Tammy Van Boening of Spectrum Writing offers a solution based on these features.

Figures 1 & 2

Text insets in FrameMaker offer a way to single-source content by sharing chunks of text across multiple files and books. Text insets are FrameMaker files that you import by reference into another FrameMaker file. The terms used to describe the files used are:

  • Container file (destination file) — this is the FrameMaker file into which you import one or more text insets. This is also the file you use to build the book you are creating.
  • Text inset (source file) — this is the FrameMaker file that you import into the container file. It typically contains content that you want to share across multiple files or books.
Figure 1 shows examples of both types of files.

Using Text Inset Files

You can put each piece of text into a separate file or place them in separate flows of a single file. You also have options when you import the text inset. Below are tips for setting up text inset files:

General Tips
  • To ensure that all styles, conditions and variables have the same names, use the same template as you use for container files.
  • Name files carefully to make their contents easily identifiable. For example, you could base the names on the headings that the text inset goes with and end them with an identifying suffix:
    • Figures 3 & 4 Intro suffix for introductory text
    •  Overview suffix for conceptual or explanatory material
    •  Proc suffix for procedures.
  • Text insets inherit the conditional text settings of the container file. Use conditions as necessaryin the text inset files (Figures 2 to 4).
    • If you need a whole text inset to be set up with a condition, apply the condition in the text inset file to all of the text. If you apply the condition to the whole text inset in the container file, you will lose the condition setting when you update the text inset.
    • You cannot use conditions on individual rows of a table that is in a text inset file. You can, however, use conditions on an entire table in a text inset.
  • Import variables into the text inset file: importing variables into the container file does not change them in the text insets.
  • Make the first paragraph of each text inset file a small anchor tag and put a non-breaking space as the first character in the paragraph (Figure 5).
  • All headings, figure captions and table titles are in the container book’s TOC, LOF and LOT, whether the heading, figure caption or table title is in a container or a text inset file.
  • All auto-numbered items such as figures and tables will be numbered correctly, whether the item is in a container file or a text inset file.
  • Place all text inset files into a separate book. This permits:
    • Spell checking of all text insets: FrameMaker’s spell checker skips the text insets in the container file.
    • Searching and replacing in all text insets: FrameMaker’s search function skips the text insets in the container file.
    • Any other book-level functions, such as show/hide conditions or importing variables.

Figure 5.

Tips for Using Flows
  • Follow all of the tips above for separate files.
  • Name each flow carefully to make the flow content identifiable.
  • Consider using flows for all insets for a particular chapter, so that each chapter has a single text inset file, with a separate flow for each text inset.

 To Create a Text Inset:

  1. Create a new, empty file based on your chapter template. Note: Make sure the file has all of the variables and conditions you need to use.
  2. Apply your anchor style to the first paragraph and put a non-breaking space as the first character in that paragraph (Figure 5).
  3. Start text in a new paragraph below the one you just created.
  4. Save the file to the folder where all the text insets for the book will be, giving the file a meaningful name.
  5. Add all text, tables and figures as you normally would.
  6. Make sure that your text ends at the end of flow symbol and that there is no extra paragraph below your text (Figure 6).
  7. If you need to create cross-references to or from the text inset file, see Cross-references and hypertext markers later in this article.
  8. Add the file to the text inset book that is in the same folder as the text inset.
  9. Run the spell check on the text inset book and other book-level functions as needed.

Setting Up Container Files and Importing Text Insets:

Below are some tips for setting up container files:

  • Place all headings in the container file. This makes it possible to use normal FrameMaker cross references to all headings, set up index markers and so on.
  • Import each text inset file into a small anchor paragraph in the container file. (This is the same anchor paragraph tag that you used for your text insets; however, you do not need a non-breaking space before this tag in your container files.)
  • Place index markers in the heading paragraphs of the container files.
  • You can open a text inset after you insert it into the container file by double-clicking on any text in the text inset. The text inset does not open if you double-click a graphic in the text inset.

Figures 6 and 7

Recommended options for importing text insets

Various options are available for importing text insets. However, the default settings (Figure 7) typically meet most users’ needs and require no modification.

Moving or renaming container files

If you need to move a container file from one folder to another or rename the file, open the container file and use File > Save As to move it to a new folder or to rename it. This method retains the following:

  • Links to text insets
  • Links to graphics in both the container file and any text insets
  • Links to cross-referenced files that are in their original locations.

If you move the cross-referenced container files, the cross-references break. You can use FrameScript and a custom script to resolve this issue. Framescript is a high level, user-oriented, scripting (or macro) language designed to work with Adobe FrameMaker. You use FrameScript to customise the features of your FrameMaker installation. In this customisation, a custom script can look for the referenced files in the same folder as the container file and update the path to the cross-referenced file. Visit www.framescript.com and www.frameexpert.com for FrameScript and the necessary custom scripts, respectively.

To Create a Container File

  1. Create a new, empty file based on your chapter template.
  2. Enter all headings needed in the document.
  3. After each heading, press Enter to create a new, empty paragraph.
  4. Apply your anchor style to the paragraph that you have just created.
  5. With the cursor in the empty paragraph, select File > Import > File to open the Import dialog box.
  6. Select the text inset file you want to import. Leave the Import by Reference option (the default) selected.
  7. Click Import to open the Import Text Flow by Reference dialog box.
  8. Select the options you need. Leave the default options selected, as shown in Recommended options for importing text insets, as these work well.
  9. Click Import.
  10. Save the file.
  11. Continue adding headings and text insets as necessary.
  12. Add index markers to the heading paragraphs.
  13. If you need to create cross-references to or from the container file, use standard FrameMaker procedures for creating cross-references.
  14. If you make changes to a text inset, you must do one of the following to ensure that the container file has the latest version:
    • After closing the text inset, double-click the text inset and click Update Now.
    • From the container file, select Edit > Update References, select the two text inset options and click Update.
    • Update the book.

To Use a Container File in a Book

  1. Open the book in which you want to use the container file.
  2. Add the container file to the book just as you would add any other file.
  3. Update the book, making sure that the Update All Text Insets option is selected.
    If necessary, before step 3:
    • Spell check your separate text inset book.
    • Carry out any search and replace operations on both the book file and the text inset book file.

Cross-References and Hypertext Markers

Cross-references and text insets are a complex subject. You can manually create the necessary references and markers; however, custom FrameScript scripts can easily resolve these issues for a fraction of the cost and time of manually resolving them. Visit www.framescript.com and www.frameexpert.com for FrameScript and the necessary custom scripts, respectively.

Text insets and generated files

The numbering and content in index markers, headings, tables and figure captions you create in text inset files will be picked up by any generated files in the book containing container files. This means that your table of contents (TOC), list of figures (LOF), list of tables (LOT) and index files include all the paragraph tags that you expect them to from both the container files and the text inset files used in your container book.

Jumping from the TOC, LOT or LOT

If you try to jump to a specific item that is in a text inset file in FrameMaker using Ctrl+Alt+Click, for example to a figure from the list of figures, the container file opens and the whole text inset where the figure appears is selected but does not open. However, after you create a PDF file and click a paragraph in the LOF, you will go directly to the figure.

Jumping from the Index

If you try to jump from the index file in FrameMaker to an index marker in a text inset file using Ctrl+Alt+Click, the text inset file opens and the index marker is selected. This behavior is completely normal. If you edit the index marker, close the text inset file and update the container book, then your index is updated.

Summary

This article has shown that by using FrameMaker, FrameScript, text insets and conditional text, those who do not have the budget, time or personnel to implement new tools can share chunks of content across multiple books.


Tammy L. Van Boening is an STC Senior Member and an officer in the Rocky Mountain Chapter. She has strong experience in devising inexpensive single-sourcing techniques for small technical writing and training departments since 2000. Tammy specialises in creating usable documentation for software products for both print and online use and has developed and delivered writing and training products for a diverse range of industries and clients.

E-mail: info@spectrumwritingllc.com
Website: www.spectrumwritingllc.com

 

{ 0 comments }

Autonumbering in Microsoft Word

by tammyvb on October 27, 2011

For my technical publications clients, I use a true desktop Publisher (Framemaker) to produce standalone documentation or to single source to an Online Help standard output such as Microsoft HTML 1.x help; however, many of my clients, for their own internal documentation, use Microsoft Word. Because I am a writer, they naturally assume that I know many things about many different tools, and reach out to me for help, in particular, Microsoft Word and numbering. I could write pages and pages about all the issues with numbering Microsoft Word, and I know that we all have felt the pain of opening a document having all the numbering and bulleted lists go to heck in a hand basket for no apparent reason other than “it’s what MS Word does.”

Sequence fields are a way of semi-automating the process of numbering in an MS Word document, and ensuring that you will have stable numbering and bulleted lists in MS Word documents that you produce. It also allows for easy updates of numbering when you insert or delete a paragraph in an MS Word document. I have offered this solution to many of my clients who have suffered the follies of numbering in MS Word and all have been happy and appreciative of the solution. I thought I would make it general knowledge and share it with anyone who chooses to read by blog. Hopefully, this will help alleviate some (but not all) of the suffering when working with an MS Word document.

P.S. This is written from the perspective of Word 2007, so some of the options might be found in different places and/or on different menus in different versions of Word, but once located, the steps are still the same.

TVB

1.) Open a blank Word document and click anywhere in the document.

2.) On the main menu, click Insert > Quick Parts > Field.

3.) In the Field dialog box, in the Field names list, select Seq. (Note how the Field codes field is automatically populated with the field code of Seq.)

Field_dialog_box

4.) After the field of SEQ, enter the code for the field with the following information:

  • The name of the field.
  • The field type. (By default, unless otherwise specified, the field type is assumed to be a numbered field.)
  • The starting number for the field, which indicates whether the field is to be a beginning field (for example, a “1” or an “a”), or a continuation field (for example, “2” or greater, or “b” or greater).

Here is an example of setting up a field code for a numbered list that is to begin with a “1″ where “numberlist” is the name of the list and the switch \r 1 indicates that the list is to be reset to “1.”

SEQ numberlist \r 1

  • Note that there is a space between numberlist and the backslash and there is a space between the “r” and the “1.”
  • It’s also important to note that I have named the field as “numberlist,” and by default, unless otherwise specified, Word assumes that the field code is to be used for a numbered list. You will see how to indicate an alphabetic list later in this lesson.

5.) Clear the Preserve formatting during updates option.

Field_dialog_box2

6.) Click OK and the number “1” is displayed where you clicked in the blank Word document.

7.) Select the “1” that is displayed, right-click it, and on the context menu that opens, select Toggle Field Codes to display and automatically select the field code for the number.

Field_code_selected

8.) After the last right curly bracket in the selected field code, type a period, press the Tab key, and then enter a space after the tab.

Field_code_space_tab

9.) Select all of the above code with the exception of the space. (Yes, this does mean select the tab character as well. This easiest way to select all but the space is to place the cursor at the beginning of the field code, hold down the Shift key, and then press the Right arrow key as needed until all but the tab is selected.)Field_code_selected_nopsace

10.) Open the AutoCorrect dialog box. (In Word 2007, this means clicking the Office 2007 button (which, to me, looks like an obnoxious knock-off of the Olympic Rings in the upper left corner of Word), and then clicking Word Options > Proofing > Autocorrect Options.)

AutoCorrect_dialogbox

11.) In the Replace field, enter the shorthand notation that you want to use for a paragraph that is to be numbered “1” in any of your Word documents. For example, in my Word installation, I entered  1], which is the number 1 followed by a right bracket ( ] ).

12.) Make sure that the option of Formatted text is selected.

13.) Click Add, and then click OK.

Now, every time that you want a paragraph to begin with a “1,” you need to simply enter a “1” followed by a right bracket “( ] ) and press Enter. The paragraph is numbered with a “1” that is followed by a period and a tab. You can then use Word Styles to change indent levels, and so on for different levels of numbered lists.

To repeat this procedure for continuation numbers for numberlist, make sure that the code for the continuation numbers is named identically– SEQ numberlist \n – where the \n is the switch that indicates to continue numbering the numberlist paragraph. (In my Word installation, I use a “2” followed by a right bracket ( ] ) to for my replacement text.)

For lower case alphabetic lists, I named the list “alphalist,” and the codes for lower case letters are as follows (noting that, unlike numbered lists, you must specify not only the switch, but also, that the numbered list type is to be a lower case alphabetic list. This requires the insertion of \* alphabetic between the list name of “alphalist” and the list switch of either \r 1 or \n).

  • SEQ alphalist \* alphabetic \r 1
  • SEQ alphalist \* alphabetic \n

For the replacement text, in my Word installation, I use a lower case “a” followed by a right bracket ( ] ) for the beginning letter “a” and I use a lower case “b” followed by a right bracket ( ] ) to indicate continue with “b” or greater.

For upper case alphabetic lists, the code for the numbered list type is Alphabetic (note the upper case “A.”) Also note that in the Auto Correct dialog box, a distinction is NOT made between upper case and lower case letters in the Replace field. For example, if you indicated that a] was to be used for the beginning lowercase “a,” you could not enter A] as the replacement text that is to be used for the beginning upper case letters. Word would automatically change the upper case A to a lower case a and you would wind up with two identical replacement codes to mean two different things and this simply won’t work! In my Word installation, I used an upper case A followed by a right curly bracket ( A} ) and an upper case B followed by a right curly bracket ( B} ) as my replacement text for upper case alphabetic lists.

Updating after you insert or delete a numbered paragraph is now easy and straight forward. If you insert or delete a numbered paragraph in a Word document, simply select any numbered paragraph in the list, right-click on the selected paragraph, and on the context menu that opens, click Update Field. The picture below illustrates this:

AllSteps

  • I decided that I needed to insert a step between Step C and Step D.
  • After insertion using the replacement code of B}, Step D was indeed inserted after Step C and what was the previous Step D.
  • I select and right-click on what was the previous Step D, and on the context menu that opens, click Update Field.
  • The previous Step D now becomes Step E as needed.

 

{ 1 comment }

Resizing Visio Swim Lanes

by tammyvb on October 14, 2011

Ah, “swimlanes!” Gotta’ love the term. Ever tried to resize a swim lane in a cross-functional flowchart in Visio and dealt with the frustrations of the swim lane “swimming” all around instead of resizing? Well, there is a way not only to resize swim lanes, but also, to keep all your swim lanes in the same view, even when the Visio diagram extends beyond a single page. (And FWIW, if you try googling this topic, you will find that Microsoft doesn’t refer to swim lanes as swim lanes – the very unfamiliar term of “band” is used instead. And, no amount of googling resulted in a hit about resizing either with the term “swim lane” or the term “band.” Evidently, it’s a trade secret that Microsoft wants to keep secret!)

Please note: This is specific for Visio 2007 and might be different for other versions of Visio. Googling the terms used in this post and your version of Visio might help you resolve the differences.

1.) Open a blank Visio document.

2.) On the main menu, click File > New > Cross-Functional Flowchart with whatever units and direction you prefer. (In this example, we will use US Units and horizontal.)

3.) Add a single band.

4.) Select the entire band in two steps.

  • First, click on the Title section of the band (the section with the placeholder of <Function>).
  • Second, click on the bottom horizontal line of the band itself. The band should be highlighted as shown in the figure below.

image

5.) Right-click on the selected bottom band, and then under Format, select Protection and clear the option for Height.

6.) Right-click on the selected bottom band and under Format, select Behavior, and then under Resize Behavior, select Reposition Only.

7.) Select only the Title section and then hold your cursor over the middle button until the cursor changes to a double-headed arrow and the Resize Shape tooltip is displayed as shown in the figure below.

image

8.) Click and hold the cursor on the middle button and drag to resize the band.

9.) Add the necessary Visio objects to the resized band.

Note: You can resize a band after you have added objects to the band only if the objects are not connected to other objects across bands.

8.) Repeat this procedure for each band that is to be added to the flowchart.

9.) Optionally, if the number of bands will exceed the vertical length of the page display, then under File > Page Setup > Page Size, select Size to fit drawing option. This results in all the bands being displayed on a single page.

{ 22 comments }

SiteLock