Finished doc port

git-svn-id: https://svn.code.sf.net/p/nsis/code/NSIS/trunk@1029 212acab6-be3b-0410-9dea-997c60f758d6

Docs/src/build.bat

@@ -1,4 +1,4 @@
-bin\halibut.exe config.but intro.but usage.but script.but attributes.but compilerflags.but sections.but functions.but labels.but basic.but registry.but generalpurpose.but flowcontrol.but file.but misc.but string.but stack.but int.but reboot.but uninstall.but log.but sec.but var.but plugin.bat history.but license.but
+bin\halibut.exe config.but intro.but usage.but script.but attributes.but compilerflags.but sections.but functions.but labels.but basic.but registry.but generalpurpose.but flowcontrol.but file.but misc.but string.but stack.but int.but reboot.but uninstall.but log.but sec.but var.but usection.but callback.but compiler.but defines.but plugin.but history.but license.but
 @del *.hlp
 @del *.cnt
 @copy Contents.html index.html

Docs/src/callback.but

@@ -0,0 +1,196 @@
+\C{callbacks} Callback Functions
+
+You can create callback functions which have special names, that will be called by the installer at certain points in the install. Below is a list of currently available callbacks: 
+
+\H{instcallbacks} Install Callbacks
+
+\S{oninit} .onInit 
+
+This callback will be called when the installer is nearly finished initializing. If the '.onInit' function calls Abort, the installer will quit instantly. 
+
+Here are two examples of how this might be used:
+
+\c  Function .onInit
+\c    MessageBox MB_YESNO "This will install. Continue?" IDYES NoAbort
+\c      Abort ; causes installer to quit.
+\c    NoAbort:
+\c  FunctionEnd
+
+or:
+
+\c  Function .onInit
+\c    ReadINIStr $INSTDIR $WINDIR\\wincmd.ini Configuration InstallDir
+\c    StrCmp $INSTDIR "" 0 NoAbort
+\c      MessageBox MB_OK "Windows Commander not found. Unable to get install path."
+\c      Abort ; causes installer to quit.
+\c    NoAbort:
+\c  FunctionEnd
+
+\S{oninitdialog} .onInitDialog 
+
+This callback is called right after an inner dialog is created (excluding InstallOptions dialogs) and before it is shown. Useful for CreateFont, SetStaticBkColor and any other last minute text changes.  
+
+\S{onuserabort} .onUserAbort 
+
+This callback is called when the user hits the 'cancel' button, and the install hasn't already failed. If this function calls Abort, the install will not be aborted. 
+
+Example:
+
+\c  Function .onUserAbort
+\c    MessageBox MB_YESNO "Abort install?" IDYES NoCancelAbort
+\c      Abort ; causes installer to not quit.
+\c    NoCancelAbort:
+\c  FunctionEnd
+
+\S{onInstSuccess} .onInstSuccess 
+
+This callback is called when the install was successful, right before the install window closes (which may be after the user clicks 'Close' if AutoCloseWindow is set to false). 
+
+Example:
+
+\c   Function .onInstSuccess
+\c     MessageBox MB_YESNO "Congrats, it worked. View readme?" IDNO NoReadme
+\c       Exec notepad.exe ; view readme or whatever, if you want.
+\c     NoReadme:
+ \c  FunctionEnd
+
+ 
+\S{onInstFailed} .onInstFailed 
+
+This callback is called when the user hits the 'cancel' button after the install has failed (if it could not extract a file, or the install script used the Abort command). 
+
+Example:
+
+\c   Function .onInstFailed
+\c     MessageBox MB_OK "Better luck next time."  
+\c   FunctionEnd
+
+ 
+\S{onVerifyInstDir} .onVerifyInstDir 
+
+This callback enables control over whether or not an installation path is valid for your installer. This code will be called every time the user changes the install directory, so it shouldn't do anything crazy with MessageBox or the likes. If this function calls Abort, the installation path in $INSTDIR is deemed invalid. 
+
+Example:
+
+\c   Function .onVerifyInstDir
+\c     IfFileExists $INSTDIR\Winamp.exe PathGood
+\c       Abort ; if $INSTDIR is not a winamp directory, don't let us install there
+\c     PathGood
+\c   FunctionEnd
+ 
+\S{onMouseOverSection} .onMouseOverSection 
+
+This callback is called whenever the mouse position over the sections tree has changed. This allows you to set a description for each section for example. The section id on which the mouse is over currently is stored, temporarly, in $0.
+
+Example:
+
+\c   Function .onMouseOverSection
+\c     FindWindow $R0 "#32770" "" $HWNDPARENT
+\c     GetDlgItem $R0 $R0 1043 ; description item
+\c 
+\c     StrCmp $0 0 "" +2
+\c       SendMessage $R0 $\{WM_SETTEXT\} 0 "first section description"
+\c   
+\c     StrCmp $0 1 "" +2
+\c       SendMessage $R0 $\{WM_SETTEXT\} 0 "second section description"
+\c   FunctionEnd
+ 
+\S{onNextPage} .onNextPage 
+
+Called when the user selects to go from one page to the next. Also called when the first page is shown (after .onInit). Call Abort from this callback in order to make the installer stay on the current page (or to make it move relative to the current page - Abort 0 means to stay put, Abort 1 means to go to the next page, Abort 2 means to go to the following page, Abort -1 means to go back a page, and so on). To figure out which page you are on, you can just keep a counter and increment it on .onNextPage, and decrement it on .onPrevPage. Note that if the directory selection page is disabled, .onNextPage and .onPrevPage are still called for it.
+
+Example use of .onNextPage/.onPrevPage/.onInit:
+
+\c Function .onInit
+\c   StrCpy $9 0 ; we start on page 0
+\c FunctionEnd
+
+\c Function .onNextPage
+\c   StrCmp $9 1 "" noabort
+\c     MessageBox MB_YESNO "advance to the second page?" IDYES noabort
+\c       Abort
+\c   noabort:
+\c     IntOp $9 $9 + 1
+\c FunctionEnd
+
+\c Function .onPrevPage
+\c   StrCmp $9 2 "" noabort
+\c     MessageBox MB_YESNO "go back to the first page?" IDYES noabort
+\c       Abort
+\c   noabort:
+\c     IntOp $9 $9 - 1
+\c FunctionEnd
+ 
+ 
+\S{onPrevPage} .onPrevPage 
+
+Called when the user selects to go from one page to the previous. Call Abort from this callback in order to make the installer stay on the current page (or pass an integer parameter to Abort to specify how many pages to move: Abort 1 means to go back one page, Abort 2 means to go back two pages, Abort -1 means to go forward a page, and so on). See .onNextPage for more information.  
+
+\S{onSelChange} .onSelChange 
+
+Called when the selection changes on the component page. Useful for using with SectionSetFlags and SectionGetFlags.  
+
+\H{uninstcallbacks} Uninstall Callbacks 
+
+\S{unonInit} un.onInit 
+
+This callback will be called when the uninstaller is nearly finished initializing. If the 'un.onInit' function calls Abort, the uninstaller will quit instantly. Note that this function can verify and/or modify $INSTDIR if necessary.
+
+Here are two examples of how this might be used:
+
+\c   Function un.onInit
+\c     MessageBox MB_YESNO "This will uninstall. Continue?" IDYES NoAbort
+\c       Abort ; causes uninstaller to quit.
+\c     NoAbort:
+\c   FunctionEnd
+
+or:
+
+\c   Function un.onInit
+\c     IfFileExists $INSTDIR\\myfile.exe found
+\c       Messagebox MB_OK "Uninstall path incorrect"
+\c       Abort
+\c     found:
+\c   FunctionEnd
+
+ 
+\S{unonInitDialog} un.onInitDialog 
+
+This callback is called right after an inner dialog is created (excluding InstallOptions dialogs) and before it is shown. Useful for CreateFont, SetStaticBkColor and any other last minute text changes.  
+
+\S{unonUserAbort} un.onUserAbort 
+
+This callback is called when the user hits the 'cancel' button and the uninstall hasn't already failed. If this function calls Abort, the install will not be aborted. 
+
+Example:
+
+\c   Function un.onUserAbort
+\c     MessageBox MB_YESNO "Abort uninstall?" IDYES NoCancelAbort
+\c       Abort ; causes uninstaller to not quit.
+\c     NoCancelAbort:
+\c   FunctionEnd
+
+\S{unonUninstSuccess} un.onUninstSuccess 
+
+This callback is called when the uninstall was successful, right before the install window closes (which may be after the user clicks 'Close' if AutoCloseWindow is set to false). 
+
+Example:
+
+\c   Function un.onUninstSuccess
+\c     MessageBox MB_OK "Congrats, it's gone."
+\c   FunctionEnd
+
+\S{unonUninstFailed} un.onUninstFailed 
+
+This callback is called when the user hits the 'cancel' button after the uninstall has failed (if it used the Abort command or otherwise failed). 
+
+Example:
+
+\c   Function un.onUninstFailed
+\c     MessageBox MB_OK "Better luck next time."  
+\c   FunctionEnd
+
+ 
+\S{unonNextPage} un.onNextPage 
+
+Called when the user selects 'Uninstall' or 'Close' from the uninstaller. Call Abort from this callback in order to make the uninstaller stay on the current page.  

Docs/src/compiler.but

@@ -0,0 +1,19 @@
+\C{compcommands} Compiler Utility Commands
+
+These commands are similar to the C preprocessor in terms of purpose and functionality. They allow file inclusion, conditional compilation, executable header packing, and processes execution during the build process. Note: none of these commands allow use of variables. 
+
+\e{!system}
+
+command [compare comparevalue] This command will execute 'command' using a call to system(), and if the return value compared (using 'compare') to 'comparevalue' is false, execution will halt. 'compare' can be '<' or '>' or '<>' or '=' or 'ignore'.  
+
+\e{!include file}
+
+This command will include 'file' as if it was part of the original script. Note that if a file is included in another directory, the current directory is still where the script was compiled from (not where the included file resides).  
+
+\e{!cd new_path}
+
+This command will change the compiler to the new directory, new_path. new_path can be relative or absolute.  
+
+\e{!packhdr tempfile command}
+
+This option makes the compiler an external EXE packer (such as Petite or UPX) to compress the executable header. Specify a temporary file name (such as "temp.dat") and a command line (such as "C:\\program files\\upx\\upx -9 temp.dat") to compress the header.  

Docs/src/defines.but

@@ -0,0 +1,62 @@
+\C{compdefines} Compiler Defines/Conditional Compilation
+
+The compiler maintains a list of defined symbols, which can be defined using !define or the /D command line switch. These defined symbols can be used for conditional compilation (using !ifdef) or for symbol replacement (a simple form of macros). To replace a symbol with its value, use $\{SYMBOL\} (if SYMBOL is not defined, no translation will occur). The translation is first-come-first-served, meaning if you do:
+       
+\c !define symbol1 ${symbol2}
+
+If symbol2 is defined when that line occurs, it will be replaced. Otherwise, any replacing will occur when $\{symbol1\} is referenced. 
+
+Define/conditional compilation related commands:
+
+\e{!define gflag [value]}
+
+This command will add 'gflag' to the global define list. This will have a similar effect as using the /D switch on the command line (only the define only becomes effective after the !define command).  
+
+\e{!undef gflag} 
+
+Removes an item from the global define list. Note that $\{SYMBOL\} where SYMBOL is undefined will be translated to "$\{SYMBOL\}".  
+
+\e{!ifdef gflag [bcheck [gflag [...]]]} 
+
+This command, when paired with an !endif command, will tell the compiler whether or not to compile the lines in between the two lines. If gflag is globally defined (using !define or the /D switch), then the contained lines will be compiled. Otherwise, they will be skipped. 'bcheck' can be specified as & (boolean and) or | (boolean or) along with more gflags -- precedence is simple, left to right.  
+
+\e{!ifndef gflag [bcheck [gflag [...]]]} 
+
+This command is the opposite of !ifdef (If 'gflag' is not globally defined, the lines contained will be compiled). Note that when using boolean operators (& or |), 'gflag' is treated as true if it is undefined. I.e. '!ifndef X | Y' means "if either X or Y is undefined" and '!ifndef X & Y' means "if X and Y are both undefined".  
+
+\e{!endif}  
+
+This command closes a block started with !ifdef or !ifndef.  
+
+\e{!else [ifdef|ifndef [...]]} 
+
+This command is the logical lovemonkey to !ifdef and !endif. !ifdef/!else/!endif, !ifdef/!else ifdef/!endif, !ifdef/!else ifdef/!else ifndef/!endif, etc. If ifdef or ifndef is specified as the first parameter, it behaves as expected.  
+
+\e{!echo message} 
+
+This command will echo a message to the user compiling the script.  
+
+\e{!warning [message]} 
+
+This command will issue a warning to the script compiler. You can also add a message to this warning.  
+
+\e{!error [message]}
+
+This commnd will issue an error to the script compiler and will stop execution of the script. You can also add a message to this error.  
+
+\e{!verbose level} 
+
+This command will set the level of verbosity. 4=all, 3=no script, 2=no info, 1=no warnings, 0=none  
+
+\e{!macro macro_name [parameter][...]} 
+
+Creates a macro named 'macro_name'. All lines between the !macro and the !macroend will be saved. To insert the macro later on, use !insertmacro. Note that macros cannot contain other macro definitions (though they can insert other macros), or !ifdef/!else/!endif. !macro definitions can have one or more parameters defined. The parameters may be accessed the same way a !define would (i.e. $\{PARMNAME\}) from inside the macro.  
+
+\e{!macroend}  
+
+Ends a macro that was started with !macro.  
+
+\e{!insertmacro macro_name [parameter] [...]} 
+
+Inserts the contents of a macro that was created with !macro. If the macro was created with parameters, then you must pass as many parameters to the macro as it requires.  
+

Docs/src/plugin.but

@@ -0,0 +1,29 @@
+\C{plugindlls} Plugin DLLs
+
+The abilities of the NSIS scripting language can be extended by utilising functionality provided in a DLL file. Probably the best known example of this is the InstallOptions.dll bundled with every NSIS release.
+
+When the NSIS compiler starts it scans the plugins directory for DLLs and makes a list of the plugins found and their exported functions. During compilation if a sequence such as fred::flintstone is encountered where the compiler expected to find a language keyword the compiler will look through this list. If a list entry specifies that fred.dll exports function flintstone NSIS will pack the fred.dll file into the created installer binary.
+
+During execution of the created installer if a plugin command is executed NSIS will unpack the necessary DLL to the $TEMP directory, execute the DLL function, then delete the DLL. If the /NOUNLOAD option is specified the DLL will not be deleted until the installer exits.
+
+\H{usingplug} Using Plugin Commands
+
+The following two examples both invoke the same plugin command. The first example shows the (still okay) syntax that scripts written for versions of NSIS earlier than 2.0a4 had to use, and the second is how it can be scripted more succintly now. The newer syntax automatically handles packing & extraction of the DLL file, and stacks up arguments for you too.
+
+\c ; Pre 2.0a4 syntax
+\c SetOutPath $TEMP
+\c GetTempFileName $8
+\c File /oname=$8 InstallOptions.dll
+\c Push "ini_file_location.ini"
+\c CallInstDLL dialog
+
+\c ; Newer syntax
+\c InstallOptions::dialog "ini_file_location.ini"
+
+InstallOptions needs the name of it's ini file as a parameter to the dialog function so it has to be pushed onto the stack before the dialog call is made. Some plugin commands may not need any parameters on the stack, others might require two or three. To use a plugin command you will need to read the documentation for the plugin so that you know what parameters it's functions require, if any.
+
+\H{disablingplug} Disabling Unloading
+
+CallInstDLL has an option not to unload the DLL after usage. To use it with the newer plugin command syntax just specify the first parameter as /NOUNLOAD. For example:
+
+\c InstallOptions::dialog /NOUNLOAD "ini_file_location.ini"

Docs/src/usection.but

@@ -0,0 +1,12 @@
+\C{UninstallSection} Uninstall Section
+
+A special Section named 'Uninstall' must be created in order to generate an uninstaller. This section should remove all files, registry keys, etc that were installed by the installer, from the system. Here is an example of a simple uninstall section:
+        
+\c Section "Uninstall"
+\c   Delete $INSTDIR\Uninst.exe ; delete self (see explanation below why this works)
+\c   Delete $INSTDIR\myApp.exe
+\c   RMDir $INSTDIR
+\c   DeleteRegKey HKLM SOFTWARE\myApp
+\c SectionEnd
+
+The first Delete instruction works (deleting the uninstaller), because the uninstaller is transparently copied to the system temporary directory for the uninstall.