Problem with linkUri and autoOutline

Topics: Developer Forum, User Forum
May 28, 2013 at 2:59 PM
Hi,

We are using SHFB to create both CHM and website help. I've noticed two problems which maybe are caused by some settings which we've set incorrectly.
The first one is dedicated to linkUri tag - we have a similar structure:
<externalLink>
    <linkText>here</linkText>
    <linkAlternateText>here</linkAlternateText>
    <linkUri>https://example.com/test/CaseSensitiveUrl</linkUri>
</externalLink>
When we build the chm file, everything works as expected and the link is correct. But when we build Website output - the link is converted to use only small letters and our case sensitive url doesn't work. Is it possible to control this behavior?

The second problem is with autoOutline tag. For some reason it doesn't work - we are using SHFB 1.9.5 and when we build the project on a local machine, the autoOutline tag is working fine, but if we test the output from our build PC, the content from autoOutline is not working anymore. So I assume it is dedicated to a setting which switches on/off this feature. Am I correct?

Thank you in advance for your help!
Coordinator
May 28, 2013 at 8:22 PM
Regarding the linkURI values, check the page source in the files being uploaded to the server. I'm pretty sure you'll find that the URLs are cased as found in the MAML elements in the topic file. I do notice that IE10 converts the site name to lowercase but it leaves everything after the first '/' cased as given. Unless something on the server is changing them after they've been uploaded or as they're being sent to the client, the links won't change in format.

Regarding autoOutline, it should work as expected as long as each section element has an address attribute. There are no options to turn it on or off, it just works. If it's working on one PC and not another, be sure that you've got the same version of Sandcastle and SHFB installed on both and that the other PC is using the same project and files as the other.

Eric
May 30, 2013 at 6:01 AM
Hi Eric,

Thank you very much for your reply. I've found out that we are using a modified version of main_conceptual.xsl file which was based on an older version of the original file. There are several changes with autoOutline in it and after using the official one, everything worked as expected.
But I wasn't so lucky with the second problem - I've checked the html file and the link is with small letters. I'll continue investigating, but for the moment I'm out of ideas what could cause this behavior.

Thanks again for your help.

Best regards,
Rosen
May 31, 2013 at 12:40 PM
Hi again,

I've finally found what is causing the unexpected behavior with our html files. We have a custom process which is reading the whole file and converting the links in it to use lower case. This task is also replacing the html's names and set them to use only lower cases. We were thinking to use escape sequence for the links we do not want to be converted, for example in our articles:
<externalLink>
    <linkText>here</linkText>
    <linkAlternateText>here</linkAlternateText>
    <linkUri>DONOTESCAPEhttps://example.com/test/CaseSensitiveUrl</linkUri>
</externalLink>
and in our custom task just to remove this sequence. But this lead to additional problem - we produce CHM, HTMLs and Help3 content, so if we apply this behavior, the CHM file will be broken (maybe the help3 file as well, I'm not sure about it). So currently we need a way to modify the aml files (both created from us and from Sandcastle when generating API Reference) before building them into all these formats. Our idea is to use code above with the escape sequence and when we have all aml files to use XML Parser and convert the links to use only lowercases and remove the escape sequence for the other ones. Is it possible to achieve this? Is Sandcastle generating aml files from the dll files and is it possible to use them to achieve the desired functionality. One other thing - is it possible to declare a pattern for the html filenames... I mean we need html filenames to use lowercase, we are currently converting them, but if there is an easy way to achieve this via Sandcastle itself, it will be much better.

Thanks in advance for your help and understanding.

Best regards,
Rosen
Coordinator
Jun 1, 2013 at 8:42 PM
There are a couple of options. One would be a plug-in that modifies all of the XML comments files and MAML topics in the working folder before the BuildAssembler step. You could search for HTML anchor and MAML externalLink elements to modify the URLs. You could add a custom attribute on ones that you don't want modified. Another, approach is a build component that runs as part of the BuildAssembler step. It could run before the Transform component and could search the XML comments or MAML elements (depending on the type of build its running in) and search for anchor and externalLink elements in a similar fashion. A build component would run for each topic so you wouldn't have to search for all XML comments files and topic files as you would with a plug-in.

See the Creating Build Process Plug-Ins and Creating a Component Configuration File topics in the SHFB help file for more info. There's also an old article on the Code Project site that covers creation of build components too.


Eric