sarabander / sicp

HTML5/EPUB3 version of SICP

SICP

This is a new HTML5 and EPUB3 version of "Structure and Interpretation of Computer Programs" by Abelson, Sussman, and Sussman. It comes from the lineage of Unofficial Texinfo Format that was converted from the original HTML version at The MIT Press.

In EPUB3 format: sicp.epub

For online reading: HTML book

Modern solutions such as scalable vector graphics, mathematical markup with MathML and MathJax, embedded web fonts, and syntax highlighting are used. Rudimentary scaffolding for responsive design is in place, which adapts the page for viewing on pocket devices and tablets. More tests on small screens are needed to adjust the font size and formatting, so I encourage feedback from smartphone and tablet owners.

Source

The root directory contains the Texinfo source in sicp-pocket.texi. To recreate the HTML files and build EPUB, enter:

$ make

All the files in html directory, but not in subdirectories, will be overwritten, so the preferred place to make changes is sicp-pocket.texi. The EPUB file will be created in the parent directory, outside of the project tree.

You will need Texinfo 5.1, Perl 5.12 or later, Ruby 1.9.3 or newer, Nokogiri gem, PhantomJS, and Internet connection to compile the book.

Acknowledgements

• Lytha Ayth
• Neil Van Dyke
• Gavrie Philipson
• Li Xuanji
• J. E. Johnson
• Matt Iversen
• Eugene Sharygin

License

The source file sicp-pocket.texi, HTML content of the book, and diagrams in directory html/fig are licensed under Creative Commons Attribution-ShareAlike 4.0 International License (cc by-sa).

Most of the scripts are licensed under GNU General Public License version 3 (for details, see LICENSE.src).

Fonts are under SIL Open Font License version 1.1. Other files, like Javascript libraries, have their own licenses.

Sister project

A PDF version built from LaTeX source accompanies this HTML version.

sicp's Issues

Keyboard navigation

Arrows, Ctrl+arrows, hjkl - none work 😟

Japanese and Japanese-English version?

This is a copy of sarabander/sicp-pdf#38 but for an online setting.

Use of obsolete Texinfo setshortcontentsaftertitlepage command

Hello,

Since Texinfo 7, setshortcontentsaftertitlepage is no longer available, and causes the build to fail with:

sicp-pocket.texi:117: unknown command `setshortcontentsaftertitlepage'

It can simply be remove. See https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Obsolete-_0040_002dCommands.html.

Thank you!

Favicon

The book is looking great, one thing is missing, the favicon. You can generate cross-platform favicon using http://realfavicongenerator.net/

Store references.xhtml in bibtex format

The resulting references.bib is then to be transformed to html via bib2xhtml or bibbase.
Why: bibtex is more machine-parseable.

Edit: add why

Headings as a link

Hi, it would be great to have a headings as a links (or maybe the chapter number) in a web version so I can bookmark the chapter where I've left.

I don't know how to do it in LaTeX, but if you give me a hint, I can make a PR.

Could someone explain the versioning logic?

Specifically, why drop the name of the editor of the version yours was based on and leave just the version number? How do you then know the exact version the edit was based on?

Also, is there a list of all available versions somewhere (not just of this project)?

Edit: Never mind, I've just noticed the history comments in the original sicp.texi.

MathML on Firefox renders too high

I'm experiencing the following on Firefox 63.0 on Arch Linux:

https://i.imgur.com/D39YePh.png

https://i.imgur.com/gWCakyj.png

So, it looks like the MathML math is getting rendered super high. On chrome, it appears that rendering is done with MathJax.

I'm not sure sure if this is an unfixable thing with Firefox, but if it is, maybe the page should just use MathJax on Firefox too? For what it's worth, StackExchange Mathematics uses MathJax on both Chrome and Firefox, and renders identically on both.

superscripts not rendered.

Exercise 1.7 Here -

x = the y such that y ≥ 0 and y 2 = x .

I believe you want a super script 2, but it is not rendered as such for me using Chrome 35 on Windows.

Same issue in Exercise 1.8

epub rendered very poorly on kobo touch -- sides margins

Hello,

As of subject, I am trying to read the SICP book on my kobo touch.

Unluckily, pages are rendered in an unfortunate manner: small font, margin on both sides.

Basically, the ePub renders as if it was an html page poorly styled.

My fix has been to convert it to mobi and then back to epub using calibre, but it would be nice to have an epub version that renders just right.

Thanks for your time and dedication,

Emanuele

Massive Text

The text is massive in the epub version.

I use Apple iBooks as my epub reader. Even at the smallest font setting, each page is only 45 characters wide, which is extremely unpleasant to read. Ideally, each page would be between 60 and 80 characters wide. I've included a screenshot showing SICP alongside The Swift Programming Language at the same display settings. Swift looks as expected; the text is a little too small but I can increase the size. On the other hand, SICP is still quite large and I can't reduce the font size further.

I don't know anything about the epub format, so I have no idea if this could even be changed. But if possible, halving the font size would be greatly appreciated.

Provide Dockerfile build environment

It might be nice for those who want to build themselves without having to install the dependencies (thoughtfully listed in the README), and who are Docker users, to have a Dockerfile that will provide a build environment.

For the way I am thinking it might be implemented, the only code to add would be a "Dockerfile" file and a special make target. The target would build the docker container environment, mount the current directly into it, and run make inside.

I can work on this and open a PR if it sounds useful.

How can I read it online?

You should create a git page for this project.

Incorrect image(fig. 5.11)

At fig. 5.11 there is an extra arrow with a push-button from reg. n to reg. val.
The controller sequence below does not feature this kind of assignment at all.
The original html-version also has this arrow. I believe it accidentally made its way into the figure as the next fib example has exactly this assignment.

Footnotes are cut out at 47 at the end of section 1.2

In the web version, there are actually 48 footnotes in section 1.2, but in the epub version footnote 47 is cut in half and footnote 48 is missing, with the next page being start of section 1.3

Fulltext search

A minified version of http://elasticlunr.com/ could be used for in-browser search.
This:

1. obsoletes the dead-tree notion of search in https://github.com/sarabander/sicp/blob/master/html/Term-Index.xhtml.
2. can be upgraded to accommodate analogy arithmetic, if any word embedding scheme is used.

e: s/index/Term-Index/

Incorrect images in Chapter 2

Problem with images

Figures 2.9 and 2.14 are incorrect and do not reflect the code in the book, or the original images.

Compare this repository's Figure 2.9 and the original.

We can see here that the limit is not interpreted in the same way, with this repo's images having more instances of the original picture than the book's images.

Compare this repository's Figure 2.14 and the original.

We can see that for example, the (right-split rogers 4) example in the book has 5 image layers, while this repository's example has 6. This is especially obvious with the corner-split examples, as the top-right corner is quite different in style.

Note on correctness

I think that this repository's images better reflect the intent of the square-limit idea. However, they do not match the code and are not a faithful representation of the original work, so should be replaced.

Can't locate Texinfo/Convert/Texinfo.pm

I can't manage to build the epub myself and it seems the epub at https://github.com/sarabander/sicp-epub/ is not up-to-date.

$ make
Converting Texinfo file to HTML...Can't locate Texinfo/Convert/Texinfo.pm in @INC (you may need to install the Texinfo::Convert::Texinfo module) (@INC contains: lib /usr/local/share/texinfo/lib/Text-Unidecode/lib /usr/local/share/texinfo/lib/Unicode-EastAsianWidth/lib /usr/local/share/texinfo/lib/libintl-perl/lib /usr/local/share/texinfo /usr/local/lib64/perl5/5.30 /usr/local/share/perl5/5.30 /usr/lib64/perl5/vendor_perl /usr/share/perl5/vendor_perl /usr/lib64/perl5 /usr/share/perl5) at ./texi2any line 102.
BEGIN failed--compilation aborted at ./texi2any line 102.
make: *** [Makefile:52: html/index.xhtml] Error 2

I'm on Fedora 31. I can't find this module anywhere.

Shortcut Support for navigating in between the different sections

We find it somewhat difficult to move our mouse.

And it would be great if we had some keyboard shortcut ( maybe right arrow and left arrow) to turn to next section or previous section

Problem building on Ubuntu 19.04 - DebugCount.pm no longer part of texinfo

I am unable to build on Ubuntu disco as the module DebugCount.pm has disappeared in the version of texinfo that comes with Ubuntu 19.04.

Please let me know if this just a "me being a n00b issue". Don't really have a ton of experience building things like this from scratch.

Pre-generated EPUB, both packed and exploded versions please (hosted in GitHub's gh-pages)

Hello, thank you very much maintaining this.
The DropBox link is handy ( https://www.dropbox.com/s/y9jt5kmabt02yg8/sicp.epub?dl=0 ), but it appears to be currently out of date:
Unofficial Texinfo Format 2.andresraba6.5 (January 29, 2015)
...compared to the online version ( http://sarabander.github.io/sicp/html/index.xhtml ):
Unofficial Texinfo Format 2.andresraba6.6

Furthermore, I would like to be able to link directly from the Readium EPUB "cloud" reader into the sicp.epub zip file, or even better: into the exploded (unzipped) version of the EPUB. DropBox will not allow this, unless the "public web pages" feature is activated. Conversely, GitHub is very handy for this, as we can simply use the gh-pages branch to publish content online. Just as you currently do with the HTML5 version of SICP:
http://sarabander.github.io/sicp/
=>
https://github.com/sarabander/sicp/tree/gh-pages

So, could you please pre-compile and commit+push the ready-to-use flavours of the EPUB content? Many thanks!!

PS: I tried to compile the EPUB myself using the Makefile, to no avail.

Doesn't work with Play Books, not rendered properly with Moon+ Reader Pro

I have 2 ebook readers on my Android phone: Play Books and Moon+ Reader Pro.
Previously, I have never experienced problem with Play Books. Just upload the epub file via the web interface and eventually your book will appear in Play Books. But not with this one. Play Books won't process it.

On the other hand, Moon+ Reader Pro seems to be able to display it. But, the figures are not rendered properly.This is just a quick gazing anyway, because I haven't finished reading the book.

For example, figure 3.28

Some characters not being read by screen reading software on 3.5.3

This is a really small issue. But maybe you'd like to know about it.

Background: I am blind so I am using a screen reading software called JAWS (Job Access with Speech) and NVDA (non-visual desktop access). They are softwares that reads texts from the screen.

Now, in section 3.5.3, there is a procedure called euler-transform. euler-transform has comments. This is how they are being read.

(define (euler-transform s)
(let ((s0 (stream-ref s 0)) ; S question mark question mark ₁
(s1 (stream-ref s 1)) ; S question mark
(s2 (stream-ref s 2))) ; S question mark question mark ₁
(cons-stream
(- s2 (/ (square (- s2 s1))
(+ s0 (* -2 s1) s2)))
(euler-transform (stream-cdr s)))))

I am not sure, but "question mark question mark" doesn't make sense at all. By reading and understanding the code, I think the real characters are:

(let ((s0 (stream-ref s 0)) ; Sn-₁
(s1 (stream-ref s 1)) ; Sn
(s2 (stream-ref s 2))) ; Sn+₁

It's not really a big deel because those are just comments, but I just find it wierd that the characters are being read like that while all the other "+", "-", "n" and even the mathjax rendering are being read correctly. Are these "question mark" type characters being displayed differently?

Justify the text

IMHO long texts look better justified. This can be enabled with

text-align: justify;

SVG images don't render if ePub converted to Mobi

I am trying to read the book using my Kindle Paperwhite (which doesn't support ePub), but the converted book just shows SVG in place of each image in the book.

I have tried experimenting a lot with different conversion tools -- Calibre, kindlegen, Kindle Previewer -- but to no avail.

With kindlegen I figured that this is because <object> tag is not supported by it:

Warning(inputpreprocessor):W29007: Rejected unknown tag: <object data="html/fig/coverpage.std.svg" type="image/svg+xml">
      in file: /var/folders/j2/3hbhcfdd2d9b2dmvcyq4g9040000gn/T/mobi-6Ttufx/index.xhtml     line: 0000060

From Amazon Kindle Publishing Guidelines:

3.6.11 Image Guideline #11: Use Supported SVG Tags and Elements

A publisher can reference the SVG files from within an HTML file using inline <svg>, <img>, <embed>, or <object> tags. Please refer to the SVG specification http://www.w3.org/TR/SVG/ for details about SVG.

Example

<html>
<body>
<svg xmlns="http://www.w3.org/2000/svg"><!—Inline SVG--></svg>
<img src="svgfile1.svg"/>
<embed src="svgfile2.svg"/>
<object src="svgfile3.svg"/>
</body>
</html>

According to last example, this problem might just be because of using data instead of src attribute of <object>.

I am no expert but I am experimenting using Sigil to convert the tags to one of these. If I succeed, I will provide a patch.

Footnotes at the end of chapter 1 are missing

It appears that the footnotes 26, 27, and 28 at the end of chapter one are missing.

Per the MIT HTML5 version of the book, the footnotes are:

25 The concept of consistent renaming is actually subtle and difficult to define formally. Famous logicians have made embarrassing errors here.

27 Lexical scoping dictates that free variables in a procedure are taken to refer to bindings made by enclosing procedure definitions; that is, they are looked up in the environment in which the procedure was defined. We will see how this works in detail in chapter 3 when we study environments and the detailed behavior of the interpreter.

28 Embedded definitions must come first in a procedure body. The management is not responsible for the consequences of running programs that intertwine definition and use.

tiny images, missing text above

I'm reading the ePUB version on Kobo. images, including the cover, are tiny.

after a page-break, all text preceding a figure is missing.

Is it possible to generate a single html page version of the book?

Aiming and clicking the next section link repeatedly is a little bit tedious

Code isn't highlighted when opened in Books on an iPad

So I'm desperately looking for an ebook reader that can chew through this book, but as for now only one reader that kinda sorta does it is, unexpectedly, Microsoft Edge. Whodathunkit.

It lags, it does everything very slow, margins are very wide, but nevertheless Edge handles rendering of the text itself pretty much ok.

I got back my old iPad mini 2, tried to open this epub in Books, expecting to see perfect rendering and super smooth operation, but no, the tablet immediately started heating up. Page turns lag for about .5-1 sec and there's no code highlighting.

Here's a comparison photo between Edge and Books.

Can the code highlighting be fixed? Or maybe you can recommend a decent reader which doesn't look like butt and can render all the nice things you put in here. iOS preferred, but UWP apps and even Android are ok, I have a large zoo of different devices.

And maybe the SVG graphs can be generated using white stroke for better legibility on dark background, but that's something I can live with.

Revert recent case twiddling?

Thank you for a wonderful, portable version of SICP!

I noticed two commits in the past year that change two (single) occurrences of symbols beginning a sentence to lowercase:

• 68dd959 changed else keyword to lower case
• 382b325 Fix [:disappointed:] good-enough? case

However, capitalisation is done throughout the book:

• “Not is an ordinary procedure.”
• “Average-damp is a procedure [...] Using average-damp, we can [...]”

Scheme itself isn't case-sensitive, so this makes sense. There are implementations that are. I can see how someone might have typed Else into their REPL, got an error thrown back, and fired off a well-meaning PR.

Even so, going against the obvious intentions of the authors of both the book and the language is quite... invasive.

If (since?) this version is considered to be a modernised rendering of the original, and not an editorial fork, I'd like to request reverting the above changes to match both ‘upstream’ and the rest of the book.

typo on Third Addendum

s/Techical/Technical/

Failing epub validation

Validation of sicp.epub fails with the message

ACC-009 (WARNING) Message: MathML should either have an 'alttext' attribute or 'annotation-xml' child element.

Tested on https://www.epubconversion.com.

Also uploading and conversion of the epub file to Google Books fails due to unspecified error. It could very well be this error.