Skip to content

Home

Jump to bottom
Ken Jin edited this page May 7, 2023 · 100 revisions

Requirements

  • node (for everything): known working version: v14.17.2
  • latex (for generating the PDF)
    • latexmk: known working version: 4.67
    • pdflatex: known working version: pdfTeX 3.14159265-2.6-1.40.21 (TeX Live 2020), kpathsea version 6.3.2

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/

SICP JS on Ubuntu

The following instructions are tested on Ubuntu 22.04.

  • Install npm and node
  • Install yarn
  • Run the following:
sudo apt install latexmk
# aliases python to python3 for gyp
sudo apt install python-is-python3

# Everything we need to build gl and gl-headless
sudo apt install -y build-essential g++-10 libxi-dev libxext-dev libpixman-1-dev libcairo2-dev libpango1.0-dev libjpeg8-dev libgif-dev libjpeg-dev librsvg2-dev mesa-common-dev

# Yarn install with G++10.
CXX=g++-10 yarn install

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

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. Used by Interactive SICP JS.

yarn json

The JSON files are deployed to https://source-academy.github.io/sicp/json/... and read by the frontend. Example: https://source-academy.github.io/sicp/json/2.2.4.json is loaded by page https://sourceacademy.org/sicpjs/2.2.4.

Test the JSON version by starting a local web server with

yarn tryjson

Then, set the frontend environment .env as follows:

REACT_APP_SICPJS_BACKEND_URL="http://127.0.0.1:8080/"

Now start the frontend by running

yarn start

Point your browser to

http://localhost:8000/sicpjs

to see the JSON version of the textbook.

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
  • SOFT_HYP inserts a soft hyphenation 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
  • EXERCISE_FOLLOWED_BY_TEXT: for adding the right amount of space in this situation.

Pagination

The following commands are available when building a PDF and ignored otherwise:

  • KEEP_TOGETHER tries to keep the paragraph in which the tag appears on a single page by adding penalties for breaking
  • START_KEEP_TOGETHER keeps everything up to the matching STOP_KEEP_TOGETHER in a single unbreakable box. Inside such a box you might have to add a NOINDENT if that is the desired behaviour. Beware: since these commands translate to a box, they must properly nest their LaTeX contennt.
  • SHRINK_PARAGRAPH tries to fit the paragraph in which the tag appears on fewer lines. It takes an optional argument lines="X" whose default value is 1.
  • STRETCH_PARAGRAPH tries to stretch the paragraph in which the tag appears to span more lines. It takes an optional argument lines="X" whose default value is 1.
  • DONT_BREAK_PAGE suggests that this is a bad place for a page break. It takes an optional argument strength="X" whose default value is 4. Legal values are 0-4.
  • DO_BREAK_PAGE suggests that this is a good place for a page break. It takes an optional argument strength="X" whose default value is 4. Legal values are 0-4.
  • FORCE_PAGE_BREAK_AND_FILL clears the page and starts a new page.
  • FILBREAK is a WIP -- if inserted around content to keep together, then breaks will only happen at a place of one of those FILBREAKs if at all.
  • LONG_PAGE -- allows the page to grow by 1 or more lines. It takes an optional argument lines="X" whose default value is 1.
  • SHORT_PAGE -- allows the page to shrink by 1 or more lines. It takes an optional argument lines="X" whose default value is 1.

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