Include documentation/highlighting for acetutil functions

[semkeijsper]

This project is great when it comes to including documentation for the functions that are documented.
However, there are many acetutil functions that can be used from lisp, that are not documented or highlighted.

I have found a small list of them on this archived site: https://www.afralisp.net/archive/lisp/acet-utils.htm
They are documented nowhere in official AutoCAD resources, yet they still work in AutoCAD 2023 today.

For example, one hugely useful function is (acet-str-replace), which allows you to use RegEXP(!!!) to modify strings. This is honestly such a huge feature that I can't believe it's not documented more clearly. Another useful thing is the ability to show and update a progressbar, which we use extensively in our LISP code, using (acet-ui-progress-init) and related functions.

I have found a file on the Autodesk Forum called acetutil.chm, which contains limited documentation:

It seems like it was made by this guy: JTB World

This file contains documentation for version 1.37, but AutoCAD says we are at version 1.38, as shown when running (acet-util-ver).
I first thought the difference wouldn't be too great, but the .chm file was made in the year 2000. And I already found some functions that do work in AutoCAD, but aren't documented in acetutil.chm, like (acet-str-space-trim) (which just trims spaces from strings).

Another huge list I found is located here, but it doesn't have clear documentation on what parameters it takes.

Can you please integrate documentation for these functions? They are very useful and gamechanging when performing simple operations, such as UI and string manipulation.

[JD-Howard]

I've had all the same problems and totally get it, but if Autodesk hasn't made this documentation yet, then I don't think they ever will. My suggestion is to look at the video from PR #138 about user-documentation and read about using the @Global flag in PR #202

Finally, just make your own file of ACET abstractions that do-nothing and document them. From there you can include the file in your project to get hover documentation. I would also suggest open-sourcing that file so others can use it/contribute.

Those user defined @Global marked functions are on my agenda to become auto-completion suggestions in the next release. However, that still won't solve the highlight issue. I have no good answers for that and I have a similar gripe about .net defined functions...

[ambrosl-adsk]

This project is great when it comes to including documentation for the functions that are documented. However, there are many acetutil functions that can be used from lisp, that are not documented or highlighted.

I have found a small list of them on this archived site: https://www.afralisp.net/archive/lisp/acet-utils.htm They are documented nowhere in official AutoCAD resources, yet they still work in AutoCAD 2023 today.

Thanks for pointing out that the acetutil.chm file is missing. Looks like the file was accidentally removed from the product and not made available online. I have noted to make this content available once again online through the AutoLISP Reference. Similar functions you mention related to string manipulation are available as part of the Visual LISP Extension, under different names. Functions for string replacement and the trimming of whitespace can be found here under the String-Handling Functions Reference (AutoLISP) topic.

[Semx11]

@JD-Howard thanks for your suggestions, I'll look into creating stubs for the acetutils with the global modifier so that it shows in the editor. I'll definitely open source it when I get around making it. Do you know if it's possible to also include the "Types" section in user generated documentation for @param's, similar to how official functions have that?

@ambrosl-adsk awesome to hear it will be made available online again! Hopefully it'll be up to date and include the new functions added in 1.38 :)

And thanks for the link, however I was already aware of the string handling functions built into 'vanilla' autolisp, but the huge difference here is that the (acet-str-replace) supports basic regex, such as [a-z]+. This does not work with
(vl-string-subst) as far as I know. I have been frustrated many times not being able to use Regex, so I'm very glad I found it now :)

[Semx11]

also, @JD-Howard, is it possible to make the acet- functions highlighted blue by the extension, even without documentation? if so, please point me to the file where to add that. I'll do that too when creating the stubs

[JD-Howard]

@Semx11
Kind of a hack, but you could find/customize your local AutoLispExt syntax file. Typically found here:
%UserProfile%\.vscode\extensions\autodesk.autolispext-1.6.0\extension\syntaxes\autolisp.tmLanguage.json

Unfortunately, types were too much of a floating target in Lisp and a purposefully omitted concept. However, you can do:

@param SomeArgName your long description about this argument; which can include information about the type.
       Note that you can also multi-line your descriptions if necessary. However your formatting will be removed.

Basically the @param will start a parameter name, the next contiguous set of printable characters is the param name and anything after that will be parsed as the description of that param until the comment ends or a new @something starts.

Edit: you might also try enhancing your documentation with basic markdown. like **Bold this**

As a more long term solution to the problem, AutoLispExt will probably have to implement the Semantic Token API. If we do that and load the user defined symbols for highlighting, then that file I suggested you make would automatically make them highlight.
https://code.visualstudio.com/api/language-extensions/semantic-highlight-guide

[Sen-real]

also, @JD-Howard, is it possible to make the acet- functions highlighted blue by the extension, even without documentation? if so, please point me to the file where to add that. I'll do that too when creating the stubs

Hi @Semx11 , I will make a PR to update the extension to get acet- functions highlighted. I'll do it soon.

[Semx11]

@JD-Howard thanks for the tips, I'll look into it tomorrow when I work again
@Sen-real thank you :)

just realized I'm logged in with a different account on my phone. sorry if that caused any confusion - I'm the same person as @semkeijsper haha

[Sen-real]

@Semx11 @semkeijsper
I just added a bunch of acet-* functions and constants into the extension, so that they can be highlighted and also listed in the auto-complete pop-up.

I only added functions which are documented in:

• acetutil.chm
• Autocad online help
• AfraLisp (the website you mentioned).

It will take a while to release a new version to VS Code market place, but you could have a try with the pre-release now:
https://github.com/Autodesk-AutoCAD/AutoLispExt/releases/tag/v1.6.1-b6ae1ada7805586f5accbbf17a28575dd77edaf1

If you would like to try with this pre-release version, the steps are:

1. Download the autolispext.vsix from that page
2. Uninstall AutoLispExt from VS Code
3. Restart VS Code
4. Install the downloaded autolispext.vsix file in VS Code, as shown below:
   

[semkeijsper]

@Sen-real it works great! thank you so much. If it's not too much to ask, could you please integrate 3 more UI functions? We use them frequently in our project - they are called:

• acet-ui-progress-init
• acet-ui-progress-safe
• acet-ui-progress-done

They are 'documented' here: https://www.cadforum.cz/en/qaID.asp?tip=5891
These functions are crucial to communicate to users the progress of long running tasks, allowing to initiate a progress bar with a text string and size, updating the status with safe, and dismissing it with done.

Hopefully the documentation for these functions will be available in acetutil.chm once it's put back online :)

[semkeijsper]

Small problem. I have tried adding user-defined documentation:

However, because the function is now marked blue, you cannot hover it with user-generated documentation:

It does work however with acet functions that are not yet in the library.

Maybe @JD-Howard knows what to do in this case?

[Sen-real]

@Sen-real it works great! thank you so much. If it's not too much to ask, could you please integrate 3 more UI functions? We use them frequently in our project - they are called:

• acet-ui-progress-init
• acet-ui-progress-safe
• acet-ui-progress-done

They are 'documented' here: https://www.cadforum.cz/en/qaID.asp?tip=5891 These functions are crucial to communicate to users the progress of long running tasks, allowing to initiate a progress bar with a text string and size, updating the status with safe, and dismissing it with done.

Hopefully the documentation for these functions will be available in acetutil.chm once it's put back online :)

Yes, they look so useful. They're now included in the following build:
https://github.com/Autodesk-AutoCAD/AutoLispExt/releases/tag/v1.6.1-d456a8ffa5be53a2d6b08b5f94ec9b9239456eb2

[JD-Howard]

@Sen-real
I would speculate that the new issues has to do with updating the alllispkeys.txt file. The JSON changes that actually do the highlighting aren't evaluated by our code directly. So, that txt is probably doing some "this is native" logic and kicking out the user definition. I remember there had to be some kind of a decision made about conflicting Native vs User symbols since literally everything can be redefined by the user and the prevailing thought was "users generally shouldn't do that" and we shouldn't try that hard to cover an edge case.

[Semx11]

@JD-Howard sounds logical enough yeah. maybe it's possible to check if, when native documentation isn't available, it'll use user defined docs? like a priority system

[ambrosl-adsk]

The documentation that was previously available in the CHM file for the Express Tools AutoLISP functions has been moved online and can be access from the AutoLISP Reference Guide now as part of the AutoCAD 2024 release. Only the functions that were previously documented are in this posted documentation set because they were fully tested for their individual use. All other functions are kind of use at your own risk.

https://help.autodesk.com/view/OARX/2024/ENU/?guid=GUID-66179117-AF23-441B-A990-3266FAF7EA38

[Semx11]

@ambrosl-adsk

Thank you so much! Hopefully more functions will be added later if they are stable, I believe there are quite some functions that are :)

@JD-Howard does this mean the plugin will pick up the docs for these functions then? as it looks at the online docs

[JD-Howard]

@Semx11 Not exactly,
There is an offline JSON blob representing the pieces of the online documentation that are relevant. I've had a long standing TODO for getting the blob creator migrated to some new format. My problem is that the scrapper really needs and interface. The existing C# version is an ugly cluster that was just a proof of concept and Sen wants it in some format backed by typescript. At some point, I intended to make a DCL visualizer and was thinking I could recycle that interface work to migrate the scrapper to typescript.

I'll see if I can get the existing C# one to account for the newly created documentation. If that documentation follows all the same standards existing documentation uses, then it won't be an issue. If it deviates in some meaningful way, then it won't be a simple task and may have to wait.

[ambrosl-adsk]

@Semx11 I see how this works... since there are only about 40ish new functions, I could add this manually and then work on something that will pull the content together in the future from the source files themselves.