Converting NT DDK/SDK PostScript documents to PDF

Pre-releases of Microsoft’s NT development tools, as well as the final NT 3.1 SDK and DDK, shipped with a full set of printable documentation in PostScript format. The PostScript book-style document were rather more pleasing to the eye than the WinHelp format, and especially for the explanatory “guide” material, some readers found them much nicer to work with.

But really, who wants thousands of pages of dead tree matter? The complete SDK/DDK documentation set ran to somewhere in the 10,000 pages range. It should be easy to convert the PostScript documents to PDFs and obtain a nice set of easily viewable and searchable documents. It should be easy… It’s anything but.

Microsoft used at least four different systems to produce the NT PostScript documentation. The NT Kernel Guide was written in MS Word 5.0 (DOS or OS/2 based). Most of the rest of the NT DDK and SDK documentation was created with Word for Windows 2.0. Reference for the Windows 3.1 setup API was produced in Aldus PageMaker 4.0. Rather surprisingly, documentation for the Microsoft C/C++ compiler was created in Digital Research’s Ventura Publisher.

Perhaps less surprisingly, the PostScript files created by the first two solutions (Word 5.0 and Word for Windows 2.0) were far more troublesome than the rest. That is to say, the output from PageMaker and Ventura Publisher can be fed to Distiller or GhostScript without modification and produces great looking PDFs.

The Word for Windows 2.0 output is generally accepted by Distiller and GhostScript and produces workable PDFs, with one nasty flaw: all bullet glyphs are rendered as ‘u’ in Courier font—not pretty. The documents look for MSIcons and/or MSIcons2 font, which is nowhere to be found; the only Google hits are other PostScript documents.

An attempt to replace the MSIcons font by WingDings or similar failed because the font metrics are too different. However, a more thorough search turned up a file called MSICONS.PS—included with the Japanese NT 3.1 SDK PostScript documents, but not mentioned anywhere. Fortunately, after minor editing, the file can be renamed to msicons.pfa, cloned to msicons2.pfa, and placed on a font search path for GhostScript and/or Distiller. That finally produced good looking PDFs.

The NT kernel guide documents were the toughest nut to crack. First of all, the delivered .PS files can’t be processed at all; they must be combined with the included PSHEADER.PS (‘copy psheader.ps + foo.ps realfoo.ps’ does the job). Unfortunately the header is not accepted as is and the ExitServer section at the top of the file must be removed (I don’t know what it does; presumably only printers understand it, not GhostScript or Distiller).

With that change, both GhostScript and Distiller can process the file. Sadly, the output is not acceptable: bullets are broken (again), this time replaced by ‘n’ in Courier font, and in Distiller output, underlines are so thick that they obscure the entire line of text.

First fixing the underlines. The PostScript produced by Word 5.0 use a rather ingenuous method to produce underlines (or strikeouts). The underscore character is looked up, converted into a path, then the bounding box of the path is computed. The bounding box is then extruded to stretch from the beginning to the end of the underlined text (on a single line only, obviously).

I don’t know why that does not work with Distiller. I suspect it has to do with protected fonts, and Distiller does not allow the conversion of a character into a path (how stupid is that? a $400 product shouldn’t be so crippled!). In GhostScript that is not an issue as it uses free fonts by default. I ended up hacking the PostScript header file to subtract an arbitrary constant from the bounding box. Ugly hack, but pretty results.

Now for the bullets. The Kernel Guide uses the ZapfDingbats font for bullets. Neither Distiller nor GhostScript have this font, but both have suitable replacements. So why doesn’t that work? The PostScript created by Word 5.0 is too clever by half. It uses its own font lookup routine and if an exact match for a font is not found, it’s replaced by Courier. The solution is to disable the routine. Once that is done, Distiller or GhostScript has a chance to replace ZapfDingbats with something sensible. Whew.

As an example, here’s a converted DDK Kernel Mode Design Guide from the March ’93 pre-release DDK. The document is not complete and several sections are “to be written”. The time-stamps on the PostScript files range from November ’92 to March ’93.

This entry was posted in Documentation, NT. Bookmark the permalink.

5 Responses to Converting NT DDK/SDK PostScript documents to PDF

  1. Dale Smoker says:

    Hi,

    I couldn’t figure out how to render the NT Kernel Guide. Could you add more detail about hacking the bounding box and disabling the font look-up routine (msfindfont)?

    Could you also describe what editing was required for the Word for Windows 2.0 files or post msicons.pfa for download?

    Thanks

  2. michaln says:

    Which Kernel Guide are you interested in (month/year)? I could probably just put up a PDF… but it might take me a few days if I have to retrace my steps 🙂

  3. Dale Smoker says:

    Hi,

    I wanted to read the NT 3.1 DDK documentation.

    Thank You 🙂

  4. michaln says:

    Okay, let’s start with the Kernel-mode Driver Design Guide: http://www.os2museum.com/files/ntps/NTDDK-3.1-KG.pdf And here’s the Kernel-mode Driver Reference: http://www.os2museum.com/files/ntps/NTDDK-3.1-KR.pdf

    This PDFs are from a while back, it’ll take me a while to get the “build system” going properly.

    By the way, one unsolved problem is the lack of a ‘MS Letter Gothic’ font. That one doesn’t appear to have survived into the 21st century, at least not in an accessible form.

  5. Dale Smoker says:

    Cool! They look really good. I can’t wait to dig into these!

    Thanks!! 🙂

Leave a Reply

Your email address will not be published. Required fields are marked *