Talk:Wgml

From Open Watcom

Revision as of 18:04, 28 August 2007; view current revision
←Older revision | Newer revision→
Jump to: navigation, search

[this is my 1st visit to the site & could not find a way to email the author directly, which would be preferable]

Let me start by saying that I have ver. 3.32 so there may be some small inconsistencies.

What you propose is no small undertaking, as wgml is quite robust and capable of more than just reference manuals. I would suggest that you concentrate on gendev and accept wgml as is, warts and all.

Recreating gendev, on the other hand, should be fairly straight forward. It's .COP files are analogous to wasm's .OBJ files, in that all gendev does is parse, check syntax & file existence and output data structures that wgml can load directly. Remember, this was developed in the mid '80s (when the man at the switch couldn't imagine PCs would ever need more that 640K - thanks a lot, Bill) and memory was tight and CPU speed was in single digit MHz, not GHz. As most of what gendev does wouldn't vary from one document to another, it made sense to keep it separate.

Decoding the .COP files should be easier, now that you know:

  • they are basically just a dump of device dependent data structures common to both programs
  • given memory was as tight as it was in those days, it was common practice to flip bits & pack them tight
 e.g. in your non-designators 0x0101, 0x0201, 0x0401, the right-most nibble (the 8-bit 01) could be unrelated 
      to the type of block 
  • assume "little-endian": these programs were developed using PC based WSL compilers before the 386 processors were even available

re: the :CMT tag - it was never intended to be an 'anywhere' tag. From the guide:
> The comment tag must be placed at the beginning of each input record that is to be
> ignored. This tag may appear at any point in the device definition source, although it
> may not be placed between device tag attributes.
Granted, there is no explicit prohibition of it's use w/i a data block; I think that was assumed.

re: 3.2.1 Discriminator - your files are DOS versions, so the 3 character strings ("DEV", "DRV", "FON") are, I think, the default file extensions (so the 0x03 that precedes them all is just another length of string). Although developed on PCs, each build was ported to both VAX/VMS and VM/CMS. Also, some of my .COP files have, immediately after "DEV", 0x06 followed by "(f:80)". In the guide, Chapter 17, they talk about three types of file formats: text (w/ each record ending in CR LF), fixed (e.g: by prefixing the filename w/ "(f:N)", where N is the record length) and variable (e.g: by prefixing the filename w/ "(v:N)", where N is the maximum record length). I don't know how long fixed & variable were supported under DOS but the mainframes always did.

As for your Directory File Format, in a word, Yikes! The 205 identical entries for HELPDRV is just weird. The 'Meta-Type Indicators' don't appear in my WGMLST.COP (this is probably due to the fact I'm running ver 3.32 in that extra fields were added to the data structure). Again, I believe this .COP is meant to be read into WGML data structure. First, the order of the entries varies inversely w/ that of the generating file (the one w/ all the :include statements).

 e.g. my :includes goes drv, dev, fon, fon, fon, fon, dev, drv, fon, fon, fon, fon and 
      finally, drv, dev, drv, dev, followed by 8 fon :include's all mixed up.  

This ordering is preserved in WGMLST.COP, only in reverse. Thus, the ordering w/i WGMLST.COP is irrelevant.

My copy of WGMLST.COP is 640 bytes long. Your's is way too big. I suggest that you regenerate from scratch - I'm assuming you have all the source files for the .COP files. First, either back it up or create an isolated 'working' copy. Then delete WGMLST.COP. Do you have a file w/ lots of :include tags? Mine is called GEN_LIB.PCD, though that just may have been my name for it (it's been too long). It just includes device, driver and font files for my printer, as well as for TERM (for proofing). Run it thru GENDEV and you should get a WGMLST.COP that's less than 640K.

It is my belief that this is not a directory file but rather a mapping one. All of my entries are of the Compact variety. This file simply associates the max. 8 char filename w/ the user's (usually) longer, more readable name (e.g. 'LQ850D17' <-> 'compressed17-draft'). I think WGML uses this file for it's command line processing, as in this partial options file for a letter quality Epson dot matrix printer:
( device EPSON-LQ850-LQ
( font 0 pica10 plain
( font 1 pica10 uline
( font 2 micron15-draft plain
( font 3 compressed17-draft plain
( format standard
( ...
The 'device' option gets you both the device and driver files, as the device file has the driver name. And the font option gets you the font files. So using WGMLST.COP, WGML knows from the options exactly which .COP files need to be loaded. It's another memory saver, loading only those 'compiled' files you actually need (the distribution of ver. 3.32 has 750 device, driver, font and table files!).

BTW, under Implementation Notes, #1 - invoking with no parameters ..., this feature is present in both wgml and gendev. It allows for long input options (see example above wrt Epson); hitting Enter on a blank terminates the input, although earlier versions required a Ctrl-Z, Enter. I'm running WinXP and never have to 'close the window'.

Hope this is of some help - Chris

I don't know when the above was input, as it never occurred to me that someone would use this tab. Please advise if you have put remarks anywhere else so I can read them.

It appears that you have a working 3.32 installation of wgml. This is the first indication I have seen that wgml is in use outside of OpenWatcom, and that is encouraging.

The reason we are redoing gendev/wgml is so that we can run it as a 32-bit command-line executable and, eventually perhaps, as a linux executable. We already have 32-bit DOS and OS/2 versions which were provided with the source tree when the project was open sourced. The 32-bit DOS version is used for the builds under Windows and some recent versions of Windows will not run 32-bit DOS (which is, of course, a 16-bit program using a DOS extender from the viewpoint of the OS).

I wish I had read this earlier. Your notes on the :CMT. tag "discoveries" being in the manual and the "03" as a count byte have, in a sense, been put into the Wiki as I discovered/thought of them myself. (That is, the Wiki has been modified to state that "discoveries" which match the manual are to be regarded as confirmations, not as new information, and a section was added giving an alternate interpretation of "02" "03" and "04" as length bytes).

The "(f:80)" in 3.3 and 4.1 is found in DRV files, encoding an attribute.

The WGMLST.COP file with the bizaare format has to have a history of abuse of some sort. My gendev will not be writing that format. It will write only compact entries. The use of "directory file" is simply a matter of terminological desperation; what else would a file mapping defined names to file names be called, I asked myself, and got no answer.

I don't want to regenerate the WGMLST.COP file because it works, and I can see no good reason to change what works. Also, we are using a version control system (Perforce) which I believe cannot control versions of this file because there is no editor defined for it, and which I am not an expert in using. I would hate to lose the file and demolish our document build system.

As to program behavior, all I can say is that, if I type "gendev" or "wgml" and hit return, and do not enter commands but try to exit the program, nothing short of closing the window will work. It ignores "Ctl-C", which is a fairly-standard convention. The OpenWatcom build system uses really large command files and very short command lines. But perhaps 3.2 did not have this option.

If you have not already done so, you might want to join the newsgroup.

(Interesting -- the Wiki just appends whatever you type in, with no separation at all, at least if no subject is input).

The above (up to the previous contributor's name) was, of course, written by Paul.

Personal tools