Merging Sandcastle created help and Manually written help

Please post all questions and comments regarding Help & Manual 7 here.

Moderators: Alexander Halser, Tim Green

Merging Sandcastle created help and Manually written help

Unread postby Robert van der Hulst » Fri Aug 09, 2019 10:42 am

H&M has added support to create help files using Sandcastle.
I have tried to use this but I am a bit disappointed about the functionality:

1) This seems to be a one time only process that is part of the New Project wizard: you run the tool and create a H&M file.
If your DLL files have updated you will have to run the tool again and produce a new H&M file.
I would expect that the H&M file contains the info about the DLL files that it was created from and that when you run the Build process to produce documentation that it would reread the DLL files and update the H&M file, but it does not seem to work like that.

2) Sandcastle has a couple of different presentation styles. The H&M 'New Project' wizard does not allow you to select a presentation style or set any of the other options that control the behavior of Sandcastle.

3) The sandcastle runtime files that are included are quite old (2012). Sandcastle is still being maintained and there are updates in Github at least twice a year. These updates contain new Framework versions as well as new or updated presentation styles.

As a result we have to run Sandcastle as a stand alone tool to produce the documentation and control what gets generated.
Unfortunately that causes the problem that we can't easily create links between topics created by sandcastle and topics written manually with H&M.
This will work as long as we when we include the CHM file in the TOC, but when we produce output for our website or Visual Studio help output then these links do not work.

Am I overlooking something ?

Robert
User avatar
Robert van der Hulst
 
Posts: 37
Joined: Thu Jul 25, 2002 10:12 am

Re: Merging Sandcastle created help and Manually written hel

Unread postby Tim Green » Fri Aug 09, 2019 5:05 pm

Hi Robert,

Updates are fully supported, you just open the original project created from your Sandcastle sources, select Import in the File menu instead of New Project and then select the Sandcastle option again. This is from the documentation on Sandcastle import:

You can also update your source code documentation to the Help+Manual project you created from an earlier version.

Open the Help+Manual project and select Import in the File menu instead of New Project. All the other steps are the same as described above. New topics chapters will be added to the end of the existing TOC. Updates to existing topics and chapters will be handled depending on the conflict management settings you configure for "changed topics". If you opt to overwrite the existing topics the earlier versions will be replaced.


https://helpandmanual.com/help/hm_worki ... astle.html
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
User avatar
Tim Green
Site Admin
 
Posts: 20889
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany

Re: Merging Sandcastle created help and Manually written hel

Unread postby Robert van der Hulst » Fri Aug 09, 2019 5:38 pm

Tim,
Thanks, I had totally missed that.

What about:
- choosing a presentation style and setting the other parameters
- updating Sandcastle to a recent version ?

Robert
User avatar
Robert van der Hulst
 
Posts: 37
Joined: Thu Jul 25, 2002 10:12 am

Re: Merging Sandcastle created help and Manually written hel

Unread postby Tim Green » Fri Aug 09, 2019 6:00 pm

Robert van der Hulst wrote:- choosing a presentation style and setting the other parameters

The style generated from the Sandcastle source is currently preset. However, after importing to Help+Manual you can edit the styles in the project stylesheet and do any other editing you like.

- updating Sandcastle to a recent version ?

Since Sandcastle has now been discontinued by Microsoft I don't think there is a more recent version, at least not any with any meaningful additions over what is there now. I will check with our developers but to the best of my knowledge nothing more is happening with Sandcastle at Microsoft. :?
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
User avatar
Tim Green
Site Admin
 
Posts: 20889
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany

Re: Merging Sandcastle created help and Manually written hel

Unread postby Robert van der Hulst » Fri Aug 09, 2019 9:36 pm

Tim,

Sandcastle is now on Github (https://github.com/EWSoftware/SHFB) and is still being developed.
W.r.t. the presentation styles, there are some things that we can do with SHFB (like adding syntax in our own development language) that require a more recent version of SHFB and a presentation style that is not included in your Sandcastle folder.
I am willing to dive into this myself if you can tell me how H&M is calling Sandcastle. Maybe I can intercept that call and feed Sandcastle our settings ?

Robert
User avatar
Robert van der Hulst
 
Posts: 37
Joined: Thu Jul 25, 2002 10:12 am

Re: Merging Sandcastle created help and Manually written hel

Unread postby Tim Green » Sat Aug 10, 2019 5:37 am

Hi Robert,

What is on Github is not Sandcastle, unfortunately. It is Sandcastle Help File Builder, which is basically doing exactly the same thing as Help+Manual: it is taking the Sandcastle output, redirecting it and formatting it. Help+Manual can't and won't deal with that, because what SHFB produces is already pre-digested Sandcastle. It's fine to use either SHFB or HM, but not both. 8)
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
User avatar
Tim Green
Site Admin
 
Posts: 20889
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany

Re: Merging Sandcastle created help and Manually written hel

Unread postby Robert van der Hulst » Sat Aug 10, 2019 11:26 am

Tim,

Ok, that is clear and unfortunate.
SHFB allows us to add our own syntax component. Since we are creating a development language it is very important for us to also show examples in our own language, such as you can see at https://www.xsharp.info/runtimehelp/htm ... VarPut.htm
Btw: we are also "post processing" the SHFB generated help pages, because our language is function based and the compiler generates a static method of a compiler generated static class from the function in the source code. We could probably also do this in the presentation template but post processing was easier.

Right now we are producing a separate help file for list of classes and functions and for the "manually written" help (https://www.xsharp.info/help/index.html).
In the CHM format we are embedding the generated chm version of the help in the TOC.
Something similar is also done for the VS help format.
It would be nice if we could also embed the generated docs in the TOC on the web.

And by including the sandcastle docs in our written docs it will also be much easier to add links to generated topics in the hand written documentation.
What would you recommend ? Is there a way we can control the output that gets generated by Sandcastle inside H&M ?

Robert
User avatar
Robert van der Hulst
 
Posts: 37
Joined: Thu Jul 25, 2002 10:12 am

Re: Merging Sandcastle created help and Manually written hel

Unread postby Tim Green » Mon Aug 12, 2019 8:19 am

Hi Robert,

It would be nice if we could also embed the generated docs in the TOC on the web.

You can't do that after the fact in WebHelp for a large number of technical reasons (search index, TOC structure, many other issues).

What would you recommend ? Is there a way we can control the output that gets generated by Sandcastle inside H&M ?


However, you also don't need to merge WebHelp at runtime (which would be a nightmare on so many levels) because you can create modular projects in Help+Manual. You just insert a reference to the project you want to merge in your TOC, and when you publish the project to WebHelp or any other format the result is just the same as if you were publishing a single large project. You get a merged TOC, and everything behaves as a single integrated WebHelp, because it IS a single integrated WebHelp. However, the source projects remain completely independent and can still be edited and published separately. You just need to make sure that there are no duplicate topic IDs in the projects that you are merging, because then you get conflicts. See the chapter on modular help systems for details:

https://helpandmanual.com/help/hm_advanced_modular.html
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
User avatar
Tim Green
Site Admin
 
Posts: 20889
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany


Return to Help & Manual 7 Forum

Who is online

Users browsing this forum: No registered users and 4 guests

cron