Update documentation

Expand the install section, adding a note about using the Startup group.

Add a brief "How it Works" section to `readme.md`.
This commit is contained in:
Jason Hood 2017-12-23 22:04:44 +10:00
parent 4502a49bab
commit 9140e3bd56
2 changed files with 52 additions and 32 deletions

View File

@ -7,3 +7,22 @@ provides much the same functionality as `ANSI.SYS` does for MS-DOS.
* 32-bit: Windows 2000 Professional and later (it won't work with NT or 9X). * 32-bit: Windows 2000 Professional and later (it won't work with NT or 9X).
* 64-bit: AMD64 (it won't work with IA64). * 64-bit: AMD64 (it won't work with IA64).
## How it Works
ANSICON *injects* a DLL into a process, *hooking* its functions.
### Injection
One of three methods is used to inject the DLL.
* `LoadLibrary` via `CreateRemoteThread` for a running process.
* `LdrLoadDll` via `CreateRemoteThread` for a 64-bit .NET AnyCPU process.
* Adding the DLL directly to the import table, otherwise.
### Hooking
Hooking is achieved by modifying import addresses, or the return value of
`GetProcAddress`.

View File

@ -23,23 +23,27 @@ Requirements
Installation Installation
============ ============
Add "x86" (if your OS is 32-bit) or "x64" (if 64-bit) to your PATH, or copy There are three ways to install, depending on your usage.
the relevant files to a directory already on the PATH (but NOT System32).
Alternatively, use option '-i' (or '-I', if permitted) to install it
permanently, by adding an entry to CMD.EXE's AutoRun registry value
(current user or local machine, respectively).
Uninstall simply involves closing any programs that are currently using it; * Add "x86" (if your OS is 32-bit) or "x64" (if 64-bit) to your PATH, or
running with '-u' (and/or '-U') to remove it from AutoRun; removing the copy the relevant files to a directory already on the PATH (but NOT to
directory from PATH; and deleting the files. No other changes are made "System32" on a 64-bit system). This means you explicitly run 'ansicon'
(although you may have also created environment variables). whenever you want to use it.
Upgrading * Use option '-i' (or '-I', if permitted) to add an entry to CMD.EXE's
--------- AutoRun registry value (current user or local machine, respectively).
This means "Command Prompt" and any program started by CMD.EXE will
automatically have sequences.
Delete ANSI.dll, it has been replaced with ANSI32.dll. * Add "d:\path\to\ansicon.exe -p" to your Startup group (run minimized to
Delete ANSI-LLA.exe and ANSI-LLW.exe, they are no longer used. avoid the console window flashing). This means any console program
Uninstall a pre-1.50 version and reinstall with this version. started by Explorer will automatically have sequences.
Uninstall involves closing any programs that are currently using it; using
the Run dialog to run "d:\path\to\ansicon.exe -pu" to remove it from
Explorer; running with '-u' (and/or '-U') to remove it from AutoRun; remov-
ing the directory from PATH; and deleting the files. No other changes are
made (unless you created environment variables).
Usage Usage
@ -84,7 +88,7 @@ Usage
If you experience trouble with certain programs, the log may help in find- If you experience trouble with certain programs, the log may help in find-
ing the cause; it can be found at "%TEMP%\ansicon.log". A number should ing the cause; it can be found at "%TEMP%\ansicon.log". A number should
follow the 'l': immediately follow the 'l':
0 No logging 0 No logging
1 Log process start and end 1 Log process start and end
@ -112,8 +116,8 @@ Usage
The variable is updated whenever a program reads it directly (i.e. as an The variable is updated whenever a program reads it directly (i.e. as an
individual request, not as part of the entire environment block). For individual request, not as part of the entire environment block). For
example, 'set an' will not update it, but 'echo %ansicon%' will. Also example, 'set an' will not update it, but 'echo %ansicon%' will. Also
created are ANSICON_VER, which contains the version without the point (1.50 created are ANSICON_VER, which contains the version without the point (1.80
becomes "150"), and CLICOLOR (see http://bixense.com/clicolors/), which becomes "180"), and CLICOLOR (see http://bixense.com/clicolors/), which
contains "1". These variables do not exist as part of the environment contains "1". These variables do not exist as part of the environment
block (e.g. 'set an' will not show ANSICON_VER). block (e.g. 'set an' will not show ANSICON_VER).
@ -123,7 +127,8 @@ Usage
Using 'ansicon' after install will always start with the default attrib- Using 'ansicon' after install will always start with the default attrib-
utes, restoring the originals on exit; all other programs will use the cur- utes, restoring the originals on exit; all other programs will use the cur-
rent attributes. The shift state is always reset for a new process. rent attributes. The shift state and insert mode are always reset for a
new process.
My version of WriteConsoleA will always set the number of characters writt- My version of WriteConsoleA will always set the number of characters writt-
en, not the number of bytes. This means writing a double-byte character as en, not the number of bytes. This means writing a double-byte character as
@ -234,8 +239,8 @@ Sequences Recognised
perform its function; an unrecognised character will preserve the escape. perform its function; an unrecognised character will preserve the escape.
SO will select the G1 character set; SI will select the G0 set. The G0 SO will select the G1 character set; SI will select the G0 set. The G0
character set is set by SCS; the G1 character set is always the DEC character set is set by SCS; the G1 character set is always the DEC Special
Special Graphics Character Set. Graphics Character Set.
I make a distinction between '\e[m' and '\e[0;...m'. Both will restore the I make a distinction between '\e[m' and '\e[0;...m'. Both will restore the
original foreground/background colors (and so '0' should be the first para- original foreground/background colors (and so '0' should be the first para-
@ -334,6 +339,7 @@ Version History
- fix explicit zero parameters not defaulting to 1; - fix explicit zero parameters not defaulting to 1;
- set color by index (also setting bold/underline); - set color by index (also setting bold/underline);
- fix processes that start without a window; - fix processes that start without a window;
* use the system default sound for the bell;
* limit parameters to a maximum value of 32767; * limit parameters to a maximum value of 32767;
* go back to saving the buffer cursor position; * go back to saving the buffer cursor position;
* preserve escape that isn't part of a sequence; * preserve escape that isn't part of a sequence;
@ -341,26 +347,21 @@ Version History
* change the graphics SCAN characters to their Unicode equivalents; * change the graphics SCAN characters to their Unicode equivalents;
* BS/CUB/HVP after wrap will move back to the previous line(s); * BS/CUB/HVP after wrap will move back to the previous line(s);
* improve speed by only flushing when necessary, adding a mode to restore * improve speed by only flushing when necessary, adding a mode to restore
flushing immediately. flushing immediately;
+ use the system default sound for the bell; + added DA, DECCOLM, DECNCSM, DECOM, DECPS, DECRC, DECSC, DECST8C, DECSTBM,
+ added Play Sound DECPS; DECSTR, HT, HTS, IND, IRM, NEL, RI, RIS, SCS (only G0 as Special/ASCII),
SD, SU and TBC;
+ added '+' intermediate byte to use the buffer, rather than the window; + added '+' intermediate byte to use the buffer, rather than the window;
+ added palette sequences; + added set/get palette sequences;
+ added the bright SGR colors; + added the bright SGR colors;
+ added -pu to unload from the parent; + added -pu to unload from the parent.
+ added IND, NEL, RI, DA, DECCOLM, DECNCSM, DECSC & DECRC;
+ added SCS, but only for special/ASCII (same as Win10);
+ added tab handling (HT, HTS, TBC & DECST8C);
+ added IRM;
+ added DECOM, DECSTBM, SD & SU;
+ added DECSTR & RIS.
1.72 - 24 December, 2015: 1.72 - 24 December, 2015:
- handle STD_OUTPUT_HANDLE & STD_ERROR_HANDLE in WriteFile; - handle STD_OUTPUT_HANDLE & STD_ERROR_HANDLE in WriteFile;
- better handling of unusual PE files; - better handling of unusual PE files;
* cache GetConsoleMode for an improvement in speed; * cache GetConsoleMode for an improvement in speed;
* files writing to the console always succeed (should mostly remove the * files writing to the console always succeed (should mostly remove the
need for ANSICON_API); need for ANSICON_API);
* log: add a blank line between processes; * log: add a blank line between processes;
remove the separate line for WriteFile & _lwrite; remove the separate line for WriteFile & _lwrite;
write byte strings as-is, wide strings using the current code page; write byte strings as-is, wide strings using the current code page;