H&M Merged Cells Alignment Strangeness (& Fix)

Update: Unchecking the Preferred Width fixed the issue.  H&M’s support forums are great!

I merged the 3 cells in the top row of a table and want to center text in the single merged cell.  It isn’t working as expected.

 

Left Justified - Ok

Centered – Not Ok in .chm

Right Justified – Not Ok in .chm

Help & Manual Publishing Detail

My documentation partner discovered a detail worth knowing about Help & Manual Topic IDs and their corresponding names in HTML Help.  He wrote about it here.

Easier Dr. Explain to Help & Manual #1 of ?

The default Dr. Explain “Generate HTML” and Help & Manual “Import” settings leave each imported topic in a bordered table.  The table looks fine as Dr. Explain output, but it does not look good inside the Help & Manual generated pages with their navigation system.

The easy way to get rid of the table border is to get rid of the table on import.  It is a single-column table so this import option works great.

Dr. Explain “Single Pages”

Dr. Explain technique for updating & adding individual topics in Help & Manual.

Export Options

Make the DrE output as close as possible to the desired layout in H&M.

The Key: DrE’s Topic Property

If the Topic is set the .htm and all the .png’s begin with the Topic.

Import Into H&M

I was surprised that the images automatically went into the Topics subfolder I wanted them in.  In my test H&M project I had to move them from the project’s root folder.  Yet another area of H&M I haven’t figured out yet…  ;-)

Next DrE / H&M Project

Before first import into H&M set up DrE topics logically.  Include a # in the Topic to make it easier to delete obsolete images.

H&M Modular Projects

http://www.helpandmanual.com/help/index.html?hm_advanced_modular.htm 

http://www.helpandmanual.com/help/index.html?hm_ref_modular.htm

A modular help system is one that is made of separate modules at "runtime", i.e. when the user is viewing it. Modular help systems are only possible in HTML Help (CHM) and the obsolete Winhelp (HLP) format.

A modular help system consist of a "master" module containing the main TOC, which must always be present, and one or more "child" modules, any of which may or may not be present.

Th: Disclaimer as master module ??

Help & Manual Publishing Issue Suggestions

Note to readers:  I really like Help & Manual.  It is an outstanding help-authoring tool.  I have been a satisfied user since January 2002.  Their technical support is excellent.

This post is part of a technical support discussion.  I’m trying to be clear.  No offense intended!  I highly recommend Help & Manual to anyone looking for a help authoring program.

 

Recommended Changes

1. Explicit Notification of Topics Not In The TOC

While I now understand that the ability to have different Builds for the TOC and .xml “flavors” of a given topic is considered a feature, I suggest that is appropriate only for advanced users.  If someone’s primary job is writing documentation it’s probably useful and powerful.  But I think it is a bug for novices and occasional users like me.  The default behavior had me publishing unseen, unwanted content.  For me, this is the definition of a bug.

This is a screenshot from your homepage.

Like a word processor and thousands of pages?  Looks great!  Let’s do it!  I set up the project carefully and logically, separating content in both the TOC and the Project Files.  I now understand that I was wrong but I don’t apologize for my initial expectation.  “Like a word processor” and “Thousands of pages”, plus the fact the navigator is called “Explorer”, had me expecting that it would be impossible for the files under
   Topics/UserGuide
to in any way influence anything in, say
   Topics/Overview
It was a shock to me to realize that as far as publishing goes, there are no Topics folders.  They are meaningless for controlling content.  This is quite different from all other Windows programs I can think of that use folder organization.

“Did you read the help?”  “Not much, until I had problems.  What I needed to know isn’t in there anyway: ‘Our folders are not like most every other Windows program you have ever used.’”

“But previous versions worked like this too.”  “That was centuries ago in internet time.  I don’t recall.  My help projects were simpler anyway.  I probably never ran into an issue.”

While I think that the “different Builds for TOC and xml topic feature” should be disabled by default for the benefit of novices and occasional users, that is a significant change.  An acceptable temporary/permanent solution is notification to the user something like this.

A notification like this probably would have saved me many hours.  Clicking on “What does this mean?” should bring up the following.

2. Build & Folders Overview in Help

Maybe pointing to existing Help topic(s) is enough, and maybe not.  The notification of non-TOC topics may have been enough for me to figure out what was happening.

Help & Manual Publishing Issue

H&M version information.

Two people are working on the same H&M project on two computers.  Subversion syncs our work. The project has 10 Custom Builds for the different documents we will publish.  I want to make a .chm of my Overview document (OVERVIEW Build) to view my latest work …

… but I get a bunch of compiler messages.

 

This never happened before.  The other person tried it and it happens on his computer too.  Hummm…  Investigating, yes the offending topic Test Files is only in the USERGUIDE build.  No problem here.

The other person recently added the topic Test Files.  If it is in the wrong Topics folder, could that be a problem?  No, it is in the expected folder.  No problem here.

Then I noticed it didn’t have a Custom Build, and neither do a lot of other topics in this folder.

 

Huh???  I confirm that the Builds for topic Test Files are different in the Table of Contents vs the Project Files.  The Builds are also different for the topic Viewing Output Types.  (I would like to check more topics but it is difficult to do because H&M does not provide TOC / Project Files mapping.  The feature request is already in the Wish List.  See  http://helpman.it-authoring.com/viewtopic.php?t=9348)

 

Looking around and thinking, I may have an idea how this happened.  We initially populated this H&M project with imports from Word, XML Spy and Dr. Explain.  Next we figured out how to make the separate final documents we need, assigning the Custom Builds.  Since then we have been editing.  It looks like all the Build-out-of-sync topics were created in H&M.  In the TOC they “inherit” the Build but they don’t as XML files in Project Files.  Of the topics we have added in H&M it looks like topic Test Files is the first containing links.

Getting rid of the Compiler Message errors is not hard:  Right-click Test_Files.xml and change “Include in Builds” from “All Builds” to “USERGUIDE”.  But IMO this bug should be fixed for two reasons.

1. As a H&M user it seems impossible to me that TOC topics are in any way different from Project Files topics.

2. So far the Build difference has not affected the final output; I have just seen warnings in Compiler Messages.  But when our 30 documentation products (10 Builds @ 1 each CHM, PDF and HTML) are part of our auto build process, how do I have confidence that SomeRandomTopic.xml, Build USERGUIDE in the TOC but “All Builds” in Project Files, won’t suddenly decide to show up in all 30 products?  I have been writing software a long time and have made a lot of mistakes.  ;-)  On the surface this looks to be a “Multiple Sources of Input” error, a technique I have used to create intermittent, hard-to-debug errors…   ;-)

Thanks.

Help & Manual 5 Suggestions

A. “Insert new Topic or Chapter” Dialog Box

1. Change title from “Insert new …” to “Insert New …”

2. Increase “Create in:” dropdown size to cut down on scrolling.

3. Fix focus after invocation by Shift+Alt+Ins.  The dialog box looks like it is ready for input because the Topic Heading is selected.  But keystrokes don’t go to the dialog box.

This focus problem doesn’t happen all the time.  I have not noticed a pattern yet.

 

B. Customize Quick Access Toolbar

I like to add frequently-used commands to programs’ Quick Access Toolbars.  For example this is my Word 2007 environment.  I would be more productive using H&M if any command could be added to H&M’s Quick Access Toolbar. 

Dr. Explain to Help & Manual

DrE “default html” to H&M “default import doesn’t look good.

Help File Technology Stuff

http://www.helixoft.com/images/stories/vsdocman/help/index.html?view_and_deploy_help__manual_d.htm

VSDocman and Help & Manual

… The recommended way of authoring with H&M is to create one master documentation in H&M. Then you generate API documentation with VSdocman and include it into the master documentation. This needs to be done only once. After that, you can generate API documentation with VSdocman any time, without need to open H&M. When the help is ready to be published, just open master document in H&M and publish it. VSdocman already comes with preset master documentation. It is located in Templates\HaM\MSDN_master_project\MasterProject.hmxp. It contains detailed instructions how to use it. …

Deploying Help2 (Visual Studio help)

… H&M generates correct Help2 (.HxS) file. When you publish VS help output in H&M, this file is registered under specified namespace as title. But that's all. Even Document Explorer which automatically opens after publishing is empty. You need to correctly register your help to see it in VS help, whether on your or other computer.