Skip to content

Commit 0603e83

Browse files
ibrahimcesaribrahimcesar
committed
Merge main - resolved conflicts
2 parents 5bf36e1 + 40bd730 commit 0603e83

86 files changed

Lines changed: 10482 additions & 1310 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎MISSING_IMAGES.md‎

Lines changed: 277 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,277 @@
1+
# Pages Missing Images - SICP JavaScript Translation
2+
3+
## Executive Summary
4+
5+
This report tracks figures/diagrams in the SICP JavaScript translation. Many missing diagrams have been implemented using Mermaid.js for inline rendering.
6+
7+
**Status Update:**
8+
- ✅ **25 diagrams implemented** (17 Mermaid.js + 7 React Components + 2 downloaded SVGs)
9+
- ✅ **All tracked diagrams complete!**
10+
- 📊 **Total figures tracked:** 25+
11+
12+
---
13+
14+
## Chapter 3: Modularity, Objects, and State
15+
16+
### 3.3.1 Mutable List Structure ✅ COMPLETE
17+
**File:** `docs/chapter-3/3.3.1.mdx`
18+
**Implemented with Mermaid.js (6):**
19+
- **Figure 3.12** ✅ - Initial box-and-pointer diagram showing lists x and y
20+
- **Figure 3.13** ✅ - Effect of `set_head(x, y)` operation
21+
- **Figure 3.14** ✅ - Effect of `const z = pair(y, tail(x))` operation
22+
- **Figure 3.15** ✅ - Effect of `set_tail(x, y)` operation
23+
- **Figure 3.16** ✅ - Sharing structure in `z1`
24+
- **Figure 3.17** ✅ - Alternative structure created by different operations
25+
26+
**Implementation:** Box-and-pointer diagrams using Mermaid graph syntax with color-coded nodes.
27+
28+
---
29+
30+
### 3.3.2 Representing Queues ✅ COMPLETE
31+
**File:** `docs/chapter-3/3.3.2.mdx`
32+
**Implemented with Mermaid.js (3):**
33+
- **Figure 3.18** ✅ - Queue representation with `front_ptr` and `rear_ptr` pointers
34+
- **Figure 3.19** ✅ - Result of `insert_queue` operation showing pointer modifications
35+
- **Figure 3.20** ✅ - Result of `delete_queue` operation showing pointer modifications
36+
37+
**Implementation:** Queue diagrams using Mermaid showing pointer manipulations with labels and color coding.
38+
39+
---
40+
41+
### 3.3.3 Representing Tables ✅ COMPLETE
42+
**File:** `docs/chapter-3/3.3.3.mdx`
43+
**Implemented with Mermaid.js (2):**
44+
- **Figure 3.21** ✅ - Box-and-pointer diagram of a one-dimensional table
45+
- **Figure 3.22** ✅ - Box-and-pointer diagram of a two-dimensional table with subtables
46+
47+
**Implementation:** Table structures showing headed lists (1D) and nested subtables (2D) using Mermaid.
48+
49+
---
50+
51+
### 3.3.4 Digital Circuit Simulator ✅ COMPLETE
52+
**File:** `docs/chapter-3/3.3.4.mdx`
53+
**Implemented with React Components (3):**
54+
- **Figure 3.25** ✅ - Half-adder circuit diagram
55+
- **Figure 3.26** ✅ - Full-adder circuit diagram
56+
- **Figure 3.27** ✅ - Ripple-carry adder circuit diagram
57+
58+
**Implementation:** Custom SVG-based React component (`src/components/CircuitDiagram`) with interactive logic gate visualizations. Includes AND, OR, XOR gates with proper wire routing and signal labels.
59+
60+
---
61+
62+
### 3.3.5 Constraint Propagation ✅ COMPLETE
63+
**File:** `docs/chapter-3/3.3.5.mdx`
64+
**Implemented with Mermaid.js (1):**
65+
- **Figure 3.28** ✅ - Constraint network diagram for Celsius-Fahrenheit temperature converter
66+
67+
**Implementation:** Flowchart showing constraint boxes (multipliers, adders, constants) connected by connectors with color-coded styling.
68+
69+
---
70+
71+
### 3.5.3 Exploiting the Stream Paradigm ✅ COMPLETE
72+
**File:** `docs/chapter-3/3.5.3.mdx`
73+
**Implemented with React Components (1):**
74+
- **Figure 3.53** ✅ - RC integrator signal flow diagram
75+
76+
**Implementation:** Custom SignalFlowDiagram component showing signal processing with integrators, multipliers, and feedback loops.
77+
78+
---
79+
80+
### 3.5.4 Streams and Delayed Evaluation ✅ COMPLETE
81+
**File:** `docs/chapter-3/3.5.4.mdx`
82+
**Implemented with React Components (3):**
83+
- **Figure 3.54** ✅ - Feedback loop for solving dy/dt = f(y)
84+
- **Figure 3.78** ✅ - Coupled differential equations system
85+
- **Figure 3.80** ✅ - RLC circuit diagram (resistor, capacitor, inductor in series)
86+
87+
**Implementation:** Custom SVG-based React component (`src/components/SignalFlowDiagram`) with signal processing blocks (integrator ∫, multiplier ×, adder +), electronic components (R, L, C), and feedback loop visualization with dashed lines.
88+
89+
---
90+
91+
## Chapter 4: Metalinguistic Abstraction
92+
93+
### 4.1 The Metacircular Evaluator ✅ COMPLETE
94+
**File:** `docs/chapter-4/4.1.md`
95+
**Implemented with Mermaid.js (1):**
96+
- **Figure 4.1** ✅ - Eval-apply cycle diagram
97+
98+
**Implementation:** Flowchart showing the circular relationship between `evaluate` and `apply` with base cases.
99+
100+
---
101+
102+
### 4.1.2 Representing Expressions ✅ COMPLETE
103+
**File:** `docs/chapter-4/4.1.2.mdx`
104+
**Implemented with Mermaid.js (1):**
105+
- **Abstraction barrier diagram** ✅ - Shows syntax abstraction layers
106+
107+
**Implementation:** Flowchart showing three layers (Evaluator, Tagged List Representation, String Representation) separated by two abstraction barriers (predicates/selectors and parse function).
108+
109+
---
110+
111+
### 4.1.5 Data as Programs ✅ COMPLETE
112+
**File:** `docs/chapter-4/4.1.5.mdx`
113+
**Implemented with Mermaid.js (2):**
114+
- **Figure 4.2** ✅ - Factorial program as abstract machine
115+
- **Figure 4.3** ✅ - Evaluator emulating factorial machine
116+
117+
**Implementation:**
118+
- Figure 4.2: Flowchart showing factorial as a machine with decrement, multiply, equality test components and recursive factorial machine
119+
- Figure 4.3: Flowchart showing the universal evaluator containing the emulated factorial machine from Figure 4.2
120+
121+
---
122+
123+
### 4.4.4 Implementing the Query System ✅ COMPLETE
124+
**File:** `docs/chapter-4/4.4.4.mdx`
125+
**Downloaded from Upstream (2):**
126+
- **Figure 4.5** ✅ - `/img/chapter-4/Fig4.5.svg` - Processing of AND queries with frame streams
127+
- **Figure 4.6** ✅ - `/img/chapter-4/Fig4.6.svg` - Processing of OR queries with frame streams
128+
129+
**Status:** Downloaded from source-academy/sicp repository and integrated into the documentation with appropriate `<Figure>` tags.
130+
131+
---
132+
133+
## Summary by Chapter
134+
135+
| Chapter | Section | Status | Figures | Priority |
136+
|---------|---------|--------|---------|----------|
137+
| 3.3.1 | Mutable Lists | ✅ Complete | 6 Mermaid | High |
138+
| 3.3.2 | Queues | ✅ Complete | 3 Mermaid | High |
139+
| 3.3.3 | Tables | ✅ Complete | 2 Mermaid | High |
140+
| 3.3.4 | Digital Circuits | ✅ Complete | 3 React Components | High |
141+
| 3.3.5 | Constraints | ✅ Complete | 1 Mermaid | High |
142+
| 3.5.3 | Streams | ✅ Complete | 1 React Component | Medium |
143+
| 3.5.4 | Delayed Evaluation | ✅ Complete | 3 React Components | Medium |
144+
| 4.1 | Evaluator | ✅ Complete | 1 Mermaid | High |
145+
| 4.1.2 | Syntax | ✅ Complete | 1 Mermaid | Medium |
146+
| 4.1.5 | Data as Programs | ✅ Complete | 2 Mermaid | High |
147+
| 4.4.4 | Query System | ✅ Complete | 2 SVG (downloaded) | Medium |
148+
| **TOTAL** | **13 pages** | **13 complete** | **25 done, 0 todo** | |
149+
150+
---
151+
152+
## Recommended Next Steps
153+
154+
1. **Create missing directory:**
155+
```bash
156+
mkdir -p static/img/chapter-4
157+
```
158+
159+
2. **Source images from original SICP.js:**
160+
- Many of these figures likely exist in the [source SICP JS repository](https://github.com/source-academy/sicp)
161+
- Can be adapted from [HTML5/EPUB3 version](https://github.com/sarabander/sicp)
162+
163+
3. **Priority order for image creation:**
164+
- **Priority 1:** Chapter 3.3.x diagrams (most critical for understanding data structures)
165+
- **Priority 2:** Chapter 4.1.x diagrams (essential for evaluator comprehension)
166+
- **Priority 3:** Chapter 3.5.x diagrams (signal processing concepts)
167+
168+
4. **Image format:**
169+
- Prefer SVG format (scalable, matches existing images)
170+
- Use consistent naming: `ch[N]-Z-G-[num].svg` or `Fig[N].[num].svg`
171+
172+
---
173+
174+
## Image Organization
175+
176+
The image directory structure has been standardized to a consistent `chapter-N/` pattern:
177+
178+
### Current Structure ✅
179+
```
180+
static/img/
181+
├── chapter-1/ # 5 images (complete)
182+
│ └── ch1-*.svg
183+
├── chapter-2/ # 5 images (complete)
184+
│ └── ch2-*.svg
185+
├── chapter-3/ # 13 images (partial - 16+ missing)
186+
│ └── ch3-*.svg, Fig3.*.svg
187+
├── chapter-4/ # 0 images (directory created, awaiting images)
188+
│ └── (empty - all images missing)
189+
└── chapter-5/ # 5 images (partial - more needed)
190+
└── ch5-*.svg, Fig5.*.svg, *.png
191+
```
192+
193+
All markdown references have been updated to use the new paths.
194+
195+
---
196+
197+
## Implementation Summary
198+
199+
### What Was Implemented
200+
201+
Successfully implemented **25 diagrams** using multiple techniques:
202+
203+
**Chapter 3.3 - Data Structures (15 diagrams):**
204+
- ✅ Figures 3.12-3.17: Mutable list structures with box-and-pointer notation (Mermaid)
205+
- ✅ Figures 3.18-3.20: Queue operations showing front/rear pointer management (Mermaid)
206+
- ✅ Figures 3.21-3.22: Table structures (1D and 2D with subtables) (Mermaid)
207+
- ✅ Figures 3.25-3.27: Digital circuit diagrams - half-adder, full-adder, ripple-carry adder (React Component)
208+
- ✅ Figure 3.28: Constraint network for Celsius-Fahrenheit converter (Mermaid)
209+
210+
**Chapter 3.5 - Streams (4 diagrams):**
211+
- ✅ Figure 3.53: RC integrator signal flow diagram (React Component)
212+
- ✅ Figure 3.54: Feedback solver for dy/dt = f(y) (React Component)
213+
- ✅ Figure 3.78: Coupled differential equations system (React Component)
214+
- ✅ Figure 3.80: RLC circuit with resistor, capacitor, inductor (React Component)
215+
216+
**Chapter 4.1 - Evaluator (5 diagrams):**
217+
- ✅ Figure 4.1: Eval-apply cycle flowchart (Mermaid)
218+
- ✅ Abstraction barrier diagram (4.1.2): Syntax representation layers (Mermaid)
219+
- ✅ Figure 4.2: Factorial program as abstract machine (Mermaid)
220+
- ✅ Figure 4.3: Evaluator as universal machine emulating factorial (Mermaid)
221+
222+
**Chapter 4.4 - Query System (2 diagrams - downloaded SVG):**
223+
- ✅ Figure 4.5: AND query processing with frame streams (SVG from upstream)
224+
- ✅ Figure 4.6: OR query processing with frame streams (SVG from upstream)
225+
226+
### Implementation Technologies
227+
228+
**Mermaid.js (17 diagrams):**
229+
- No external files - diagrams defined directly in markdown
230+
- Version controlled - changes tracked as text in git
231+
- Easy to update - community can edit without image tools
232+
- Consistent styling - unified visual appearance
233+
234+
**React Components (7 diagrams):**
235+
- Custom SVG-based interactive diagrams
236+
- `CircuitDiagram` component in `src/components/CircuitDiagram/`
237+
- Supports AND, OR, XOR, NOT logic gates
238+
- Configurable circuits: half-adder, full-adder, ripple-carry-adder
239+
- `SignalFlowDiagram` component in `src/components/SignalFlowDiagram/`
240+
- Signal processing blocks: integrator (∫), multiplier (×), adder (+), gain, constant
241+
- Electronic components: resistor (R), capacitor (C), inductor (L)
242+
- Configurable diagrams: rc-integrator, feedback-solver, rlc-circuit, differential-system
243+
- Feedback loop visualization with dashed lines
244+
- Dark mode support and responsive design for all components
245+
246+
**Downloaded SVGs (2 diagrams):**
247+
- Source: source-academy/sicp repository
248+
- Placed in `static/img/chapter-4/`
249+
250+
### Benefits of Mermaid
251+
252+
1. **No external files** - diagrams defined directly in markdown
253+
2. **Version controlled** - changes tracked as text in git
254+
3. **Easy to update** - community can edit without image tools
255+
4. **Consistent styling** - unified visual appearance
256+
5. **Accessible** - better than static images for screen readers
257+
258+
### Configuration
259+
260+
Mermaid support enabled in `docusaurus.config.js`:
261+
```javascript
262+
markdown: {
263+
mermaid: true,
264+
},
265+
themes: ['@docusaurus/theme-mermaid'],
266+
```
267+
268+
Package installed: `@docusaurus/theme-mermaid@3.9.2`
269+
270+
---
271+
272+
## Notes
273+
274+
- All existing Chapter 1, 2, 3 (partial), and 5 (partial) images are present and working
275+
- The original SICP book contains all these diagrams, they just need to be converted/adapted to JavaScript syntax
276+
- Mermaid is excellent for data structures but complex circuits/signal diagrams may need SVG or React components
277+
- Consider sourcing remaining images from upstream repositories that have already adapted SICP figures for JavaScript

‎docs/chapter-1/1.1.3.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ Observe como a ideia de recursão pode ser usada sucintamente para expressar o q
2222
requer que a regra de avaliação seja aplicada a quatro combinações diferentes. Podemos obter uma imagem desse processo representando a combinação na forma de uma árvore, conforme mostrado na figura [1.1](#fig-1.1). Cada combinação é representada por um nó com ramificações correspondentes ao operador e aos operandos da combinação que dele decorrem. Os nós terminais (ou seja, nós sem ramificações derivadas deles) representam operadores ou números. Vendo a avaliação em termos de árvore, podemos imaginar que os valores dos operandos percolam para cima, começando nos nós terminais e depois combinando em níveis cada vez mais altos. Em geral, veremos que a recursão é uma técnica muito poderosa para lidar com objetos hierárquicos semelhantes a árvores. Na verdade, a forma de "filtrar os valores para cima" da regra de avaliação é um exemplo de um tipo geral de processo conhecido como `acumulação de árvore`.
2323

2424
<a name="fig-1.1"></a>
25-
![#fig-1.1](/img/ch1-expression-tree.svg)
25+
![#fig-1.1](/img/chapter-1/ch1-expression-tree.svg)
2626

2727
Figura 1.1 Representação em árvore, mostrando o valor de cada subexpressão.
2828

‎docs/chapter-1/1.1.8.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ A função `sqrt` é nosso primeiro exemplo de um processo definido por um conju
88
Observe que o problema de calcular raízes quadradas se divide naturalmente em vários subproblemas: como saber se uma estimativa é boa o suficiente, como melhorar uma estimativa e assim por diante. Cada uma dessas tarefas é realizada por uma função separada. Todo o programa `sqrt` pode ser visto como um cluster de funções (mostrado na figura 1.2) que reflete a decomposição do problema em subproblemas.
99

1010
<a name="fig-1.2"></a>
11-
![figura-1.2-decomposição-funcional-do-sqrt](/img/ch1-sqrt-decomposition.svg)
11+
![figura-1.2-decomposição-funcional-do-sqrt](/img/chapter-1/ch1-sqrt-decomposition.svg)
1212

1313
Figura 1.2 Decomposição funcional do programa `sqrt`.
1414

‎docs/chapter-1/1.2.1.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ Assim, podemos calcular $n!$ calculando $(n-1)!$ e multiplicando o resultado por
2929

3030
Podemos usar o modelo de substituição da seção 1.1.5 para observar esta função em ação calculando $6!$, como mostrado na figura abaixo.
3131

32-
![Um processo recursivo linear para calcular 6!](/img/ch1-Z-G-7.svg)
32+
![Um processo recursivo linear para calcular 6!](/img/chapter-1/ch1-Z-G-7.svg)
3333

3434
*Figura: Um processo recursivo linear para calcular 6!.*
3535

@@ -64,7 +64,7 @@ function fact_iter(product, counter, max_count) {
6464

6565
Como antes, podemos usar o modelo de substituição para visualizar o processo de calcular $6!$, como mostrado na figura abaixo.
6666

67-
![Um processo iterativo linear para calcular 6!](/img/ch1-Z-G-10.svg)
67+
![Um processo iterativo linear para calcular 6!](/img/chapter-1/ch1-Z-G-10.svg)
6868

6969
*Figura: Um processo iterativo linear para calcular 6!.*
7070

‎docs/chapter-1/1.2.2.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ Podemos traduzir imediatamente esta definição em uma função recursiva para c
2727
showLineNumbers={false}
2828
/>
2929

30-
![O processo recursivo em árvore gerado ao calcular fib(5)](/img/ch1-fibonacci-tree.svg)
30+
![O processo recursivo em árvore gerado ao calcular fib(5)](/img/chapter-1/ch1-fibonacci-tree.svg)
3131

3232
*Figura: O processo recursivo em árvore gerado ao calcular `fib(5)`.*
3333

‎docs/chapter-2/2.1.2.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ import HelpFooter from '@site/src/components/HelpFooter';
99

1010
Antes de continuar com mais exemplos de dados compostos e abstração de dados, vamos considerar algumas das questões levantadas pelo exemplo de números racionais. Definimos as operações de números racionais em termos de um construtor `make_rat` e seletores `numer` e `denom`. Em geral, a ideia subjacente da abstração de dados é identificar para cada tipo de objeto de dados um conjunto básico de operações em termos das quais todas as manipulações de objetos de dados desse tipo serão expressas, e então usar apenas essas operações na manipulação dos dados.
1111

12-
![Barreiras de abstração de dados no pacote de números racionais](/img/javascript/ch2-Z-G-6.svg)
12+
![Barreiras de abstração de dados no pacote de números racionais](/img/chapter-2/ch2-Z-G-6.svg)
1313

1414
Podemos visualizar a estrutura do sistema de números racionais como mostrado na figura acima. As linhas horizontais representam *barreiras de abstração* que isolam diferentes "níveis" do sistema. Em cada nível, a barreira separa os programas (acima) que usam a abstração de dados dos programas (abaixo) que implementam a abstração de dados. Programas que usam números racionais os manipulam exclusivamente em termos das funções fornecidas "para uso público" pelo pacote de números racionais: `add_rat`, `sub_rat`, `mul_rat`, `div_rat` e `equal_rat`. Estas, por sua vez, são implementadas exclusivamente em termos do construtor e seletores `make_rat`, `numer` e `denom`, que eles mesmos são implementados em termos de pares. Os detalhes de como os pares são implementados são irrelevantes para o resto do pacote de números racionais, desde que os pares possam ser manipulados pelo uso de `pair`, `head` e `tail`. Na prática, as funções em cada nível são as interfaces que definem as barreiras de abstração e conectam os diferentes níveis.
1515

‎docs/chapter-2/2.2.1.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ import HelpFooter from '@site/src/components/HelpFooter';
99

1010
Uma das estruturas de dados úteis que podemos construir com pares é uma *sequência*—uma coleção ordenada de objetos de dados. Existem, é claro, muitas maneiras de representar sequências em termos de pares. Uma representação particularmente direta é ilustrada abaixo, onde a sequência 1, 2, 3, 4 é representada como uma cadeia de pares:
1111

12-
![Sequência 1, 2, 3, 4 como cadeia de pares](/img/javascript/ch2-Z-G-13.svg)
12+
![Sequência 1, 2, 3, 4 como cadeia de pares](/img/chapter-2/ch2-Z-G-13.svg)
1313

1414
O head de cada par é o item correspondente na cadeia, e o tail do par é o próximo par na cadeia. O tail do par final sinaliza o fim da sequência apontando para um valor distinto de qualquer par, que representamos na diagrama de box-and-pointer como um símbolo diagonal e em programas como o valor de `null`. A sequência inteira é construída por operações `pair` aninhadas:
1515

‎docs/chapter-2/2.2.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,11 @@
22

33
Como vimos, os pares fornecem uma "cola" primitiva que podemos usar para construir objetos de dados compostos. A figura abaixo mostra uma maneira padrão de visualizar um par—neste caso, o par formado por `pair(1, 2)`. Nesta representação, que é chamada de *notação box-and-pointer*, cada objeto composto é mostrado como um ponteiro para uma caixa. A caixa para um par tem duas partes, a parte esquerda contendo o head do par e a parte direita contendo o tail.
44

5-
![Representação box-and-pointer de pair(1, 2)](/img/javascript/ch2-Z-G-11.svg)
5+
![Representação box-and-pointer de pair(1, 2)](/img/chapter-2/ch2-Z-G-11.svg)
66

77
Já vimos que `pair` pode ser usado para combinar não apenas números, mas pares também. (Você fez uso desse fato, ou deveria ter feito, ao fazer os exercícios 2.2 e 2.3.) Como consequência, os pares fornecem um bloco de construção universal a partir do qual podemos construir todos os tipos de estruturas de dados. A figura abaixo mostra duas maneiras de usar pares para combinar os números 1, 2, 3 e 4.
88

9-
![Duas maneiras de combinar 1, 2, 3 e 4 usando pares](/img/javascript/ch2-Z-G-12.svg)
9+
![Duas maneiras de combinar 1, 2, 3 e 4 usando pares](/img/chapter-2/ch2-Z-G-12.svg)
1010

1111
A capacidade de criar pares cujos elementos são pares é a essência da importância da estrutura de lista como uma ferramenta representacional. Nos referimos a essa capacidade como a *propriedade de closure* de `pair`. Em geral, uma operação para combinar objetos de dados satisfaz a propriedade de closure se os resultados de combinar coisas com essa operação podem ser combinados usando a mesma operação. Closure é a chave para o poder em qualquer meio de combinação porque nos permite criar estruturas *hierárquicas*—estruturas compostas de partes, que são elas mesmas compostas de partes, e assim por diante.
1212

0 commit comments

Comments
 (0)