[NSIS-Bugs] [ nsis-Bugs-2881164 ] need several kinds of changes to documentation

[SourceForge.net <no...@so...>]

Bugs item #2881164, was opened at 2009-10-17 21:26
Message generated for change (Tracker Item Submitted) made by jmichae3
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=373085&aid=2881164&group_id=22049

Please note that this message will contain a full copy of the comment thread,
including the initial issue submission, for this request,
not just the latest update.
Category: Documentation
Group: 2.0 Series
Status: Open
Resolution: None
Priority: 5
Private: No
Submitted By: Jim Michaels (jmichae3)
Assigned to: Nobody/Anonymous (nobody)
Summary: need several kinds of changes to documentation

Initial Comment:
These changes will make the documentation a better once-place reference.
1. in in 4.9.5.2 FileOpen where "error flag" is mentioned in passing, give detail. us programmers need detail.
what error flag are you talking about?  I don't know anything about an error flag.  I can't find it in the documentation.  so document this error flag wherever it is found in the documentation.
copy and paste works nicely.
basically, if you are telling me about something and not giving any detail or examples that explain it's use clearly, that's a mistake.

2. give usable, workable examples that handle error conditions.  in 4.9.5.2 FileOpen, the example just doesn't cut it, because "error flag" is mentioned, yet nothing in the example shows anything that handles the so-called error flag and the documentation doesn't even show what the error flag looks like.
take it beyond
FileOpen $0 $INSTDIR\file.dat r
FileClose $0

examples that give forever-loop examples like
StrCmp $R0 "2000" 0 +2
fix all those.  0 is not a useable jump example, and you shouldn't be using it in your examples without "loop/while" comments.  so document intentional loops in your examples, or you just confuse people and they think 0 means the next instruction and they start using it in their code. 
I see a lot of what look like bad examples with that 0 jump that look like untested code (forever loops when condition is true).  just search for 0 and see what you find.

3. in the bookmarks/Contents in the .CHM documentation, 
- have a section on relative and absolute jumps and other language basics under Scripting Reference|Jumps.
- have a section on predefined variables under Scripting Reference|Predefined variables
- have a section on user variables under Scripting Reference|User Variables, which covers the Var statement and talks about using $ everywhere else, even in strings.
- have a section on logic statements under Scripting Reference|Logic statements, which details ${If}, Strcmp, IfFileExists, and anything else that causes a jump on condition.
- have a section on branching statements under Scripting Reference|Branching Statements, which covers jumps like Goto
- There are no variable types, so possibly there is no need for such a section, except you might need Scripting Reference|Variable Sizes,that says that strings are by default limited to 1023 characters (if I am correct), and that different versions of windows have PATH lengths that can exceed this (such as 64-bit XP at 8191).  and also that this can be changed at compile time (and say exactly how and in what file).

it is possible you can move the existing document sections under those headings.  it will make a world of difference helping people to find what they are looking for.  basically what I was asking for is ti structure at least the core Language Ref part of it like the Visual C++ language Reference, or other C++ Language Reference.




----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=373085&aid=2881164&group_id=22049