Better docs

docs/specs/Makefile

@@ -6,13 +6,11 @@ SPECS = $(SPECSNUMS:%=source_%)
 
 PDFSPECS = $(SPECS:%=%.pdf)
 
-HELPERS = header bnf comments intro names numbers return strings typing objects arrays interpreter lists array_support loops boolean_operators pair_mutators 1_stepper_rules 
-
 HELPERSTEX = $(HELPERS:%=source_%.tex)
 
 all: $(PDFSPECS)
 
-%.pdf: %.tex $(HELPERSTEX)
+%.pdf: %.tex 
 	$(PDFLATEX) $*
 
 clean:

docs/specs/source_1.tex

@@ -13,21 +13,27 @@
 
 \newpage
 
+\input source_return
+
 \input source_import
 
 \input source_boolean_operators
 
-\input source_return
-
-\input source_names
+\input source_names_lang
 
 \input source_numbers
 
 \input source_strings
 
+\input source_comments
+
 \input source_typing
 
-\input source_comments
+\section{Standard Libraries}
+
+The following library is always available in this language.
+
+\input source_misc
 
 \input source_js_differences
 

docs/specs/source_1_bnf_without_import.tex

@@ -0,0 +1,77 @@
+\begin{alignat*}{9}
+&& \textit{program}    &&\quad ::= &\quad && \textit{statement} \ \ldots
+                                                           && \textrm{\href{https://source-academy.github.io/sicp/chapters/3.1.1.html\#p6}{program}} \\[1mm]
+&& \textit{statement}    &&\quad ::= &\quad && \textbf{\texttt{const}}\  \textit{name} \ 
+                                           \textbf{\texttt{=}}\  \textit{expression} \ \textbf{\texttt{;}}
+                                                           && \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.2.html\#p2}{constant declaration}} \\
+&&                       && |   &\quad && \textbf{\texttt{function}}\  \textit{name} \ 
+                                   \textbf{\texttt{(}}\  \textit{parameters} \ \textbf{\texttt{)}}\ \textit{block} \quad
+                                                           && \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.4.html\#p4}{function declaration}}\\
+&&                       && |   &\quad && \textbf{\texttt{return}}\  \textit{expression} \ \textbf{\texttt{;}}
+                                                           && \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.4.html\#p4}{return statement}}\\
+&&                       && |   &\quad && \textit{if-statement} \quad
+                                                           && \textrm{\href{https://source-academy.github.io/sicp/chapters/1.3.2.html\#p13}{conditional statement}}\\
+&&                       && |   &\quad &&  \textit{block} 
+                                                           && \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.8.html\#p14}{block statement}}\\
+&&                       && |   &\quad &&  \textit{expression} \ \textbf{\texttt{;}}
+                                                           && \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.1.html\#p3}{expression statement}} \\[1mm]
+&& \textit{parameters}   && ::= &\quad &&  \epsilon\ | \  \textit{name} \ 
+                                                   (\ \textbf{\texttt{,}} \ \textit{name}\ )\ \ldots
+                                                            && \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.4.html\#p4}{function parameters}}   \\[1mm]
+&& \textit{if-statement} && ::= &\quad &&  \textbf{\texttt{if}}\
+                                   \textbf{\texttt{(}}\ \textit{expression} \ \textbf{\texttt{)}}\ 
+                                   \textit{block} \\
+&&                       &&     &      && \textbf{\texttt{else}}\
+                                          (\ \textit{block}
+                                          \ | \
+                                          \textit{\href{https://source-academy.github.io/sicp/chapters/1.3.3.html\#footnote-1}{if-statement}} \ )
+                                                            && \textrm{\href{https://source-academy.github.io/sicp/chapters/1.3.2.html\#p12}{conditional statement}}   \\[1mm]
+&& \textit{block}        && ::= &      && \textbf{\texttt{\{}}\  \textit{statement}\ \ldots   \ \textbf{\texttt{\}}} \quad
+                                                           && \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.8.html\#p14}{block statement}}\\[1mm]         
+&& \textit{expression}   && ::= &\quad &&  \textit{number}   && \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.1.html\#p3}{primitive number expression}}\\
+&&                       && |   &\quad && \textbf{\texttt{true}}\ |\ \textbf{\texttt{false}}
+                                                           && \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.6.html\#p1}{primitive boolean expression}}\\
+&&                       && |   &\quad &&  \textit{string}   && \textrm{\href{https://source-academy.github.io/sicp/chapters/2.3.1.html}{primitive string expression}}\\
+&&                       && |   &\quad &&  \textit{name}   && \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.2.html}{name expression}}\\
+&&                       && |   &\quad &&  \textit{expression} \  \textit{binary-operator} \ 
+                                            \textit{expression} \qquad
+                                                           && \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.1.html\#p5}{binary operator combination}}\\
+&&                       && |   &\quad &&   \textit{unary-operator} \ 
+                                            \textit{expression}
+                                                           && \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.6.html\#p4}{unary operator combination}}\\
+&&                       && |   &\quad &&   \textit{expression} \ 
+                                            \textbf{\texttt{(}}\ \textit{expressions}\
+                                            \textbf{\texttt{)}}
+                                                           && \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.4.html\#p5}{function application}}\\
+&&                       && |   &\quad &&   (\ \textit{name}\ | \
+                                               \textbf{\texttt{(}}\ \textit{parameters}\ \textbf{\texttt{)}}\
+                                            )\    
+                                            \texttt{\textbf{=>}}\ \textit{expression}
+                                                           && \textrm{\href{https://source-academy.github.io/sicp/chapters/1.3.2.html}{lambda expression (expr. body)}}\\
+&&                       && |   &\quad &&   (\ \textit{name}\ | \
+                                               \textbf{\texttt{(}}\ \textit{parameters}\ \textbf{\texttt{)}}\
+                                            )\    
+                                            \texttt{\textbf{=>}}\ \textit{block}
+                                                           && \textrm{\href{https://source-academy.github.io/sicp/chapters/2.2.4.html\#footnote-3}{lambda expression (block body)}}\\
+&&                       && |   &\quad &&   \textit{expression} \ \textbf{\texttt{?}}\ 
+                                            \textit{expression}
+                                            \ \textbf{\texttt{:}}\
+                                            \textit{expression}\
+                                                           && \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.6.html\#p1}{conditional expression}}\\
+&&                       && |   &\quad &&  \textbf{\texttt{(}}\  \textit{expression} \ 
+                                            \textbf{\texttt{)}} && \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.1.html\#p6}{parenthesised expression}}\\[1mm]
+&& \textit{binary-operator}    \ 
+                        && ::= &\quad && \textbf{\texttt{+}}\ |\ \textbf{\texttt{-}}\ |\ \textbf{\texttt{*}}\ |\ \textbf{\texttt{/}}\ |\ \textbf{\texttt{\%}}\ |\ 
+                                   \textbf{\texttt{===}}\ |\ \textbf{\texttt{!==}}\ \\
+&&                       && |  &\quad &&  \texttt{\textbf{>}}\ |\ \texttt{\textbf{<}}\ |\ \texttt{\textbf{>=}}\ |\ \texttt{\textbf{<=}}\
+                                          |\ \textbf{\texttt{\&\&}}\ |\ \texttt{\textbf{||}}
+                                          && \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.1.html\#p4}{binary operator}}\\[1mm]
+&& \textit{unary-operator}    
+                        && ::= &\quad && \textbf{\texttt{!}}\ |\ \textbf{\texttt{-}}
+                        && \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.6.html\#p4}{unary operator}}\\[1mm]
+&& \textit{expressions}  && ::= &\quad && \epsilon\ | \ \textit{expression}\ (
+                                                               \ \textbf{\texttt{,}} \
+                                                                 \textit{expression} \ 
+                                                                      )\ \ldots
+                                                            && \textrm{\href{https://source-academy.github.io/sicp/chapters/1.1.4.html\#p5}{argument expressions}} 
+\end{alignat*}

docs/specs/source_1_lazy.tex

@@ -12,7 +12,7 @@
 
 Source \S 1 Lazy is a lazy-evaluation variant of Source \S 1.
 
-\section*{Changes}
+\section{Changes}
 
 Source \S 1 Lazy modifies Source \S 1 by using
 lazy evaluation. In
@@ -38,19 +38,27 @@ \section*{Changes}
 
 \newpage
 
-\input source_boolean_operators
-
 \input source_return
 
-\input source_names
+\input source_import
+
+\input source_boolean_operators
+
+\input source_names_lang
 
 \input source_numbers
 
 \input source_strings
 
+\input source_comments
+
 \input source_typing
 
-\input source_comments
+\section{Standard Libraries}
+
+The following library is always available in this language.
+
+\input source_misc
 
 \input source_js_differences
 

docs/specs/source_1_wasm.tex

@@ -28,7 +28,7 @@
 
 This document specifies the dialect of Source \S 1 used in Sourceror, an experimental compiler from Source \S 1 to WebAssembly.  This dialect is a subset of Source \S 1.
 
-\section*{Changes compared to Vanilla Source \S 1}
+\section{Changes compared to Vanilla Source \S 1}
 
 \subsection*{Language}  
 
@@ -46,23 +46,29 @@ \subsection*{Error Handling}
 
 \input source_bnf.tex
 
-\input source_1_bnf.tex
+\input source_1_bnf_without_import.tex
 
 \newpage
 
-\input source_boolean_operators
-
 \input source_return
 
+\input source_boolean_operators
+
 \input source_names_lang
 
 \input source_numbers
 
 \input source_strings
 
+\input source_comments
+
 \input source_typing
 
-\input source_comments
+\section{Standard Libraries}
+
+The following library is always available in this language.
+
+\input source_misc
 
 \input source_js_differences
 

docs/specs/source_2.tex

@@ -7,7 +7,7 @@
 
 \input source_intro.tex
 
-\section*{Changes}
+\section{Changes}
 
 Compared to Source \S 1, Source \S 2 has the following changes:
 \begin{itemize}
@@ -17,27 +17,33 @@ \section*{Changes}
 
 \newpage
 
-\input source_import
-
 \input source_bnf.tex
 
 \input source_2_bnf.tex
 
-\input source_boolean_operators
-
 \input source_return
 
-\input source_names
+\input source_import
 
-\input source_lists
+\input source_boolean_operators
+
+\input source_names_lang
 
 \input source_numbers
 
 \input source_strings
 
+\input source_comments
+
 \input source_typing
 
-\input source_comments
+\section{Standard Libraries}
+
+The following library is always available in this language.
+
+\input source_misc
+
+\input source_lists
 
 \input source_js_differences
 

docs/specs/source_2_lazy.tex

@@ -12,7 +12,7 @@
 
 Source \S 2 Lazy is a lazy-evaluation variant of Source \S 2.
 
-\section*{Changes}
+\section{Changes}
 
 Source \S 2 Lazy modifies Source \S 2 by using
 lazy evaluation. In
@@ -41,21 +41,29 @@ \section*{Changes}
 
 \input source_2_bnf.tex
 
-\input source_boolean_operators
-
 \input source_return
 
-\input source_names
+\input source_import
 
-\input source_lists
+\input source_boolean_operators
+
+\input source_names_lang
 
 \input source_numbers
 
 \input source_strings
 
+\input source_comments
+
 \input source_typing
 
-\input source_comments
+\section{Standard Libraries}
+
+The following library is always available in this language.
+
+\input source_misc
+
+\input source_lists
 
 \input source_js_differences
 

docs/specs/source_3.tex

@@ -7,7 +7,7 @@
 
 \input source_intro.tex
 
-\section*{Changes}
+\section{Changes}
 
 Compared to Source \S 2, Source \S 3 has the following changes:
 \begin{itemize}
@@ -33,33 +33,37 @@ \section*{Changes}
 
 \newpage
 
+\input source_return
+
 \input source_import
 
 \input source_boolean_operators
 
 \input source_loops
 
-\input source_return
+\input source_names_lang
 
-\input source_names
+\input source_numbers
 
-\input source_lists
+\input source_strings
 
-\input source_pair_mutators
+\input source_arrays
 
-\input source_array_support
+\input source_comments
 
-\input source_streams
+\input source_typing_3
 
-\input source_numbers
+\section{Standard Libraries}
 
-\input source_strings
+\input source_misc
 
-\input source_arrays
+\input source_lists
 
-\input source_typing_3
+\input source_pair_mutators
 
-\input source_comments
+\input source_array_support
+
+\input source_streams
 
 \input source_js_differences