#Requires in downloaded examples

Share your ideas as to how the documentation can be improved.
lexikos
Posts: 9560
Joined: 30 Sep 2013, 04:07
Contact:

#Requires in downloaded examples

Post by lexikos » 17 Sep 2022, 19:38

Would it make sense for the download button on documentation code samples to automatically insert #Requires at the top of the file?

This would make running examples easier if AutoHotkey v2 and v1 are both installed.

User avatar
Ragnar
Posts: 611
Joined: 30 Sep 2013, 15:25

Re: #Requires in downloaded examples

Post by Ragnar » 18 Sep 2022, 03:06

For the v1 docs, this would cause problems for those using versions prior to 1.1.33.00 which do not support #Requires.

For the v2 docs, I don't see any concerns.

lexikos
Posts: 9560
Joined: 30 Sep 2013, 04:07
Contact:

Re: #Requires in downloaded examples

Post by lexikos » 18 Sep 2022, 20:57

People are using a version more than 2 years old, but referring to the latest online documentation...?

User avatar
Ragnar
Posts: 611
Joined: 30 Sep 2013, 15:25

Re: #Requires in downloaded examples

Post by Ragnar » 19 Sep 2022, 02:46

Statistically difficult to determine, but in my experience such people do exist. Especially those who are forced to use older versions, such as in companies. Of course, they could also consult the CHM, but that is not always guaranteed.

On the other hand, most will probably understand that they just need to remove the #Requires line to make the script work, or won't even be confronted with it because they just copy-pasted the example. To avoid confusion, a short comment could be put next to #Requires and a note could be added in Using the Program regarding this.

All in all, I have nothing against this. I just wanted to point out the problems.

User avatar
Ragnar
Posts: 611
Joined: 30 Sep 2013, 15:25

Re: #Requires in downloaded examples

Post by Ragnar » 28 Sep 2022, 10:01

I tried to implement this, but I noticed negatively that I can't just use #Requires AutoHotkey v1 for v1.1 scripts or #Requires AutoHotkey v2 for v2.0 pre-release scripts. Much too restrictive in my opinion to just distinguish between v1 and v2. It would be more helpful if this would be treated as #Requires AutoHotkey v1* or #Requires AutoHotkey v2* or the asterisk would be supported at least.

Currently, the values v1 and v2 are available for the docs. These would first have to be changed to v1.1 and v2.0- for #Requires for everything to work. If AHK v2 is out of beta status at some point, v2.0- would need to be changed to v2. If AHK v2.1 is released (hypothetically), it would have to be changed to v2.1, and so on. So this needs to be changed manually each time. If it were more flexible as described above, this would lead to less maintenance work; in this case, maintenance work means manual change and not forgetting to make the change.

lexikos
Posts: 9560
Joined: 30 Sep 2013, 04:07
Contact:

Re: #Requires in downloaded examples

Post by lexikos » 28 Sep 2022, 21:13

Just distinguishing between v1 and v2 is not "restrictive" enough. Once v2.1-alpha.1 is released, a user may have v2.0 set as the preferred version but still be able to run scripts with #Requires AutoHotkey v2.1-alpha.1 if that version is installed.

A "minor" release such as v2.1 would introduce new features. Example code may therefore literally require v2.1, and fail to work on v2.0. If the examples are to include #Requires at all, it should be specific (even if it is using the release version and some examples could potentially run on earlier versions).

Bug fix releases should never affect compatibility, so that component could be omitted.

Pre-release versions may have unique requirements, but currently #Requires doesn't have the capability to specify an exact match or upper bound.

The documentation already includes the version number, and there is no maintenance cost because it is updated automatically by the release script. If you define a variable somewhere with the version, I can change the release script to update it.

If for any reason you do not want to implement this idea, I am fine with that.

User avatar
Ragnar
Posts: 611
Joined: 30 Sep 2013, 15:25

Re: #Requires in downloaded examples

Post by Ragnar » 29 Sep 2022, 04:13

Well, in this case it doesn't have to be so precise. My intention is that #Requires should only serve as a hint for the Launcher whether it is a v1 or v2 script. This saves the user from having to choose the correct version when launching an ambiguous script. Everything that happens after that doesn't matter in this case. This is the same as having different file extensions for both versions, e.g. .ahk vs .ah2.

Tensai
Posts: 29
Joined: 12 Dec 2019, 14:15

Re: #Requires in downloaded examples

Post by Tensai » 29 Sep 2022, 16:08

#Requires is there for a reason and should feel required to use. I feel it'd be best practice for anyone learning through the examples to get in the habit of including it.
I agree with Ragnar in that it can be placed with comment clarification and recommendation, much like the v1 default template directives. If #Requires is the very first line they and the interpreter read, it should be clear their version is mismatched upon error.

lexikos
Posts: 9560
Joined: 30 Sep 2013, 04:07
Contact:

Re: #Requires in downloaded examples

Post by lexikos » 29 Sep 2022, 21:15

Ragnar wrote:
29 Sep 2022, 04:13
Well, in this case it doesn't have to be so precise. My intention is that #Requires should only serve as a hint for the Launcher whether it is a v1 or v2 script.
Since you seem to be contradicting what I explained in my previous post without directly addressing it, I feel that you may have missed my point. If you actually disagree, would you care to explain why?

The purpose of the launcher is to have the script run in the appropriate version (potentially even downloading and installing it), instead of merely aborting execution of the script (or showing an arbitrary syntax error) if the requirement isn't met. If the requirement is imprecise, the script may fail to launch in the correct version. The launcher and #Requires directive aren't merely for v1 vs. v2, but for all future versions.

Suppose that v2.1-alpha.1 adds the capability to assign var := unset. Any script that uses this would not run with v2.0. If the user has v2.0 (stable version) set as their default for v2 scripts, any examples they "download" from the v2.1-alpha.1 documentation that utilize this would fail to work without the appropriate #Requires directive; i.e. #Requires AutoHotkey v2.1-alpha.1.
This saves the user from having to choose the correct version when launching an ambiguous script.
I assume "an ambiguous script" means any script that syntax detection fails to identify the version for. As an example, it is likely that var := unset will remain as an ambiguous case, hypothetically valid in v1 and v2.1. If the user has v2.0 (stable) set as default, #Requires AutoHotkey v2* would fail to achieve the stated goal.
Everything that happens after that doesn't matter in this case.
I don't understand what bearing this comment has on the topic. Ensuring the script launches in the correct version is the concern, not what happens after and only if it launches in the correct version.



Perhaps all of the downloadable code blocks should be tagged with the required version, in a manner similar to the [v1.x.y+] tags in the v1 documentation - preferably in a non-intrusive way (e.g. displayed in the frame of the code block), that the download code can translate to a #Requires directive. A reader can see the requirement of a given example at a glance, and the downloaded code will clearly indicate for the launcher (and reader) what version it requires.

Initially (after release) all code would require v2.0, and only new additions for feature releases would need to be tagged.

Post Reply

Return to “Suggestions on Documentation Improvements”