doc/intro.tex: Strengthen the argument about C++ a bit.

doc/: Fix various unfortunate garblings.

doc/concepts.tex: Fix description of standard method combination.

doc/concepts.tex: Typeset method rôle names as identifiers.

doc/: Consistently write `rôle', rather than `role', in prose.

Obviously there's no diacritic in identifiers.

Merge branches 'mdw/doc-reorg' and 'mdw/parser-fixes'

* mdw/doc-reorg: (34 commits)
  doc/refintro.tex, src/sod-module.5: Fix slightly garbled text.
  doc/syntax.tex: Delete (wrong) duplicate rule for <argument-declarator>.
  doc/syntax.tex: Consistently use baseline-level ellipses in syntax.
  doc/concepts.tex: Fix a rather distant demonstrative.
  test/: Add a simple rational-number class.
  src/method-impl.lisp: Initialize `suppliedp' flags properly.
  src/class-output.lisp: Fix missing parentheses around `me' in message macros.
  doc/concepts.tex: Fix garbled fragment ordering rules.
  doc/runtime.tex: Fix name of `SOD_XCHAIN' macro.
  doc/structures.tex, lib/sod-structs.3: Fix in-chain ichain exemplar.
  src/optparse.lisp: Indent a line correctly.
  test/test.sod: Abbreviate the T1 class nicknames.
  src/method-impl.lisp: Mark `sod__obj' as ignorable in effective methods.
  src/method-aggregate.lisp: Allow useful behaviour if no primary methods.
  doc/intro.tex: Begin a (rather extensive) comparison with C++.
  doc/Makefile.am, doc/sod.tex: Actually include the stub intro.
  doc/intro.tex: Fix erroneous `\manpage' to correct `\man'.
  doc/concepts.tex: Include diagram of standard method combination.
  doc/Makefile.am: Enable `\nonstopmode' in TeX processing.
  doc/Makefile.am: Abstract out repeated TeX arguments into a variable.
  ...

* mdw/parser-fixes: (97 commits)
  src/class-finalize.lisp: Improve reporting of CPL construction errors.
  src/class-finalize-impl.lisp: Move error reporting to `merge-class-lists'.
  src/class-finalize-impl.lisp (clos-cpl, dylan-cpl): Improve formatting.
  src/class-finalize-impl.lisp (clos-tiebreaker): Refactor.
  src/class-finalize.lisp (merge-class-lists): Zap pointless `:present' arg.
  src/module-impl.lisp (c-fragment): Fix docstring formatting.
  src/module-parse.lisp: Improve error recovery for core class items.
  src/module-parse.lisp: Abstract out `parse-maybe-dotted-name'.
  src/module-parse.lisp: Use `quote', not `list', to make constant lists.
  src/module-parse.lisp: Use `dotted-name', not `dotted-identifier'.
  src/module-parse.lisp: Catch errors during class-item construction.
  src/module-parse.lisp: Factor out slot and maybe-initializer creation.
  src/module-parse.lisp: Improve error recovery for `class' item framing.
  src/class-utilities.lisp: Permit `temporary-name' objects as class names.
  src/class-utilities.lisp: Improve reporting of multiple root classes.
  src/module-parse.lisp: Improve error recovery for `initarg' class-items.
  src/module-parse.lisp: Improve error recovery for `lisp' items.
  src/module-parse.lisp: Improve error recovery for `load' and `import' items.
  src/module-parse.lisp: Improve error recovery for `test' items.
  src/module-parse.lisp: Improve error recovery for `code' items.
  ...

doc/refintro.tex, src/sod-module.5: Fix slightly garbled text.

doc/syntax.tex: Delete (wrong) duplicate rule for <argument-declarator>.

doc/syntax.tex: Consistently use baseline-level ellipses in syntax.

doc/concepts.tex: Fix a rather distant demonstrative.

test/: Add a simple rational-number class.

This found a surprising number of bugs.  I wasn't even intending for it
to be a test, but it seems to work well as one.

src/method-impl.lisp: Initialize `suppliedp' flags properly.

More foolishness.  The standalone C library gets this right,
embarrassingly enough.

src/class-output.lisp: Fix missing parentheses around `me' in message macros.

What was I thinking?

doc/concepts.tex: Fix garbled fragment ordering rules.

doc/runtime.tex: Fix name of `SOD_XCHAIN' macro.

The index entry was right, but the synopsis showed the wrong name.

doc/structures.tex, lib/sod-structs.3: Fix in-chain ichain exemplar.

The general ichain structure is for some superclass on the same chain,
but not necessarily the chain head.  The later prose already has this
right, but the synopsis at the beginning of the section didn't.

src/optparse.lisp: Indent a line correctly.

test/test.sod: Abbreviate the T1 class nicknames.

They don't actually need to have `t1' in them.

src/method-impl.lisp: Mark `sod__obj' as ignorable in effective methods.

Very trivial effective methods don't need this, and the warnings are
annoying.

src/method-aggregate.lisp: Allow useful behaviour if no primary methods.

Many aggregating combinations have obvious things to do even if they
have no primary methods; e.g., `progn' should do nothing, and
combinations based on operators with identity should return that
identity.  This actually covers all of them except `min' and `max'.

doc/intro.tex: Begin a (rather extensive) comparison with C++.

I think this doesn't fit well here, but these things need saying
somewhere.

doc/Makefile.am, doc/sod.tex: Actually include the stub intro.

doc/intro.tex: Fix erroneous `\manpage' to correct `\man'.

doc/concepts.tex: Include diagram of standard method combination.

doc/Makefile.am: Enable `\nonstopmode' in TeX processing.

Now the build doesn't grind to a halt because I've upset TeX again.

doc/Makefile.am: Abstract out repeated TeX arguments into a variable.

doc/structures.tex: Fix variable reuse in keyword-args message signature.

I had `m' as both the message name and the total number of arguments.

doc/concepts.tex: Warn about allocating resources in init methods.

doc/concepts.tex: Fix missing superclass in a code example.

doc/concepts.tex: Fix copy-and-paste fail in `Destruction' section.

doc/concepts.tex: Update `Slot initializers', about class initialization.

The old initialization function has been replaced by a message.

doc/concepts.tex: A number of minor fixes.

  * Insert a missing paren.

  * Insert missing space after `\Cplusplus'.

  * Hyphenate `pointer-to-class-type' in the description of conversions,
    because it's easy to mis-associate otherwise.

  * Fix erroneous (probably copy-and-paste) `upcast' to `downcast'.

  * Improve wording about failing downcasts.

src/optparse.lisp: Use low-level slot accessor in `option' printer.

If I try to use the access wrapper, I get compiler warnings about how
the previous use of the function wasn't inlined; but if I declare the
wrapper earlier then it might not inline anything.  The printer is
rarely used, so this isn't a bad place to be.

src/class-make-impl.lisp: Introduce property to choose initarg class.

This is now uniform, at least.

doc/syntax.tex: Describe the built-in properties for objects.

All a bit rough, but at least there's a place to write this stuff down
now.

doc/syntax.tex: Give cross-ref to (stub) metaclass section.

Fixes a fixme.

Various, style: Generally prefer `: ' over ` : '.

Before subclass lists, output constraints, and bitfield widths.  Retain
` : ' in conditional expressions to match ` ? ' which I don't want to
change, at least for now.

doc/: Work in progress.

doc/refintro.tex: Introduction to reference section.

This is the start of a major reorganization of the reference material.

doc/stdmeth.tex: A TikZ diagram of the standard method combination.

For safekeeping.  Remove the old (Lisp-specific) SVG version now that we
don't need it any more.

src/class-finalize.lisp: Improve reporting of CPL construction errors.

Introduce `report-class-list-merge-error' to report problems properly.

src/class-finalize-impl.lisp: Move error reporting to `merge-class-lists'.

This means that `merge-class-lists' now needs a CLASS argument, hence
the noise.

src/class-finalize-impl.lisp (clos-cpl, dylan-cpl): Improve formatting.

  * In `clos-cpl', distinguish the `class' argument to the outer
    function from the lambda-bound `c'.  This makes the lambda short
    enough to un-miser the `merge-class-lists' call.

  * in `dylan-cpl', hoist the `cpls' calculation into the `let', to
    match `c3-cpl' below.  Again, this lets us un-miser.

src/class-finalize-impl.lisp (clos-tiebreaker): Refactor.

An early exit is cleaner than assignment and a nil check.

src/class-finalize.lisp (merge-class-lists): Zap pointless `:present' arg.

Since we don't actually print the `inconsistent-merge-error' anyway,
fiddling with the presentation of the items doesn't do anything.

src/module-impl.lisp (c-fragment): Fix docstring formatting.

src/module-parse.lisp: Improve error recovery for core class items.

src/module-parse.lisp: Abstract out `parse-maybe-dotted-name'.

src/module-parse.lisp: Use `quote', not `list', to make constant lists.

src/module-parse.lisp: Use `dotted-name', not `dotted-identifier'.

An identifier is a single token, and therefore can't be dotted.  I
appear to have gotten this one right everywhere else.

src/module-parse.lisp: Catch errors during class-item construction.

These aren't worth failing the whole class construction over, but they
do mean that the individual class-item shouldn't be recorded.

This approach seems generally easier than reporting continuable errors
and then indicating failure in some other way, particularly in the case
of slots with initializers.

src/module-parse.lisp: Factor out slot and maybe-initializer creation.

src/module-parse.lisp: Improve error recovery for `class' item framing.

Cope with a failure to parse the class name (by inventing a synthetic
name) and/or superclass list (by forcing the use of `SodObject' as a
parent).

src/class-utilities.lisp: Permit `temporary-name' objects as class names.

This will be helpful in error recovery.  Classes and various related
objects must have names, but if we can't parse the user's choice of name
then we have to make one up.  The easy approach, to avoid conflicts with
the user's other choices, is to pick a name with funny characters in,
but that's properly rejected by the check here; but we can wrap the name
up in a `temporary-name' object to push it through without trouble.

src/class-utilities.lisp: Improve reporting of multiple root classes.

src/module-parse.lisp: Improve error recovery for `initarg' class-items.

src/module-parse.lisp: Improve error recovery for `lisp' items.

src/module-parse.lisp: Improve error recovery for `load' and `import' items.

src/module-parse.lisp: Improve error recovery for `test' items.

src/module-parse.lisp: Improve error recovery for `code' items.

src/module-parse.lisp: Improve error recovery for `typename' items.

src/module-parse.lisp (`set'): Parse at least one property if no pset.

Allow

[foo = "thing"] set;

and

set foo = "thing";

but not plain

set;

src/module-parse.lisp (read-module): Use requested pathname for location.

The default behaviour for `charbuf-scanner' is to use the pathname from
its underlying stream; but (at least on some implementations) this is an
absolute pathname which is actually rather annoying in error messages.

Instead, arrange for `read-module' to attach the namestring of the
pathname it was given directly to the scanner.  This will be the correct
possibly-relative pathname to the module file, because `find-file' has
already done that part of the work, but it will be relative if that's
how it was specified on the command line, if it was found by merging
with a relative pathname in the `*module-dirs*' list, or if it was
imported by a name relative to a module with a relative pathname.

src/module-parse.lisp (read-module): Provide sensible default error-recovery.

By default, if there's an error parsing a module item, skip and consume
until the next `;' or `}'.  This actually seems to work quite well.

src/module-parse.lisp: Don't explicitly ask for default behaviour.

  * Reporting the scanner position as the error location.

  * Setting at-least-one when parsing delimitered lists.

  * Keeping the terminator when skipping to one of several terminator
    tokens.

src/module-parse.lisp: Use newer syntax notation in the commentary.

src/module-parse.lisp: Some minor reformattings.

src/lexer-{proto,impl}.lisp: Add explicit recovery action to `error'.

This ends up being an `:action' keyword argument to
`parse-error-recover', and a macro body to the `error' parser macro.

src/lexer-{proto,impl}.lisp: Enhance `skip-until' to match token values.

src/lexer-impl.lisp: Set default `:keep-end' in `%skip-until' function.

The parser-macro set this correctly, but the function didn't.

src/lexer-impl.lisp: Rename internal `skip-until' function.

This shouldn't have leaked.

src/class-make-impl.lisp: Forbid slots with function types.

Pointer-to-function type is fine, of course.

src/{c-types-impl,method-{proto,impl}}.lisp: Improve `merge-keyword-lists'.

  * Make the overall description of the merging site be a function (a)
    to report a file location and (b) to avoid formatting the thing if
    there isn't actually a problem.

  * Make the per-argument-list descriptions be functions so that they
    can report more than one message each.

  * Change `method-keyword-argument-lists' to report the inheritance
    path for methods involved in keyword argument conflicts.  Add an
    argument to thread through an `inheritance-path-reporter-state'
    object to make this work.

src/c-types-impl.lisp: Reorder `merge-keyword-lists' input lists.

Prepend the `what' argument to the front of each argument list, rather
than having a (LIST . WHAT) pair.  Also, internally to
`merge-keyword-lists', keep the entries in the hash table as
(WHAT . ARG) rather than the other way around.

src/method-impl.lisp (method-keyword-argument-lists): Check message type.

Check keyword arguments defined in the message as well as all of the
applicable methods.

src/method-impl.lisp (method-keyword-argument-lists): Zap pointless `let'.

src/method-impl.lisp (method-keyword-argument-lists): Fix indentation.

src/{lexer-{proto,impl},parser/floc-proto}.lisp: Conditionify parse errors.

  * Introduce condition classes for parse errors.

  * Introduce `classify-condition' to describe the different reportable
    conditions to the user, and change `count-and-report-errors*' to use
    this rather than having special knowledge.  Now it pretty much just
    counts and prints.

  * Move the complicated error-message printing machinery from the
    `syntax-error' and `lexer-error' functions into the condition
    reporting functions.  (Now they don't actually need to be formatted
    until they're just about to be presented to a user.)

src/**/*.lisp: Use convenience functions to invoke restarts.

Introduce a new function `noted' to invoke the `noted' restart.  Fiddle
other code to do the right thing.

src/utilities.lisp: New function `invoke-associated-restart'.

Does what it says on the tin.  Not really sure why this isn't part of
Common Lisp.

src/class-finalize-impl.lisp: Overhaul `check-sod-class', `compute-chains'.

Signal continuable errors so that we can get more useful diagnostics.
Use the `finalization-error' machinery to limit redundant error
reporting.  Report portions of inheritance structure where appropriate.
Improve checking that the things defined by the class don't conflict
with each other.

src/class-finalize-*.lisp: Improve finalization error reporting.

Change the finalization protocol: now, `finalize-sod-class' and its
helpers (notably `check-sod-class') can signal continuable errors and
still have the overall finalization report failure.

Actually make use of the return value in the two callers:
`parse-class-body' and `bootstrap-classes'.

src/method-{impl,proto}.lisp: Add `sod-method-description'.

Now we can report on kinds of methods.

src/class-*.lisp: Improve metaclass selection.

Replace the slightly wobbly (and poorly named) `maximum' function (in
`class-finalize-impl.lisp') with the much more capable
`select-minimal-class-property' (in `class-utilities.lisp').

Use this new function as appropriate.

src/builtin.lisp (method-keyword-argument-lists): Don't `delete-duplicates'.

No idea why this was here.  The `merge-keyword-lists' function copes
fine with duplicate names.  And the `:key' argument was hopelessly
wrong, so the code could never have worked.

src/class-finalize-{proto,impl}.lisp (finalize-sod-class): Add `:around'.

The `around' method handles the recursiveness and state tracking (and
will accumulate further functionality later).  The primary method
actually does the calculation and checking needed to make a class work.

src/class-finalize-proto.lisp (check-sod-class): Fix docstring.

Describe the actual, rather unsatisfactory, state of the world.
Fortunately, this will be fixed soon.

src/{class-,}utilities.lisp: Add machinery for showing inheritance paths.

To the general utilities collection, we add an implementation of
Dijkstra's distinguished-point shortest-path algorithm.

To the class utilities, we add a new type and function for reporting
inheritance paths, with the notion that this will be useful when
debugging problems where classes turn out to be incompatible with each
other for various reasons.

src/class-{finalize,layout}-*.lisp: Relocate layout interface code.

Establishing the layout is now the responsibility of the layout code.
Not sure what made me put it anywhere else.

src/final.lisp (test-parser): Set error location after making the scanner.

Oops.

src/final.lisp (test-module): By default, just report and count up errors.

This makes the whole return value thing more useful.  You can still get
a backtrace (or enter the debugger or whatever) by setting the new
BACKTRACE argument.

src/final.lisp (test-module): Optionally clear the decks before parsing.

src/final.lisp (test-module): Don't try output if parsing failed.

src/final.lisp (test-module): Make REASON be a keyword argument.

It's not always wanted, and we'll want to add more keywords soon.

src/final.lisp (test-module): Fix egregiously wrong docstring.

Make the doc stub match too.

src/utilities: (add partial-order-minima)

src/utilities.lisp: Fix docstring formatting.

lib/keyword.3: Fix some minor formatting errors.

src/c-types-class-impl.lisp (find-sod-class): Improve error reporting.

The built-in simple type names are now properly baked in, in the
`*simple-type-map*' hash table, rather than being exported by the
`builtin' module, so check there before reporting a type as `unknown'.

src/c-types-class-impl.lisp (find-class-type): Don't repeat type name.

It turns out that if some type name isn't a class, then it doesn't
usually have a very interesting description which is different from its
name.