What is the recommended way to add links to topics in other CHM files

[RobertvanderHulst]

Our documentation consists of "manual" written help and generated help. From the manual written help we can add links to the topic pages in the generated documentation. I would also like to add links back to the manual written help. What is the recommended way to do this ? I have experimented with

cref="ms-its:HelpFile.chm::/page_url.html"
cref="MSITStore:Helpfile.chm::/page_url.html"
cref="mk:@ms-its:HelpFile.chm::/page_url.html"
cref="mk:@MSITStore:Helpfile.chm::/page_url.html"

href="ms-its:HelpFile.chm::/page_url.html"
href="MSITStore:Helpfile.chm::/page_url.html"
href="mk:@ms-its:HelpFile.chm::/page_url.html"
href="mk:@MSITStore:Helpfile.chm::/page_url.html"

But that did not work.

[EWSoftware]

I'm not sure of the exact format but I think it is similar to opening external files such as Word documents and PDF files. As I recall, an external link will work but you have to specify the fully qualified file:// URL using the location of the external help file (no relative paths). Unless you know where it's at that may not be feasible. You may also run into security issues as well. In the case of Word documents and PDF files, they can be embedded as resources within the help file at which point relative paths work and there are no security issues since it's within the help file.

[VBWebprofi]

I would also like to add links back to the manual written help.

How did you wrote it? in HTML or MAML?

[RobertvanderHulst]

Holger,

I have not been able to get this to work unfortunately. If you figure out how to do it then that would be great.

I am also looking for a way to add category pages to our help file. The development language that we create (X#) has functions like VB (I guess you know VB since your name is VBWebprofi). All functions are compiled by the compile into static methods of a compiler generated functions class (I think VB.Net does something similar). We have adjusted the SHFB template so it does not show "Functions.Foo" method but "Foo Function". We have also added a syntax component that generates prototypes in our own language.

I would like to add pages to the documentation with "String functions", "DateTime Functions", "Conversion functions" etc.

In theory this should be possible by adding custom XML tags to the XML documentation and then add a step in the presentation template to combine them. But that is too much work and requires source code changes in all functions.

I think I will create a CSV file or something like that with the function names in one column and the category in another column and then write a small helper program to generate aml pages per category. That should be much easier than doing it manually or by adding custom tags to each function.

Btw: The "external" help file is produced with Help & Manual. H&M has an option to run sandcastle, but it cannot be configured like SHFB.

Robert

[VBWebprofi]

Sorry, don't know X#, programming now mostly in C#.

Our documentation looks like this:

  /// <summary>
  /// WpColor class
  /// </summary>
  /// <revisionHistory>
  ///   <revision version="1.1" date="2020-07-23" author="VBWebprofi">Added: <see cref="CanDelete"/></revision>
  ///   <revision version="1.0" date="2020-03-11" author="VBWebprofi">Initial implementation</revision>
  /// </revisionHistory>
  [CodeVersion("1.1")]
  [DebuggerDisplay("{GetType().Name}; Order := {Order}, ForeGround := {ForeGroundColorString}, BackGround := {BackGroundColorString}, IsGNYE := {IsGNYE}, Id := {Id}")]
  [DatabaseConnectorBase.DatabaseTable("TL_WP_COLORS",
                                       ColumnPrefix = "WPCL_")]
  public partial class WpColor :
    ObjectBase<WpColor>
  {
    #region Construction/Destruction

    /// <summary>
    /// Constructor
    /// </summary>
    /// <param name="obj_Connector_p">Related connector instance</param>
    /// <revisionHistory>
    ///   <revision version="1.0" date="2020-03-11" author="VBWebprofi">Initial implementation</revision>
    /// </revisionHistory>
    protected WpColor(IConnector obj_Connector_p) :
      // Implicit parameter check
      base(obj_Connector_p)
    {
      // Nothing to do
    }

    #endregion
  ...
  }

and some MAML

<?xml version="1.0" encoding="utf-8"?>
<topic id="ed459d65-1b8b-4a49-ac69-018aae866bca"
       revisionNumber="1">

  <developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
                               xmlns:h="http://www.w3.org/1999/xhtml"
                               xmlns:xlink="http://www.w3.org/1999/xlink">
    <introduction>
      <para>Informations about database connector</para>

      <autoOutline/>
    </introduction>

    <section address="DatabaseConnectorOverview">
      <title>Database Connector Overview</title>

 ...

If you use MAML now you can add the topic ID (from attribute "id" of XML element "topic" in MAML) with an XML comment into your class/function documentation by conceptualLink. The target attribute then has to point to the ID of the conceptual topic.

  /// <summary>
  /// WpColor class
  /// </summary>
  /// <revisionHistory>
  ///   <revision version="1.1" date="2020-07-23" author="VBWebprofi">Added: <see cref="CanDelete"/></revision>
  ///   <revision version="1.0" date="2020-03-11" author="VBWebprofi">Initial implementation</revision>
  /// </revisionHistory>
  /// <conceptualLink target="ed459d65-1b8b-4a49-ac69-018aae866bca" />
  [CodeVersion("1.1")]
  [DebuggerDisplay("{GetType().Name}; Order := {Order}, ForeGround := {ForeGroundColorString}, BackGround := {BackGroundColorString}, IsGNYE := {IsGNYE}, Id := {Id}")]
  [DatabaseConnectorBase.DatabaseTable("TL_WP_COLORS",
                                       ColumnPrefix = "WPCL_")]
  public partial class WpColor :
    ObjectBase<WpColor>
  {
    #region Construction/Destruction

    /// <summary>
    /// Constructor
    /// </summary>
    /// <param name="obj_Connector_p">Related connector instance</param>
    /// <revisionHistory>
    ///   <revision version="1.0" date="2020-03-11" author="VBWebprofi">Initial implementation</revision>
    /// </revisionHistory>
    protected WpColor(IConnector obj_Connector_p) :
      // Implicit parameter check
      base(obj_Connector_p)
    {
      // Nothing to do
    }

    #endregion
  ...
  }

The link to the conceptual topic will be placed in the "Other Resources" section at the end of the API page.

[RobertvanderHulst]

Holger, Thanks, I will give this a try. Robert