Powershell help writer is not parsing the xml file correctly

Support for all customers who have purchased a PowerShell HelpWriter product license. This forum does not offer a response time guarantee.
Forum rules
DO NOT POST SUBSCRIPTION NUMBERS, LICENSE KEYS OR ANY OTHER LICENSING INFORMATION IN THIS FORUM.
Only the original author and our tech personnel can reply to a topic that is created in this forum. If you find a topic that relates to an issue you are having, please create a new topic and reference the other in your post.

Any code longer than three lines should be added as code using the 'Select Code' dropdown menu or attached as a file.
User avatar
whiggs2
Posts: 37
Joined: Sat Sep 23, 2017 11:59 pm

Powershell help writer is not parsing the xml file correctly

Post by whiggs2 » Fri Jan 04, 2019 12:01 pm

To help you better we need some information from you.

*** Please fill in the fields below. If you leave fields empty or specify 'latest' rather than the actual version your answer will be delayed as we will be forced to ask you for this information. ***

Product, version and build:
PowerShell HelpWriter 2019
Version 2.3.42
32 or 64 bit version of product:
64 bit
Operating system: Windows 10 1809
32 or 64 bit OS:
64 bit

*** Please add details and screenshots as needed below. ***
It would appear that Powershell help writer is not parsing the examples which are added to the project correctly:
Image

What I would expect this section to look like:
Image


DO NOT POST SUBSCRIPTIONS, KEYS OR ANY OTHER LICENSING INFORMATION IN THIS FORUM

User avatar
davidc
Posts: 5646
Joined: Thu Aug 18, 2011 4:56 am

Re: Powershell help writer is not parsing the xml file correctly

Post by davidc » Fri Jan 04, 2019 12:09 pm

Was the original help an existing xml help file or did it come from comment-based help?

If you can, please zip and upload the project here:

https://sapien.com/support/upload

This will allow us to take a closer look.
David
SAPIEN Technologies, Inc.

User avatar
whiggs2
Posts: 37
Joined: Sat Sep 23, 2017 11:59 pm

Re: Powershell help writer is not parsing the xml file correctly

Post by whiggs2 » Thu Jan 10, 2019 7:50 pm

So what I have done is I have created two separate "help" projects using the same module as a base. One will use Sapien powershell help writer to import the module, modify the help content of the functions, and generate the external help document. The external help file generated using this process has consistently just not worked, as attempting to view the help information for functions will simply display what I assume to be the default, bare-bones help content rather than what is actually present:

Image

The other project will use platyps, a powershell module which is essentially the working, free alternative to Sapien powershell help writer to import the module, modify the help content of the functions, and generate the external help document. As mentioned previously, I have had far more success using platyps than I have using Sapien powershell help writer:

Image

I am doing it this way for a few reasons. This way, you will get the help project, the module which was used to build it, the broken help file that it generates, and can compare the broken sapien help file to the working help file generated using platyps. This I would hope would make it easier to identify and quickly fix what is wrong with Sapien Powershell help writer. Another reason I am doing it this way is so that I can document here any....oddities....that I come across while trying to generate the external help file using Sapien powershell help writer, which I will start below:

***Oddities****

1. When I created the project fresh by importing the module to automatically generate the functions that would make up the help file, I noticed as I was going through the functions that at least one, as seen below, automatically had the name of the function populated in the "Synopsis" text box in Sapien powershell help writer:

Image

User avatar
davidc
Posts: 5646
Joined: Thu Aug 18, 2011 4:56 am

Re: Powershell help writer is not parsing the xml file correctly

Post by davidc » Fri Jan 11, 2019 8:45 am

Just taking a quick look at the project, I found the following:

1. In the psm1 file, you include the language folder in the path. Instead, simply specify the name of the help file:

Code: Select all

<#
    .EXTERNALHELP PoshBox.psm1-Help.xml   
#>
PowerShell will handle the language path depending on the user's settings.

2. Examples:
a. Dashes in the title:
This is up to the author. You can add the dashes in the title of the example. Maybe we can include an option here to generate it.

b. The spacing between Examples:
This is up to the author as well. You can add extra lines at the end of the description to produce the spacing between examples. This is what Microsoft does for Get-Content’s examples.

3. Connect-Box examples:
In the first screenshot you show 3 examples for Connect-Box. But looking at the platy generated file, it also has only one example as well.

4. Oddities:
Cmdlet name in the synopsis:
PowerShell returns the syntax when there is no synopsis present. Since this cmdlet has no parameters, it got passed our filter.
David
SAPIEN Technologies, Inc.

User avatar
davidc
Posts: 5646
Joined: Thu Aug 18, 2011 4:56 am

Re: Powershell help writer is not parsing the xml file correctly

Post by davidc » Wed Jan 16, 2019 3:25 pm

The syntax in the synopsis issue should be resolved in the new PowerShell HelpWriter service release (v2.3.43).
David
SAPIEN Technologies, Inc.