From: Ralf Jung <post@ralfj.de>
Date: Sat, 27 Jun 2015 11:24:31 +0000 (+0200)
Subject: document 'make workspace'
X-Git-Url: https://git.ralfj.de/rust-101.git/commitdiff_plain/cb170f41304c809a22de172621845e637e28b8d2

document 'make workspace'
---

diff --git a/Makefile b/Makefile
index c6c80eb..01d7298 100644
--- a/Makefile
+++ b/Makefile
@@ -5,29 +5,35 @@ WORKSPACEFILES=$(addprefix workspace/,$(FILES))
 all: docs workspace crates
 .PHONY: docs workspace crates
 
-# Documentation
+## Documentation
 docs: $(DOCFILES)
 
 .tmp/docs/%.rs: src/%.rs Makefile
 	@mkdir -p .tmp/docs
 	@echo "$< -> $@"
-	@sed 's|^\(\s*//\)@|\1|;s|\s*/\*@\*/||' $< > $@
+	@# sed-fu: remove the "@" from "//@", and remove trailing "/*@*/".
+	@sed 's|^\(\s*//\)@|\1|;s|\s*/\*@\*/$$||' $< > $@
 
 docs/%.html: .tmp/docs/%.rs
 	@./pycco-rs $<
 
-# Workspace
+## Workspace
+# The generated files are shipped only for the benefit of Windows users, who
+# typically don't have the necessary tools for generating the workspace
+# available.
 workspace: $(WORKSPACEFILES)
 
 workspace/src/%.rs: src/%.rs Makefile dup-unimpl.sed
 	@mkdir -p .tmp/docs
 	@echo "$< -> $@"
+	@# sed-fu: remove lines starting with "//@", and replace those ending in "/*@*/" by "unimplemented!()".
+	@# Also coalesce multiple adjacent such lines to one.
 	@sed '/^\s*\/\/@/d;s|\(\s*\)\S.*/\*@\*/|\1unimplemented!()|' $< | sed -f dup-unimpl.sed > $@
 
 workspace/src/main.rs:
 	# Don't touch this file
 
-# Crates
+## Crates
 crates: $(WORKSPACEFILES)
 	@cargo build
 	@cd solutions && cargo build
diff --git a/README.rst b/README.rst
index 8254d96..3d4188f 100644
--- a/README.rst
+++ b/README.rst
@@ -12,6 +12,8 @@ You can either read through the sources in ``src/``, or generate the HTML in
 ``docs/`` using ``make docs`` (this step needs Pycco_), or go directly to 
 `the rendered output`_.
 
+The files ``workspace/src/part*.rs`` are generated by ``make workspace``.
+
 .. _Pycco: https://fitzgen.github.io/pycco/
 .. _the rendered output: https://www.ralfj.de/projects/rust-101/main.html