example/README

   1 (C) Copyright Vesa Karvonen 2004.
   2
   3 Distributed under the Boost Software License, Version 1.0.
   4 (See accompanying file LICENSE.)
   5
   6 # Order programming examples
   7
   8 An attempt has been made to make each example mostly self-contained
   9 at the cost of repeating some explanations. A reader having a good
  10 understanding of programming should be able to follow the examples
  11 with a minimal understanding of the Order language. The narrative
  12 body of each example briefly motivates the example and gives a bit
  13 of background information, but doesn't aim to explain every detail
  14 of each Order language feature used.
  15
  16 Most of the examples are meant to apply programming techniques that
  17 are likely to be useful in practice to the kind of problems that one
  18 might encounter in practice, but none of the examples is meant to be
  19 an industry strength solution. This is emphasized by exercises,
  20 given at the end of each example, that ask the reader to modify and
  21 extend the examples in various ways. While it is probably too much
  22 to ask the reader to complete all the exercises, all readers are
  23 strongly recommended to preprocess one or more examples to actually
  24 see what is ultimately being generated.
  25
  26 ## Rant of the day
  27
  28 In case the reader is interested in preprocessing the examples, it
  29 is good to know that at the time of writing, the author is only
  30 aware of two preprocessors that are able to preprocess the examples
  31 correctly. The preprocessors are the GNU CPP and the Wave
  32 preprocessor library by Hartmut Kaiser. To the best of the knowledge
  33 of the author, the implementation of the Order interpreter strictly
  34 conforms to the [C99] standard. Unfortunately, despite the supposed
  35 simplicity of the C preprocessor, and the existence of a stable C
  36 standard first since 1989 and later since 1999, with a couple of
  37 exceptions, almost no preprocessor implementation conforms even to
  38 the 1989 standard. In the opinion of the author, 5 years, let alone
  39 15 years, should be considerably more than enough time to get the
  40 implementation of a simple language right. The author will not spend
  41 one minute of his time to write workarounds for broken
  42 preprocessors.