Help File/Documentation Issues. (Discussion Only)

[Skysnake]

SQLite again

for download https://www.autoitscript.com/autoit3/pkgmgr/sqlite/

Help File page: https://www.autoitscript.com/autoit3/docs/libfunctions/_SQLite_Startup.htm

The page states " The SQLite files can be downloaded from " ... Is it made sufficiently clear that this is an additional download?  

I could not find a general "AutoIt and SQLite" intro page / paragraph in the documentation? Even just a brief Intro, along the lines that there are powerful AutoIt functions that support SQLite, that it should be downloaded separately... ? This intro could even be included in the description of the _SQLite_Startup.htm page.

Skysnake

[Skysnake]

SQLite again...

SQLITE_OPEN_READONLY

from https://www.sqlite.org/c3ref/c_open_autoproxy.html

SQLite.au3 Line 62

Global Const $SQLITE_OPEN_READONLY = 0x01 ; /* Database opened as read-only */

Exists in the SQLite.au3, but is not mentioned in the Help File.

 

[BrewManNH]

There are a LOT of SQLite variables not mentioned in the help file, many are return codes, and some that are used for other things, you can't list every available variable used in a function in the help file. It would make the help file very difficult to maintain.

Look at any of the *Constants.au3 files and you'll see what I'm talking about as relates to undocumented variables.

[jchd]

I agree that isn't useful. Not only there is a large number of constants that are undocumented explicitely in the help but in this instance there are very few use for RO DB. Also users serious enough to play with such parameter is supposed to know how to read the UDF and see how things work, contrary to languages where libraries are opaque.

Since SQLite is serverless and given that any user (malvolent or not) who has access to the DB file can do whatever she wants with the content, there is not much that SQLite can do to protect against unwanted DB writes or even destruction by overwriting garbage. See my answer about how this can be somehow overcome, using the access rights extension and authorizers.

[Skysnake]

I will submit to your superior knowledge.

 

[orbs]

suggestion: add the below to the help for Run():

Run() may fail in any of the following scenarios:
- on 64-bit OS: the executable you attempt to run is 64-bit, but your script is running as 32-bit.
- on Windows Vista+ with UAC enabled: the executable requies elevated admin rights, but your script is not elevated.
- the executable is disallowed by software restriction policy.
although running these scenarios manually (i.e. double-click the executable) produces a relevant notice to the end user (UAC prompt or system message box), when using Run() these indications are suppressed.

(note: i use the "may" phrase for politeness only. "may fail" should read "always fails".)

also, there is a mix and match in the Remarks sections of Run(), RunWait(), RunAs() and RunAsWait(). common remarks include the usage of @ComSpec and I/O streams - these are either inadequately omitted or needlessly redescribed in the help for said functions. i suggest that common remarks (including the suggested) are described only for Run(), and a notice is placed in the Remarks sections of RunWait(), RunAs(), and RunAsWait() instructing the user to review the Remarks section for Run().

 

[AdamUL]

To allow a 32-bit process to run a 64-bit process, please add the following to the top of your script.  

#include <WinAPIFiles.au3>
_WinAPI_Wow64EnableWow64FsRedirection(False)

You will then not have an issue with any of the "Run" commands not running 64-bit processes.  

 

Adam

[BrewManNH]

You could add something along the same lines to most functions, and they'd still be more than what you really need in the help file. Checking to see if Run failed should tell the user that it failed, why it failed isn't part of the functions purpose.

There are a hundred other reasons that Run may (will) fail that aren't in your list, such as misspelling the command to run, or not including the full path. You can't possibly hope to include every reason why Run fails in a help file.

[orbs]

the help file is intended to provide help. if possible, it should help the user troubleshooting a failing function call for scenarios in which normal troubleshooting methods (like syntax check, file existence, manual launch etc.) do not reveal the cause of the failure.

indeed there may be many causes for Run() failing, but i'm talking about the ones that are not revealed by normal troubleshooting: the 32-bit/64-bit issue and the elevation issue. as for the SRP issue, i stand corrected - it should not be added, since it's easily revealed by trying to manually launch the executable.

i stumbled upon these issues in a recent project, involving kind of a launcher function. i started testing the launcher on random files, and had to spend some time discovering the causes which i suggest be added to the help file in order to spare other users from wasting their time.

 

[BrewManNH]

The help file isn't meant as a tutorial, and shouldn't be inflated to be one. It tells you how to use the functions, what they do, what you get when they succeed and when they fail. Beyond that it's up to the programmer to figure out what might go wrong, and write your code accordingly. In the specific case of the Run function you're told when it fails, YOU should know how to figure out why it failed or take the time to learn why what you wrote didn't work as intended. You're not going to find it in the help file so learn about what you're doing before trying to do it.

Programming isn't about having your hand held all along the way, it's about learning what the command set available does and if you can't do that then don't be a programmer (even a sometimes one).

[argumentum]

in regards to _WinAPI_SetProcessAffinityMask() , there is a remark saying: " For example, if you pass a mask of 0x05, processors 1 and 3 are allowed to run. " but CPU count starts at zero, not one. So I guess change it to "the 1st and 3th logical processors" or "processors 0 and 2" ??
This came to mind while reviewing https://www.autoitscript.com/forum/topic/184096-authread-multi-thread-emulation-forking-for-autoit/?do=findComment&comment=1322347 and my example did not match the referance I was giving to TaskManager.

What you think ?, should it be changed ?

[BrewManNH]

In Microsoft's world, the affinity mask starts at 1 and counts up, it's got nothing to do with CPU numbering but assigning a bit position to a CPU.

[argumentum]

2 minutes ago, BrewManNH said:

affinity mask starts at 1

yes, the mask starts at 1. A bitwise selection needs to start with at first position but the CPU itself is called 0.  So the presence of mask 1 selects CPU 0 and mask 3 selects CPU 2.

30 minutes ago, BrewManNH said:

it's got nothing to do with CPU numbering

Well, it does, but do as you see fit. I'm just pointing it out for the betterment of the help file. I hope you see my point kindly.

[orbs]

DriveGetFileSystem can detect ReFS (returns the string "ReFS"), but that is not mentioned in the help file, and there is no constant declared for it in AutoItConstants.au3 like the rest of the filesystem types. i think it should be added.

[Skysnake]

Helpfile error

::/html/libfunctions/_WinAPI_CreateANDBitMap.htm

My Helpfile version 3.3.14.0

Thx

Skysnake

 

[Skysnake]

Small typo

::/html/functions/IniRead.htm

under Remarks

wise if you want a hwnd to be a ptr, theN use Ptr() or HWnd().

........................................^

In addition, could the contents of post #5 from this thread perhaps be included as a general example and discussion on INI files? 

AND, with post #4 fromthis thread 

 

Should there perhaps be a note in the HelpFile that INI's should be considered redundant and users encouraged to rather use XML?

Edited June 9, 2017 by Skysnake

[mLipok]

Today I ask about _FTP_Connect() here:

Now I'm thinking about adding:
 

Quote

If $iPassive is set to 1 then $iFlags always use $INTERNET_FLAG_PASSIVE combined with user's setting for $iFlag.

To Remarks in documentation for _FTP_Connect.

Please comment - even on the correct use of English.

 

Edited November 1, 2017 by mLipok

[BrewManNH]

6 hours ago, mLipok said:

If $iPassive is set to 1 then $iFlags always use $INTERNET_FLAG_PASSIVE combined with user's setting for $iFlag.

If $iPassive is set to 1, then the special flag $INTERNET_FLAG_PASSIVE is automatically combined with the user's $iFlag parameter.

Maybe something like that?

[mLipok]

For me sounds ok. 

 

[Skysnake]

Inputbox

::/html/functions/InputBox.htm

1.

If your script is going to use an inputbox you must include the pragma directive "#pragma compile(inputboxres, true)"

Is this still necessary? Important?

 

2.

Can we please have extended functionality for input boxes such as eg the "modal" switch for msg boxes ? Forcing top most etc?