#52: describe prose in HTML files

Development.md

@@ -2,7 +2,7 @@
 
 As of 2017, all exercises are coded in Java.
 Each Pityoulish exercise comprises:
-- Instructions in HTML, from files in
+- A description in HTML, from files in
   [src/main/prose/](src/main/prose/)
 - A JAR file, compiled and assembled from source code in 
   [src/main/java/](src/main/java/)
@@ -16,6 +16,7 @@ Table of Contents:
 - [Setup](#setup) - install your own build environment
 - [Ant Targets](#ant-targets) - use Ant to build exercises and related stuff
 - [Build Steps](#build-steps) - how the build process works
+- [Prose](#prose) - write exercises or instructions in HTML
 
 
 # Setup
@@ -81,7 +82,7 @@ Ant targets specific to an exercise have at least one hyphen in their name, and
 | server-rmi-java | ijr | Instructions: Java RMI |
 | follow-rmi-java | fjr | Follow the board: Java RMI |
 
-The target for an Exercise or the Instructions will build a zip archive for students or instructors, respectively.
+The target for an Exercise or its Instructions will build a zip archive for students or instructors, respectively.
 This requires several sub-targets to be built. Ant prints these sub-targets while it executes.
 If you are working on a specific part of an exercise, you can build the respective sub-target directly to save time.
 For example, building the Tutorial with `prep-java` builds these sub-targets, among others:
@@ -154,3 +155,31 @@ public class FooImpl implements Foo {
     // PYL:end
 }
 ```
+
+
+## Prose
+
+All exercise descriptions and instructor's notes are written as static HTML files in [src/main/prose/](src/main/prose/).
+You can read all the information by browsing the files on your local machine, without running a build or a web server.
+[`local-index.html`](src/main/prose/local-index.html) is the table of contents.
+
+When building the prose for a zip archive, the relevant files are copied to a dedicated directory, and one of them is renamed to `index.html`.
+By browsing the dedicated directory, you can verify that all relevant files have been copied.
+
+There is a naming convention to support the co-existence of all the exercises and notes in a single directory:
+
+- `pityoulish.css` or other files without a hyphen (-) provide a common style.
+  These files are copied into every exercise and instructor package.
+- _xyz_`-index.html` becomes the `index.html` file when building the _xyz_`-prose` [Ant target](#ant-targets).
+- `message-board.html` or other files with a hyphen (-) are copied only into zip archives for which they are relevent.
+  Their name remains unchanged.
+- Some files with a hyphen (-) are just local, not relevant for any of the zip archives:
+  - `local-index.html` is the table of contents.
+    It links to all _xyz_`-index.html` files with their local name.
+    It also links to default locations of exercise-specific JavaDocs,
+    as generated by the _xyz_`-jdoc` [Ant targets](#ant-targets).
+  - `color-palette.gpa` is the [GPick](http://www.gpick.org/) palette from which the colors in `pityoulish.css` were chosen.
+
+Due to this naming convention, links to non-index files work everywhere.
+Backlinks to `index.html` are broken in the source directory, but work in the dedicated directory.
+Links to _xyz_`-index.html` work only in the source directory, but are broken everywhere else.