Sharing XPorting documentation (after Chris session of March 25)

[ic2]

I just watched the recording of the again very interesting and useful session about porting a VO program to X#.

The suggestion around 55:00 was to share what was learned during the conversion.

What we did is: every error we got is documented as follows:

Problem:
Error XS9002 Parser: unexpected input 'IF
Solution: In this case it was simply caused because a comment after the closing ENDIF was without //

Often the documentation on the compiler error shows nothing.

Would it be an idea that Robert/Chris define a kind of common format, e.g. like:

- Error message
- Cause
- Some sample code (before & after fixing)

and invite a few users who have done more or less the same as we did to send the documentation, sorted by error number, and in English, to you?

Then add this to the help so users can directly see the suggestion from the error. And it doesn't hurt if one error has multiple explanations or solutions (e.g. from multiple users). Apart from our own documentations which also contains some "doubles" (as I've recorded the YouTube session and paused it every time to write the same type of documentation from Chris' session as I did for our own conversion, some errors are now in twice).

Obviously, I volunteer to deliver our documentation, if you want it, after you define a common format.

It may be good that one of you quickly review and add it in your help file, but if you don't have time I am also willing to do the latter. Even when my (or sent in documentation from others) is not completely correct, it is better than nothing in the help file, as now is often the case, I think.

Dick

[wriedmann]

Hi Dick,
I would propose to add such a capitle to the wiki, so everyone that is interested can contribute.
Wolfgang

[robert]

Dick,

We can certainly use some help here and get some examples for error messages.

Like was said in the session: most of the error messages are Roslyn error messages. We have already copied the descriptions from the C# online documentation (but have deleted the C# examples of course). Unfortunately many of the errors are also not documented for C#.
In the case of undocumented errors we have generated the help pages and added the error message as description.

One of the problems that you will find when you document errors is that some errors may be caused by several causes.
For example error 9002 is a generic Parser error that is used when the parser finds an unexpected token. And as you can imagine: unexpected tokens can appear everywhere in your code.
We will create a template to help creating uniform descriptions.

Robert

[wriedmann]

Hi Robert,
personally I would think that the error documentation should not be done by your team - you are more than busy implementing new features.
And some errors can have very different causes, so a user driven documentation would be the best.
But if you can give us a template how errors can be documented - that would be helpful.
Or maybe it could be an idea to build an online database of errors and the relative solutions.
Wolfgang

[VR]

I personally like the approach of the docs.microsoft.com site. Every page has an "Edit" button. This button opens the corresponding source code of the page (written in markdown) on github. Everybody can commit changes and then a generator rebuilds the html (probably using github actions). I'm not sure, but I think, this is the generator that builds the page.

[robert]

Volkmar,
I like that too, but unfortunately that will not work for us. We are generating the documentation with Help and Manual (such as the description of the runtime errors and command line options) and Sandcastle (the documentation of the runtime functions, classes and methods). These tools do not allow to pick up docs like that from the website.
If someone wants to help and convert all our docs to a format like what Microsoft uses and has a system to extract XML comments into a help file (and process it to make sure that FUNCTIONS are documented as FUNCTION and not as a STATIC METHOD) then we would welcome that help.
For now I would like to stay with the system that we have.
I'll prepare a template for documenting error messages over the Easter weekend.

For the next build we have also added some extra help pages that group functions and classes "per category" in our runtime documentation. We could use some help from a XML guru to lookup the description from each function from XML files that we already have. For now that documentation looks like this:

Categories list:

Categories.png (10.03 KiB) Viewed 585 times

One category:

ArrayFunctions.png (34.11 KiB) Viewed 585 times

The area marked in Read needs to be read with a smart XPath query.
The links on the page go directly to a function, or to the page with the various overloads of a function.

And we could also use some help adding examples or cleaning up the examples in the runtime documentation.
This is all stored in XML files together with the source code of the runtime.


Robert

[VR]

Robert,

I agree, this task is certainly not trivial and there are alot of other things with higher priority. Just for the sake of completion: As I understand it, DocFx also uses xmlhelp data from the source code in addition to the markdown files. So at least in theory, you should be able to replace sandcastle with docfx. And Help and Manuals stores it's data as xml, so at least a conversion would be possible. This might be an interesting job for a summer intern.

Volkmar

[robert]

Volkmar,

I looked at DocFx. It can indeed create help from XML comments.
However we have added custom code to Sandcastle to "post process" the generated help so our functions look like functions in the documentation. And we are also replacing the internal types like __Usual with the USUAL keyword.

I am sure that with a lot of work this would also be possible for DocFx. But this work has already been done (mostly by my son Rolf) for Sandcastle. And I hate to do this all over again.
And what I did not see is how DocFx can create CHM files.

Robert