Skip to content

Home

Jump to bottom
Martin Henz edited this page Aug 1, 2021 · 103 revisions

SICP JS on the Mac

  • Install Homebrew
  • Install yarn: brew install yarn (This will also install Node.js if it is not already installed.)
  • Make your own PDF as follows:
    • Install LaTeX
    • yarn pdf
    • find the PDF in latex_pdf/sicpjs.pdf
  • Make your own SICP JS comparison edition as follows:
yarn install
yarn split
yarn prepare
yarn try

and now point your browser to http://localhost:8080/

Adapter guidelines

  • Never delete any parts from the original; use SPLIT and SPLITINLINE to mark sections where we deviate from the original. Use XML comments <!-- and --> to comment out original LaTeX index commands, if you don't want to deal with INDEX tags for now.
  • Indicate things that need fixing using an XML comment that contains the word FIXME: <!-- FIXME: whatever needs to be fixed later -->
  • Try to format the XML to fit within 80 character line width.
  • Program SNIPPETs should not be wider than 67 characters.
  • Program SNIPPETs should not contain tab characters.
  • Due to a quirk in the XML processor, exercises must have a LABEL tag as the first child element in XML.

Yarn tools

To get started, call yarn and then yarn install in the sicp folder.

PDF Edition

A PDF edition developed in a nodejs system using latex:

yarn pdf

Exercise solutions are currently not included; add them by removing the comments at the end of javascript/latexContent.js.

EPUB Edition

An EPUB edition developed in a nodejs system using latex and pandoc.

yarn epub

Web Edition

A web edition developed in a nodejs system. This edition is deprecated, replaced by Interactive SICP.

yarn web

Comparison Edition

A split web edition that displays the original and Javascript adaption of the SICP textbook side-by-side.

yarn split

Source Program from the Textbook

Generate all the Source code from the textbook, in a form suitable for running.

yarn js

JSON

Generate JSON files from the source XML files.

yarn json

Progressive Web App

Other functions

  • yarn all: combines yarn pdf/epub/web/split/js
  • yarn format: runs linter prettier on JavaScript files extracted from the textbook
  • yarn clean: removes all generated files
  • yarn prepare: copies all generated files to docs_out
  • yarn svgpdf: converts all SVG files to PDF, for use by LaTeX
  • yarn test: runs all generated JavaScript files using js-slang and checks if the result matches the expected result; optional arguments: chapter section, for example yarn test js_programs/chapter2/section3 only runs test cases of chapter2 section3
  • yarn nodetest: runs all generated JavaScript files using node and checks if the result matches the expected result; optional arguments: chapter section, for example yarn nodetest chapter2 section3 only runs test cases of chapter2 section3
  • yarn try: start local webserver, with docs_out as root; visit localhost:8080 with your browser to see if it all works (run yarn all and yarn prepare first)
  • yarn checktags <argument>: 0 or 1 arguments can be provided. If 0 arguments are provided, checks all XML files for tags which are not valid and print their locations to the console, where valid tags refer to those listed in the file: ./javascript/findBadTags.js. If 1 argument is provided, looks for all instances of the provided argument as a tag name and print their locations to the console.

Textbook Content

Contributing Exercise Solutions

You can contribute to the exercise solutions through "Issues" or "Pull Request"

Documenting our XML

The XML in SICP needs to be documented better. For now, the following serves as a quick reference.

  • INDEX
  • SNIPPET
  • FIGURE
  • SECTION (similar: CHAPTER, SUBSECTION, SUBSUBSECTION)
  • SPLIT & SPLITINLINE
  • COMMENT: can be added anywhere in the text; will displayed only in the comparison edition, and are rendered there in grey. COMMENT makes a "span" element in HTML, meant for inline comments.
  • WEB_ONLY: can be added anywhere in the text; will only go in the web editions (JS and split). To get the right color-coding in the comparison edition, WEB_ONLY needs to be inside of SPLIT tags. WEB_ONLY makes a "div" element in HTML, meant for paragraphs.
  • PDF_ONLY: can be added anywhere in the text; will only go in the PDF edition. Content shows up inline in the PDF. (currently rendered using a DIV paragraph in the comparison edition)
  • EXERCISE: mark a textbook exercise; must have a LABEL tag as their first element.
  • QUOTE: put the content inside of a pair of double quotation marks.
  • BLOCKQUOTE: set the content apart from the rest to be identifiable as a quotation.
  • SOLUTION: add a solution to an EXERCISE; must be inside of the EXERCISE tag that it refers to.
  • LABEL: have a NAME attribute so that other sections can refer with a REF tag to the element that has the LABEL.
  • REF: have a NAME attribute to refer to elements that are tagged with LABEL.
  • META: within <SNIPPET><JAVASCRIPT>...</JAVASCRIPT></SNIPPET> and in normal text, this will produce an italics font intended for meta variables. <META> elements must not enclose any other elements. No math allowed in <META>.
  • METAPHRASE: within <SNIPPET><JAVASCRIPT>...</JAVASCRIPT></SNIPPET> and in normal text, this will produce an italics font within angle brackets, intended for meta-level phrases. <METAPHRASE> elements may include <JAVASCRIPTINLINE> elements, but no other elements. No math allowed in <METAPHRASE>.
  • JAVASCRIPTINLINE: will render the enclosed string as program syntax. <JAVASCRIPTINLINE> elements must not enclose any other elements. The element may enclose the characters {, }, %, and $, all rendered literally. In addition, the content of <JAVASCRIPTINLINE> must not start with a blank character.
  • SCHEMEINLINE: same as JAVASCRIPTINLINE
  • SPACE adds a non-breaking space.
  • FIXED_SPACE adds a non-breaking space in the same formatting as JAVASCRIPTINLINE.
  • SHORT_SPACE adds a very small break inside JAVASCRIPT or SCHEME in a SNIPPET and allows, but tries not to have, a page break in that space.
  • SHORT_SPACE_AND_ALLOW_BREAK like SHORT_SPACE but suggests the break as a good place for a page break if one is needed close by.
  • HYP inserts a - in PDF and is ignored otherwise
  • TABLE, TR, TD: as usual in HTML; spacing: 1.5 lines; in addition:
  • TR DOUBLESPACE="yes": use double spacing before this row
  • TR SINGLESPACE="yes": use single spacing before this row

Page breaking

  • In <PDF_ONLY>, we can use \begin{ABSOLUTELYNOPAGEBREAK} ... \end{ABSOLUTELYNOPAGEBREAK} to prevent a page break. This is not a great way, but serves as documentation for now. When this command introduces white space or break things, better document unwanted page breaks with a FIXME.

Policy on Issues and PRs

Open Issues and PRs should be actionable. When we decide to postpone an Issue or PR, it can be closed but should remain marked with the label _postponed. After a major milestone (a semester) we will re-visit postponed Issues and PRs and re-open them.

Clone this wiki locally