Help File/Documentation Issues. (Discussion Only)

[guinness]

In FileCreateNTFSLink, should the options for the flag parameter be constants?

Currently it is this:

flag

[optional] this flag determines whether to overwrite link if they already exist.

Can be a combination of the following:

0 = (default) do not overwrite existing link

1 = overwrite existing link

I'm aware that $FC_OVERWRITE and $FC_NOOVERWRITE could be used but that's beside the point.

It's boolean so no it doesn't. If it was 1,2,3 then yes constants would need to be applied.

[jaberwacky]

I just want to make sure of something.  Should I start a trac ticket for an issue even if I'm not sure it could be an issue?  Or am I ok with discussing it here first?

[guinness]

You can discuss here if you want, but I can't guarantee I will read it. Especially if a long discussion ensues during that particular day.

So I would say post a ticket, because I can then PM you to discuss further if I don't understand. I'm also not going to jump down your throat if it's not a valid request, it's not in my nature! I appreciate the time and effort you guys put in to making the help file better.

If I do reject a ticket, don't take it personally, we're all here to make AutoIt better! -_0

[guinness]

Let me know if you don't like my decisions. Thanks.

[jaberwacky]

If I do reject a ticket, don't take it personally, we're all here to make AutoIt better! -_0

 Absolutely.  I understand the nature of the beast.  =)

Seriously.  Thanks for the reply and for the work you do on AutoIt.

One more thing.  Now that you're a develop.  If you or anybody else had a question about the helpfile and the answer to that question would come from looking into the source.  Do you have that authorization?

Edited August 21, 2013 by jaberwocky6669

[guinness]

 One more thing.  Now that you're a develop.  If you or anybody else had a question about the helpfile and the answer to that question would come from looking into the source.  Do you have that authorization?

No, as I don't work on the core code. But I have a means to ask those who do.

[mLipok]

 

 I appreciate the time and effort you guys put in to making the help file better.

Thank you.

In fact, it's the 3rd time when I started my review of the file HelpFile.

 

The first time was in 2006. Two years after I started using AutoIT and about the time when I signed up for the forum.

The second time was somewhere around 2010.

Now, in connection with such a major revision in BETA, so I started 3 review.

This time, however, I felt compelled to report everything that I had already wondered and worried.

I take it as my contribution to the general welfare of the community, which is also mine.

By the way, I learned a lot from you all.

 

we're all here to make AutoIt better! -_0

 

I'm glad you're such a good approach this.

 

If I do reject a ticket, don't take it personally,

No offense.

I just hope that you also do not have me too bad, the fact that I add comments to a closed ticket like this:

http://www.autoitscript.com/trac/autoit/ticket/2399

http://www.autoitscript.com/trac/autoit/ticket/2392

 

and that in some long time, in some cases, you answer again.

 

Let me know if you don't like my decisions. Thanks.

 

I think these are good ideas.

 

What's more on your statement I have a proposal:

I want to all new posts on the documentation, I'll report as TRAC ticket, even such as in the post # 10, # 11, # 18

 

I think that if the need arises, it is the right time, the ticket can be transferred to a new post on the forum for this thread, in order to initiate a broader discussion.

After the discussion will announce the result by closing the report, ie TRACK ticket.

 

I think people will be more interested in visiting TRACK timeline.

By the way, I would like to thank BrewManNH, AdmiralAlkex, and of course, Guinness's current response to my last tickets,

 

I think that is consistent with your statement:

 

So I would say post a ticket, because I can then PM you to discuss further if I don't understand. I'm also not going to jump down your throat if it's not a valid request, it's not in my nature!

 

 

[mLipok]

No, as I don't work on the core code. But I have a means to ask those who do.

Good to know.

[guinness]

I have all but one ticket remaining as I'm awaiting confirmation. I was worried moving to Trac wouldn't work, but I think it does as it stops the "waffling" and gets straight to the point of the problem -_0!

[mLipok]

What this mean "waffling"  ?? 

[FireFox]

to talk and talk again without something concrete

[guinness]

Yeah, it's just an expression and not to be offensive.

[mLipok]

I was worried moving to Trac wouldn't work, but I think it does as it stops the "waffling" and gets straight to the point of the problem -_0!

 

Well done.

I think now the situation is under control, because really, it was not before.

And that was the key issue.

[guinness]

Well if you and jaberwocky6669 are happy this way then so am I. Keep posting what you find!

[mLipok]

You can be sure that I will.

[AZJIO]

StatusbarGetText - 

[FireFox]

@AZJIO

Fixed everything except:

WinSetTrans

Sets the transparency of a window. (Windows 2000/XP or later)

the text in heading

Not needed as IIRC the compatibility with Windows 98 was removed.

 

Column easier to read than the string

Not necessary.

GUICtrlUpdate...() - isn't the link, as on other pages

What do you mean?

 

GUICtrlSetColor

Checkbox, Radio, Group or Progress controls cannot be painted if the "Windows XP/Vista style" is used.

Lack Combo

Same question. Edited August 23, 2013 by FireFox

[Ascend4nt]

While looking at an old piece of code which relied on AutoIt's behavior in regards to numerical computations involving booleans, I noticed the Help file has a really crap example for True/False keyword:

#include <Constants.au3>

Local $fBoolean = False
If Not $fBoolean = True Then MsgBox($MB_SYSTEMMODAL, "Bool comparison", "OK") ; If $fBoolean is NOT equal to True then display the messagebox

 

The use of NOT there is a poor example, and I'd also argue that comparing anything to True or False is bad practice.  Normally it should be 'If $fBool Then' or 'If Not $fBool Then'.  Maybe such tests might not be clear for some newcomers but at least it doesn't promote bad programming practice as the above code fragment does. (plus whatever NOT is testing should be in parentheses).

Also, since I had looked at the Help file to see what the current stance is on using True/False in expressions, I had to double-check what the difference between expressions and statements was since I don't really use the terms on a daily basis (and I've probably made the mistake of saying one was the other at some point).  Perhaps this wording can confuse others too?

These keywords should not be used in expressions as AutoIt will not detect this 'misuse' and the results will be unpredictable.

 

An example of misuse would be doing math with a bool. ($x = $bBool * 5)

Also, I'm wondering - with "bool" arguments in DLLCall's, I've relied on True/False being converted to the expected 1 or 0 (Windows convention) - is this something I should or should not rely on?

Thanks!

[Jon]

Also, I'm wondering - with "bool" arguments in DLLCall's, I've relied on True/False being converted to the expected 1 or 0 (Windows convention) - is this something I should or should not rely on?

Thanks!

 

We evaluate true to 1 and false to 0 internally, so that should be fine.

[mLipok]

 

I have a new proposal for an interesting observation and concepts in a global scale, ie the whole HelpFile.

 

First:

Please look at the documentation for the function _ArrayDelete

Please focus on the yellow box constructor

# include <Array.au3>
_ArrayDelete (ByRef $ avArray, $ iElement)

 

Second:

Please look at the documentation for the function StringCompare

Please focus on the yellow box constructor

StringCompare ("string1", "string2" [, casesense = 0])

 

Third:

Please look at the documentation for the function StringCompare

Please focus on the Remarks section

 

 

 

Summary of what I've observed, and also what I would like to discuss:

 

1. The first example is for me the most correct.
2. The second example in the constructor does not contain any relevant references to # inculde files. As a result, in order to properly use the function, but I have every time to read all the documentation for this function and copy text from two different places this documentation.
3. A third example: well here at all I was surprised that description. I wonder whether he is here at the right place.

 

Please your opinion what do you think about this.

 

 

StringCompare() is a native function. You may not wish to include the optional parameters. Besides you could also pass magic numbers to the function without the includes.

 

I had to consider and compare.

My thoughts are these:

You're right, your statement is dispelled my doubts about the second example.

 

However, EDIT: I would make I continue to talk about the third example.

 

Looking through the documentation I came across DirCopy. There is a nice example that does not use: MagicNumbers. In this case, the variables are defined in FileConstants.au3.

 

So why am I writing about:

in this documentation is a difference, information on the need for FileConstants.au3 is not included in Section REMARKS but in the PARAMETERS.

 

I propose to establish a uniform method of informing about the need for additional files, when using variables to replace magic numbers.

Edited August 23, 2013 by mlipok