Pages: 1
Print
Author Topic: modifying CHM output functionality  (Read 7968 times)
Maria
Member

Posts: 8


« on: December 02, 2010, 11:20:25 AM »

XMetal does a nice job of very bare-bones CHM output. I know how to tweak the CSS to modify fonts etc. but I wonder if there is a way to modify the CHM UI itself.

For example, my CHM opens with 3 tabs: Contents, Index, Search  (no favorites). I want users to be able to click on the Search tab and have an option to *search titles only*. Reason being, if they type in any word here, they will get all the hits on the links as well.

XMetal help has a good example of what I am looking for. See attachment.  Is there any way to get this into my output without too much programming pain?

Thanks,
Maria


* chm_output.jpg (49.05 KB, 477x427 - viewed 638 times.)
Logged
gcrews
Member

Posts: 265


« Reply #1 on: December 02, 2010, 01:22:29 PM »

We had the same issue a long time back. You will have to tweak the map2hhp.xsl quite a bit most likely.  I created a plug-in and overwrote some xsl templates. This link may help with editing the hhp format: http://www.nongnu.org/chmspec/latest/INI.html#HHP

One thing you’re going to have to do that took me forever to figure out why my xsl changes were not  having any effect is to not have Xmetal compile the CHM but let the toolkit do it.  Xmetal does some stuff to the hhp and  it does not copy across the “main=…” code.  You use ANT_PARAM_args.htmlhelp.skipCompilation I think.
Logged
Derek Read
Program Manager (XMetaL)
Administrator
Member

Posts: 2621



WWW
« Reply #2 on: December 02, 2010, 03:03:24 PM »

If you need this to be done as part of the output generation process kicked off from the XMetaL Author Enterprise UI then the XSLT would need to be altered (as gcrews suggests).

However, a simpler (more immediate) fix might be to generate output, locate the HHP file in the output folder, double click to open it in HTML Help Workshop, modify as necessary (according to the Microsoft documentation for HTML Help Workshop or perhaps using some other documentation if that is simpler) or modify the HHP file directly if you are familier with the format (it is just a text file). Then generate the CHM one more time directly from within HTML Help Workshop (there's an icon that looks like a meat grinder that does that).
Logged
Maria
Member

Posts: 8


« Reply #3 on: December 02, 2010, 06:20:03 PM »

thanks for responding to this issue:

gcrews: I was afraid of that. however, I would ultimately like to have the output generated through XMetal, so I guess I am going to have to roll up my sleeves and get my hands dirty with the transforms. Thanks for the steps to doing this, though I doubt I will get through it without another query to the this group (or an OTK group).

Derek: thanks for providing a simple option for doing it "in-the-meantime." I followed your instructions and now I do see the Advanced Search options and the Favorites tab. However I would have to do this everytime I generate output and that just won't scale.

Alas, I will not be able to avoid learning XSLT for much longer and it sure doesn't look easy.
Logged
Derek Read
Program Manager (XMetaL)
Administrator
Member

Posts: 2621



WWW
« Reply #4 on: December 02, 2010, 07:35:17 PM »

@gcrews: "Xmetal does some stuff to the hhp"...

If you are wondering what XMetaL is actually doing when it calls the DITA OT to generate output you may wish to view the list of commands that XMetaL calls.

The commands are in the following file (for XMetaL Author Enterprise 6.0), which you can open directly inside of XMetaL (a basic customization is provided to view these files). Search for the text "HTML Help (CHM)" to find the list of commands used by the CHM deliverable.

C:\Program Files\XMetaL 6.0\Author\DITA\XACs\shared\renditions\print_dita142.xml

The content of each <bat_line> is copied verbatim into a standard (DOS) batch file before that batch file is run.

If you want to see what everything looks like you can get XMetaL Author Enterprise to generate output and not clean up any of the files it uses to do that:

  • a) Select Tools > Configure Output and in that dialog on the Advanced tab look for the following setting:
                    _rem_cmd_synchro_mode  =  2
    b) Remove the _rem_ part so that it looks like this:
    cmd_synchro_mode  =  2
    c) Open a DITA map or topic and generate output using the "HTML Help (CHM)" deliverable. When that process is complete select the Open Folder button instead of Open File in the dialog that appears. You can select any deliverable type, but we were initially discussing CHM output in this thread.
    d) In the folder that opens there should be a subfolder called xmetal_log (yes, I agree this is a perhaps a poor name choice, but this feature was not originally designed to be visible to clients and was also initially used for the output log only). Inside that folder is everything you need to generate the same output you just generated. You simply need to run the file dita_call.bat again.
    e) To show that it is this set of files that is actually generating output shut down XMetaL, then inside the chm_out  folder delete everything except the xmetal_log folder, and finally inside xmetal_log run the dita_call.bat batch file.

An added benefit of turning on the cmd_synchro_mode = 2 option (which is currently undocumented) is that you can generate output and then immediately return to editing in XMetaL Author Enterprise. Without this command XMetaL is performing the exact same set of steps, it just locks itself and then cleans up the xmetal_log folder so that you never see it.
Logged
gcrews
Member

Posts: 265


« Reply #5 on: December 02, 2010, 07:56:34 PM »

Thanks, Yeah I pretty much know what it’s doing and have some custom print items already. What I was kind of referring to was when Xmetal copies the hhc and hhp from a sub folder if the base path was altered during compile because of referenced file outside the map directory. The toolkit may generate the hhp at chm_out\subfolder\map.hhp but if Xmetal triggers the compile, it uses the CopyHHP prototype in DitaRenditions.js to copy the hhp to chm_out\map.hhp. The updateString function in the CopyHHP prototype ends up goofing up the hhp my xsl creates because it  is not aware of [window] and treats the next lines like the last hhp section trying to resolve the main=”… line as if it was a file path. I can fix the code in about 5 min but the DitaRenditions.js seems to be a kinda core xmetal file I don't want to touch.
« Last Edit: December 02, 2010, 10:56:38 PM by gcrews » Logged
Maria
Member

Posts: 8


« Reply #6 on: December 03, 2010, 10:42:36 AM »

Just to refer back to my original question about the Search tab...I wonder if there is a hack that will allow you to expand the search options.
 
For example, since my reltables produce a lot of links, it makes the CHM search functionality irrelevant. If someone searches for "Configuring Admin rights," not only does the system return the Configuring Admin rights topic, it returns dozens of pages that have an xref to Configuring Admin rights. The top hit is not always the main topic page either.
I wish there were a way to specify, IGNORE XREFS.
Another thing, and this may just be the limits of HTML Help; there is no way to say Search exactly this string of words: "Configuring Admin rights." The system returns every instance of the word "configuring."

HTMLHelp (or is it RoboHelp) hasn't changed in 2 decades...I wish XMetal partnered with a better Documentation Help producer. Is there anything more important in documentation than findability? The single biggest complaint I hear from users about the embedded help in applications is, you can never find anything. 2 decades and no improvement...
Logged
gcrews
Member

Posts: 265


« Reply #7 on: December 03, 2010, 11:04:50 AM »

I'm not sure theirs any way to exclude xref text for chm full text search. we are having this problem to.  I have taught about a few things that could possibly work but haven't tried them yet. Maybe adding non printing charters or extra tags to the xrefs every 5 characters would get it thrown out of the full text search. as for the exact string just use quotation marks. The chm search is quite powerful, that's one of the main reasons we still use it, here is an page that explains the search pretty well:
http://helpware.net/htmlhelp/hhfindingtext.htm

update: I just did a quick test and if the html link has the text of “Config<b></b>uring Admin rights” it doesn’t seem to pick it up in the search. It’s kind of a hack but other than that you’re kind of stuck with how the html search works. To even get that to work you’d have to get pretty familiar with the xsl files to be able to salt the html links.
« Last Edit: December 03, 2010, 12:22:35 PM by gcrews » Logged
Maria
Member

Posts: 8


« Reply #8 on: December 03, 2010, 12:46:20 PM »

thanks gcrew. Though I appreciate the very helpful link to using HTML Help Search, I do not share your opinion that HTML Help Search is powerful. Most users are accustomed to advanced searching that does not require you to know the symbols and syntax (e.g. boolean, et al) to find something; so this approach is not obvious. They are also accustomed to more relevant results too. It would be very easy for Microsoft to create a UI with better Search capability.

Thanks again for all the helpful replies.
Logged
Su-Laine Yeo
Solutions Consultant
Member

Posts: 260


« Reply #9 on: December 03, 2010, 02:20:23 PM »

Hi Maria,

You might want to take a look at WebHelp as a help delivery format. By default, the search feature that comes with XMetaL's WebHelp is not the most powerful, however WebHelp is open so you can integrate a search engine of your choice into it. An example is here: http://forums.xmetal.com/index.php?topic=1080.0

Good luck,
Su-Laine


Logged

Su-Laine Yeo
Solutions Consultant
JustSystems Canada, Inc.
Pages: 1
Print
Jump to: