jagregory / abrash-black-book Goto Github PK

Markdown source for Michael Abrash's Graphics Programming Black Book

CSS 43.90% Makefile 12.41% HTML 43.69%

abrash-black-book's Introduction

Michael Abrash's Graphics Programming Black Book

This is the source for an ebook version of Michael Abrash's Black Book of Graphics Programming (Special Edition), originally published in 1997 and released online for free in 2001 (original link now broken, Internet Archive link).

Reproduced with blessing of Michael Abrash, converted and maintained by James Gregory.

The GitHub releases list has an EPUB and Mobi version available for download, and you can find a mirror of the HTML version at www.jagregory.com/abrash-black-book.

How does this differ from the previously released versions?

The book is now out of print, and hard to come by. Last time I checked, it was going for over $200 on eBay.

The version which Michael and Dr. Dobbs released in 2001 was a collection of PDF files. That version is still available (original link now broken, Internet Archive link). However, the structure (multiple files) and the format (PDF) result in a poor user experience on an ebook reader or other mobile device.

This version has been thoroughly cleaned of artifacts and condensed into something which can easily be converted into an ebook-friendly format. You can read this version online at GitHub, or download any of the EPUB or Mobi releases. You can clone the repository and generate your own version with pandoc if necessary.

Contributing

Changes are welcome, especially conversion-related ones. If you spot any problems while reading, please submit an issue and I'll correct it. Pull requests are always welcome.

Some larger changes could be made to improve the content. I'd love to see some of the images converted to a vector representation so we can provide higher-resolution versions. Formulas and equations could be typeset with MathJax.

Generating your own ebook

You need to have the following software installed and on your PATH before you begin:

pandoc version 2.0 or greater for Markdown to HTML and EPUB conversion.
kindlegen for Epub to Mobi conversion.

To generate an e-reader friendly version of the book, you can use make with one of the following options:

html - build an HTML5 single-page version of the book
epub - build an EPUB3 ebook
mobi - build a Kindle-friendly Mobi
all - do all of the above

Once complete, there will be an out directory with a black-book.epub, a black-book.mobi and an html directory with a black-book.html file.

Note: Generating a Mobi requires an EPUB to already exist. Also, Mobi generation can be slow because of compression. If you want a quick Mobi conversion you can just run kindlegen out/black-book.epub.

abrash-black-book's People

Contributors

Stargazers

Watchers

Forkers

mpmedia mancobian druidsbane mattl202 joe8bit ygra mgile makash rblackwe ejchet smtechnocrat demiguise gcr anjackson tibbon picomancer dylang malkia knodi nrdufour aholmes danhyun alx wookie786 durango ortuna catufunwa awesome steets oaguy1 kagekirin wintermind ajaykgp tml gregnwosu gnlnx claudiouzelac uikit0 goldenpipewrench fabiensanglard rmurthy1 vietnt svanellewee veekay7 efrenacosta paincompiler neshume khobalt jstedfast fenkesi kalebdark jeffpar skydevht bundgaard joseprous inothnagel ylyking azmr seymer iorange ajinkyakulkarni silky funfei1987 jujis008 frob ntwk ryman linuxenia whb224117 jesseshieh connlan thecocce babooppa6 4sp1r3 anqurvanillapy caoimhinp mkalas tachen stipid pstankiewicz ruiorey tomihasa shadercoder rivokl intdxdt eticzon akhilkrushnaa alainlompo bitmybytes dorgonman ngmlab kurtulusarkan mightybucket t4world gomson vinilm matrix-1996 bharath1097 ambient-seclusion vdt

abrash-black-book's Issues

-- merged to — ?

I think -- gets merged to whatever that long hyphen character is called, which leads to reading code incorrectly, for example in chapter 17 I think while (—init_length) should be while (—init_length) ...which is github doing exactly what I said. In the latter case it should read

-- init_length

Font sizes are ignored in Mobi

When converting a pandoc generated epub to mobi using kindlegen, the font sizes aren't carried across. This causes issues for reading the code samples.

Zen of Assembly Language

Didn't know how else to contact Michael. We have a reconstructed Zen of Assembly Language PDF created mostly from files on the old CD. We have redrawn the images and filled in the missing parts. The listings are hyperlinked so that one can go back and forth while reading the book. We created the PDF by first converting the RTF files on the disk to Microsoft Word 2007 DOCX. Many hours were spent on this project. Just wondering if you are interested in reviewing it. Our email is [email protected].
R W

Typos in Chapter 1

I'm new to x86 assembly and I'm trying to get this working on a modern x86 processor using Visual Studio 2017. However, copying in the .asm files gives several errors.

The listings in chapter 1 don't seem to be right because listing 1.3 has a line where it says "_ChecksumFile proc near" and in listing 1.7 it says "_ChecksumChunkprocnear". I think there are multiple places where whitespaces have been messed up? For example, isn't it supposed to be "_ChecksumFile endp" and not "_ChecksumFileendp"?

License type

Hi,
I was wondering what kind of license does Graphics Programming Black Book has now?
Can one have it printed for oneself and colleagues at work (no general public)?
Thanks.

Cover page incorrect

The cover page on my Kobo reader shows it zoomed in, rather than showing the whole cover.

Table of Contents should start from 23 for Part 2

This is a HTML output issue, the OL for Part 2 needs to start at 23. Not sure how to do this with pandoc.

Typos in chapter 4

Typos in chapter (256*15.08 microseconds = 3.86 microseconds?!) result in a poor user experience. I'm going back to the PDFs. They are better formatted anyways. I never thought I'd say that about a PDF.

how can i compile to PDF file?

Great Work your job.
And I want to use your model to generate my own book in PDF,
Could you give some suggestions?
Thank you.

Declare content language as English in epub

I'm reading the epub version in iBooks on iOS, my system language is set to German, and I sometimes use the screen reader in addition to just reading on-screen. Most parts of the book are properly screen-read using an English voice, but some parts are read using a German voice (not sure if that's because of my system's language, or because it auto-detects parts as German).

I assume a lot here, but maybe my problem can be fixed by specifying the language (English) in the epub file explicitly so that screen readers (possibly -- might be a software defect with iBooks and nothing to do with the book itself) read everything as English?

Here's some links I've found:

https://www.mobileread.com/forums/showthread.php?t=87928
https://gist.github.com/labocho/1009210

I also noticed that content.opf has this set: <dc:language>en-AU</dc:language>, but maybe just setting lang="en" in the <html> tags of each chapter helps?

https://stackoverflow.com/questions/1071789/how-to-specify-language-of-website-html

Feature Request: Build an e-book without the code snippets for text-to-speech

Thanks for your work on this project.

Using text-to-speech on assembly language listings is an excruciating experience!

Build failure due to deprecated Pandoc -S switch

Attempting to build the HTML or EPUB versions of the book fails with the following error:

--smart/-S has been removed.  Use +smart or -smart extension instead.
For example: pandoc -f markdown+smart -t markdown-smart.
Try pandoc --help for more information.

I am currently using Pandoc 2.2.3.2 and it appears that Pandoc 2.0 made some changes to its command-line interface. The same issue was seen in rmarkdown issue #1120.

Typos in Chapter 4

There are some instances of "µs" that should be "ms" instead, in the "Dynamic RAM Refresh: The Invisible Hand" section.

All of the PC’s system memory consists of DRAM chips. Each DRAM chip in the PC must be completely refreshed about once every four milliseconds in order to ensure the integrity of the data it stores. Obviously, it’s highly desirable that the memory in the PC retain the correct data indefinitely, so each DRAM chip in the PC must always be refreshed within 4 µs of the last refresh. Since there’s no guarantee that a given program will access each and every DRAM block once every 4 µs, the PC contains special circuitry and programming for providing DRAM refresh.

The two "4µs" instances should be ms, and also on the next section:

The 256 addresses accessed by the refresh DMA accesses are arranged so that taken together they properly refresh all the memory in the PC. By accessing one of the 256 addresses every 15.08 µs, all of the PC’s DRAM is refreshed in 256 x 15.08 µs, or 3.86 µs, which is just about the desired 4 µs time I mentioned earlier. (Only the first 640K of memory is refreshed in the PC; video adapters and other adapters above 640K containing memory that requires refreshing must provide their own DRAM refresh in pre-AT systems.)

The "3.86 µs" and the "4µs" right after should also be ms.

I have confirmed that the original PDFs (linked on this project's main page) have the correct units.

I apologize if this is not the proper way to report this issue, but it is my first time doing so.
Thank you for your effort, by the way -- certainly more enjoyable than going through the chapter-by-chapter PDFs.

EDIT:

Found a few similar issues on the same chapter, in the "The Impact of the Display Adapter Cycle-Eater" section.

Even on the EGA and VGA, the effect of the display adapter cycle-eater depends on the display mode selected. In text mode, the display adapter cycle-eater is rarely a major factor. It’s not that the cycle-eater isn’t present; however, a mere 4,000 bytes control the entire text mode display, and even with the display adapter cycle-eater it just doesn’t take that long to manipulate 4,000 bytes. Even if the display adapter cycle-eater were to cause the 8088 to take as much as 5µs per display memory access—more than five times normal—it would still take only 4,000x 2x 5µs, or 40 µs

The "40µs" should be ms, and also:

For example, if we assume the same 5 µs per display memory access for the EGA’s high-resolution graphics mode that we assumed for text mode, it would take 26,000 x 2 x 5 µs, or 260 µs

Same thing for the "260 µs".

Missing Chapters A through K from the CD

This version is missing the extra chapters that were included on the CD that came with the book.

Image 13-01.jpg is too low resolution to be readable.

This may have been captured at too low a resolution.

Or it's from the chapters on the Life game.

many code listings do not assemble or compile in current chapter*.md files

There are what appear to be various transcription errors (incorrect or bad characters substituted).
Sometimes symbols have disappeared. Sometimes whitespace has been incorrectly removed causing syntax errors.

some related issues or PRs:
#28
#44

Pandoc fails because it cannot find 69-02.jpg

After gitcloning your project, I ran make epub and started to run into problems. Bash spit out the error pandoc: src/src/images/69-02.jpg: openBinaryFile: does not exist (No such file or directory). I looked at the markdown source and didn't find any errors, the image 69-02.jpg was referenced the same way as the other pictures. I eventually created a src directory within the original src directory and copied the images directory into it. This allowed me to create the book with pandoc, but is a bit of a hack.