Using Visual Studio Code for editing WGML documentation

[pchapin]

I'm experimenting with using Visual Studio Code to edit the WGML documentation. I'm preparing a pull request containing a docs/doc/.vscode folder with sharable settings for certain relevant VS Code extensions. I will also include a docs/doc/README.md file that explains how to set up the environment.

I'm using the configuration experimentally to edit the OWSTL documentation. In particular, I'm rewrapping all paragraph blocks (to the degree WGML rules allow) to a tidy 80-column width. I'm also discovering (and fixing) numerous (i.e., dozens) of spelling errors. The environment's ability to find so many spelling errors so easily is encouraging.

In the future, I might look into creating a proper VS Code extension for WGML, perhaps by forking the troff extension. This would provide intelligent syntax highlighting for WGML files, making them much easier to read. I would also like to define a task definition for running the WGML tools from inside VS Code as a convenient way to check the buildability of the documents.

I'm visualizing this project's scope to extend over docs/doc and not just docs/doc/owstl in anticipation of other documentation edits I might want to make in the future. Usually, I advocate using Open Watcom tools when developing Open Watcom to exercise (and hence test) the tools we offer. However, it seems silly to deny ourselves access to the powerful tools available today for the sake of some abstract concept of purity. Considering how limited the project's resources are, using the best tools at every stage will be helpful. However, I'm posting this discussion because I see this as a potentially controversial direction, and I wanted to let the community weigh in on it before I submit my PR.

[jmalak]

I considered abandoning WGML altogether and converting the documentation to some more up-to-date format due to problems with the WGML tool (DOS and OS/2 binaries only).
One other reason is not visible, but the use of WGML with OW is limited to the US ASCII character set only.
I don't know how the WGML tool supports character sets, probably only single-byte and what limitations there are, I haven't tested it.
Nowadays we should use some form of UNICODE, probably the best encoding would be UTF-8. But processing such text with a WGML script probably won't work.
I solved a similar problem with Japanese texts in the GUI and there I switched to UTF-8 sources and it converts to the appropriate code page for each platform.
I think that further continuation with WGML only makes sense if we get usable source code and make the appropriate modifications to use UTF-8 encoding.
I know that WGML source code development still continue but it is completely hidden from the public and there are no interest to move it to some public git repository. It is hold in perforce server without public access.

[jmalak]

Yes, now it is used as it is, because the efort to migrate to other systems is relatively high.
It is reason why I changed infrastucture to use only dosbox with DOS version of WGML and fix it.
I still hoping that we get some sources from WGML development to deploy it to OW 2.0 because WGML development is based on OW 1.9. We use more standardized source code tree as much as portable to follow C99 standard and POSIX standard and as last OW specific, but OW 1.9 has different priority.
We will see what bring the future. Now I don't plan to remove it, but I don't want invest to much time for it.
If you feel that it has sense go forward, I am not against.

[jmalak]

By the way, are we still bound by 8.3 filename limitations in the OW source tree? I mention it because my proposed folder name, owstl-ltx, is nine characters long. Should I shorten it?

I am still holding this compatibility due to support of DOS build system.

[pchapin]

Okay, that sounds good. I did make some changes to the WGML sources of the OWSTL documentation that fixed numerous typos, spelling mistakes, and grammar errors. I also cleaned up the formatting. I'll create a PR for that because it probably should be incorporated into the master branch regardless of what ultimately happens with the documentation.

After that, I'll start experimenting with LaTeX in a separate folder. Do you want PRs for that, or should I just commit directly to the master branch? It will be highly isolated in its own sandbox, so it shouldn't interfere with anything.

[pchapin]

By the way, are we still bound by 8.3 filename limitations in the OW source tree? I mention it because my proposed folder name, owstl-ltx, is nine characters long. Should I shorten it?

I am still holding this compatibility due to support of DOS build system.

Understood! Thanks.

[jmalak]

You can submit it directly, there is no problem, you can fix it or revert change back in case that it broken regular build. Sometimes I submit changes as PR if I want to test build on various platforms. But it is related to programs code not for documentation.