Merge README.wrc into wrc's man page.

tools/wrc/README.wrc

-Release 1.1.8 of wrc (24-Aug-2000), the wine resource compiler.
-
-See the file CHANGES for differences between the version and what has been
-corrected in the current version.
-
-Wrc features:
-
-- full source preprocessing
-- 16 and 32 bit support
-- LANGUAGE support (32 bit only)
-- most resource types are supported
-- enhanced expression capabilities and resource naming
-- indirect loadable resources
-- NE/PE resource directory generation
-- binary .res file generation/reading
-- byte-order conversions
-
-Wrc generates an assembly file that can be assembled with GNU's gas, or
-passed to gcc. The assembly became necessary for two reasons. First, C does
-not ensure relative position of declared data. Secondly, C complains about
-complex initialization schemes that became necessary with the NE/PE
-directory generation.
-
-
-Wrc command-line
-----------------
-You can get this message by typing 'wrc -?':
-
-Usage: wrc [options...] [infile[.rc|.res]]
-   -a n        Alignment of resource (win16 only, default is 4)
-   -b          Create an assembly array from a binary .res file
-   -B x        Set output byte-order x={n[ative], l[ittle], b[ig]}
-               (win32 only; default is n[ative] which equals little-endian)
-   -c          Add 'const' prefix to C constants
-   -C cp       Set the resource's codepage to cp (default is 0)
-   -d n        Set debug level to 'n'
-   -D id[=val] Define preprocessor identifier id=val
-   -e          Disable recognition of win32 keywords in 16bit compile
-   -E          Preprocess only
-   -g          Add symbols to the global c namespace
-   -h          Also generate a .h file
-   -H file     Same as -h but written to file
-   -I path     Set include search dir to path (multiple -I allowed)
-   -l lan      Set default language to lan (default is neutral {0, 0})
-   -L          Leave case of embedded filenames as is
-   -m          Do not remap numerical resource IDs
-   -n          Do not generate .s file
-   -N          Do not preprocess input
-   -o file     Output to file (default is infile.[res|s|h]
-   -p prefix   Give a prefix for the generated names
-   -r          Create binary .res file (compile only)
-   -s          Add structure with win32/16 (PE/NE) resource directory
-   -V          Print version end exit
-   -w 16|32    Select win16 or win32 output (default is win32)
-   -W          Enable pedantic warnings
-
-Input is taken from stdin if no sourcefile specified.
-
-Debug level 'n' is a bitmask with following meaning:
-    * 0x01 Tell which resource is parsed (verbose mode)
-    * 0x02 Dump internal structures
-    * 0x04 Create a parser trace (yydebug=1)
-    * 0x08 Preprocessor messages
-    * 0x10 Preprocessor lex messages
-    * 0x20 Preprocessor yacc trace
-
-The -o option only applies to the final destination file, which is
-in case of normal compile a .s file. You must use the '-H header.h'
-option to override the header-filename.
-If no input filename is given and the output name is not overridden
-with -o and/or -H, then the output is written to "wrc.tab.[sh]"
-
-For more info see the wrc manpage.
-
-
-Preprocessing
--------------
-The preprocessor is a fully operational C preprocessor. It handles all
-directives supported by ANSI-C. It also includes some additions from
-gcc/egcs.
-Wrc understands these directives:
-#define		(both simple and macro)
-#undef
-#if
-#ifdef
-#ifndef
-#elif
-#else
-#endif
-#error
-#warning
-#line
-#
-#pragma		(ignored)
-#ident		(ignored)
-
-The extensions include '#'-line directives.
-Not handled at the moment are variable argument macros. They are parsed,
-but not expanded properly. This will be corrected in the future.
-
-The preprocessor handles the special defines and aditionally defines an
-extra set of defines:
-  Define       | Value         | Comment
----------------+---------------+---------------
-RC_INVOKED     | 1             | Always defined
-__FLAT__       | 1             | Only defined if win32 compile
-__WIN32__      | 1             | Only defined if win32 compile
-__FILE__       | "..."         | Current filename as string
-__LINE__       | nnn           | Current linenumber as integer
-__TIME__       | "23:59:59"    | Timestring of compilation
-__DATE__       | "May  1 2000" | Datestring of compilation
-__WRC__        | 1             | Wrc's major version
-__WRC_MINOR__  | 1             | Wrc's minor version
-__WRC_MICRO__  | 7             | Wrc's minor version
-__WRC_PATCH__  | 8             | Alias of __WRC_MICRO__
-
-Include-files are not read twice if they are protected with this scheme:
-#ifndef SOME_DEFINE
-#define SOME_DEFINE
-...
-#endif
-This strategy has been borrowed from gcc/egcs and results in significantly
-reduced preprocessing times (20..30%). There must not be any junk before
-the first #ifndef and not after the last #endif; comments and whitespace
-excepted. Wrc will check the existance of the define prior to inclusion to
-detect "#undef SOME_DEFINE" (notably poppack.h) and act accordingly.
-
-
-16 and 32 bit support
----------------------
-All of wrc is layed out in such a way that it enables compilation of both 16
-and 32 bit resources. They mainly differ in code-generation and extra
-keywords. Win32 keywords are recognized by default in 16 bit compile. You
-can disable recognition of win32 reserved keywords by using the '-e' option,
-if you encounter .rc-files that use win32 reserved keywords (I strongly
-recommend that you just rename things in the source).
-
-
-Language support
-----------------
-Wrc also understands the LANGUAGE keyword (win32 only) for both global and
-local definitions of language. There are differences with respect to MS' and
-Borland's implementation. Wrc uses 0,0 as the default language if none is
-specified. Both MS and Borland use the language of the system that the
-compiler runs on.
-
-Language, version and characteristics can be bound to all resource types that
-have inline data, such as RCDATA. This is an extension to MS' resource
-compiler, which lacks this support completely. Only VERSIONINFO cannot have
-version and characteristics attached, but languages are propagated properly if
-you declare it correctly before the VERSIONINFO resource starts.
-
-Example:
-
-1 RCDATA DISCARDABLE
-LANGUAGE 1, 0
-VERSION 312
-CHARACTERISTICS 876
-{
-	1, 2, 3, 4, 5, "and whatever more data you want"
-	'00 01 02 03 04 05 06 07 08'
-}
-
-
-Resource types supported
-------------------------
-All types are supported except for:
-- RT_VXD
-- RT_PLUGPLAY
-- RT_HTML
-- RT_DLGINCLUDE
-
-These types will be implemented as soon as I get a proper specification of
-the layout.
-
-Font type resources (RT_FONT, RT_FONTDIR) are partially supported and will
-be enhanced when I have the complete spec. The font resources work only if
-you supply the FONTDIR resource yourself.
-
-
-Expression capabilities and resource names
-------------------------------------------
-You can use an expression in most places where the resource definition
-expects a number (except usertype type). Operators supported: 
-()	parenthesis
-*	multiply
-/	divide
-+	plus/add
--	minus/substract
-|	binary or
-&	binary and
-~	binary not (unary operator though)
-NOT	... (sigh)
-
-Plus (+) and minus (-) can both be unary and binary. The NOT operator is
-(primarily) used to disable window styles but I strongly suggest to refrain
-from using this operator.
-
-Resource names can be both numerical (expressions) and character typed. Wrc
-does support this insane (deep sigh) construct:
-
-MENU MENU
-{
- ...
-}
-
-It is _ONLY_ supported for backwards compatibility so that old sources can
-be compiled with winelib. DO NOT USE IT IN NEW RESOURCES, PLEASE!
-
-
-NE/PE resource directory generation
------------------------------------
-A windows executable has a table/directory of resources available in that
-module. Wrc will generate this directory with the '-s' option and place it
-in the assembly output (and header-file). This will enable the separation
-of different modules (dlls) in wine, which is the next project after wrc.
-
-The layout of the PE directory should be exactly like the executable file.
-The NE directory layout _DIFFERS_ from the real NE executable in such way
-that all offsets to actual resource data are relative to the NE directory and
-_NOT_ the beginning of the file.
-
-
-Binary .res file generation/reading
------------------------------------
-Wrc can both generate (32 and 16 bit) and read (32 bit only) .res-files.
-These can be used as intermediate files or binary files can be imported from
-other sources. The reading of 16 bit .res-files is on the list for the next
-release.
-
-You cannot convert 32 bit .res-files into 16 bit output or vice versa. I
-might implement 16 bit res into 32 bit output in the future, but I strongly
-oppose to the other way around.
-
-
-Bugs
-----
-Inherent to programs you have bugs. These I know are there, plus a few
-things that I noted in the above text (more lack of implementation than bug
-though):
-- No codepage translation
-- UNICODE translations are not/not correct implemented
-- No documentation ('wrc -?' gives command-line options and a manpage)
-- grep for FIXME in the source
-- Memory options are wrong under some conditions. There seems to be a
-  different action for win32 and win16
-- PUSHBOX control is unsupported. The MS docs use it plenty, but neither
-  MS' nor Borland's compiler supports it.
-
-Reporting bugs and patches
---------------------------
-Send problems to the wine newsgroup or, preferrably,  directly to me at:
-
-bertho@akhphd.au.dk
-
-Please send the problematic .rc source with the bug so I can reproduce it.
-Patches should _not_ be sent to Alexandre but to me. I will then review the
-change and send a full patch to be included into the new wine release (I
-prefer 'diff -u' format). You can always upload suggestions to wine
-headquarters, but be sure to send me a copy.

tools/wrc/wrc.man

@@ -166,6 +166,39 @@ Win32 compilation mode also sets __WIN32__ to 1 and __FLAT__ to 1.
 .PP
 Special macros __FILE__, __LINE__, __TIME__ and __DATE__ are also
 recognized and expand to their respective equivalent.
+.SH "LANGUAGE SUPPORT"
+Language, version and characteristics can be bound to all resource types that
+have inline data, such as RCDATA. This is an extension to MS' resource
+compiler, which lacks this support completely. Only VERSIONINFO cannot have
+version and characteristics attached, but languages are propagated properly if
+you declare it correctly before the VERSIONINFO resource starts.
+.PP
+Example:
+.PP
+1 RCDATA DISCARDABLE
+.br
+LANGUAGE 1, 0
+.br
+VERSION 312
+.br
+CHARACTERISTICS 876
+.br
+{
+.br
+	1, 2, 3, 4, 5, "and whatever more data you want"
+.br
+	'00 01 02 03 04 05 06 07 08'
+.br
+}
+.SH NE/PE RESOURCE DIRECTORY GENERATION
+A windows executable has a table/directory of resources available in that
+module. Wrc will generate this directory with the '-s' option and place it
+in the assembly output. 
+.PP
+The layout of the PE directory should be exactly like the executable file.
+The NE directory layout _DIFFERS_ from the real NE executable in such way
+that all offsets to actual resource data are relative to the NE directory and
+_NOT_ the beginning of the file.
 .SH "ERROR REPORTING"
 All errors and warnings are written to standard error and report:
 .br