Updating cross references to design documents to html style, to go with master/design document tree.

Copied from Perforce Change: 29897 ServerID: perforce.ravenbrook.com
author: Richard Brooksby 2002-06-07 16:47:14 +0100
committer: Richard Brooksby 2002-06-07 16:47:14 +0100
commit: 97075f705350901f5ff46387f658ab459a4cd73f (patch)
tree: 4349ad5e7200f072a800f48749d57f3625757e7e /mps/code
parent: 8b990e4858b6f6d735de07a241b1785702bb16e7 (diff)
download: emacs-97075f705350901f5ff46387f658ab459a4cd73f.tar.gz
emacs-97075f705350901f5ff46387f658ab459a4cd73f.zip
91 files changed, 557 insertions, 557 deletions
diff --git a/mps/code/abq.c b/mps/code/abq.c
index 74ab8066ea8..94ac5dd4680 100644
--- a/mps/code/abq.c
+++ b/mps/code/abq.c
@@ -7,7 +7,7 @@
 *
 * .purpose: A FIFO queue substrate for impl.c.poolmv2
 *
- * .design: See design.mps.poolmv2
+ * .design: See <design/poolmv2/>
 */
 #include "meter.h"
diff --git a/mps/code/abq.h b/mps/code/abq.h
index d2ceccf67f7..608240b4474 100644
--- a/mps/code/abq.h
+++ b/mps/code/abq.h
@@ -5,7 +5,7 @@
 *
 * .purpose: A FIFO queue substrate for impl.c.poolmv2
 *
- * .source: design.mps.poolmv2
+ * .source: <design/poolmv2/>
 */
 #ifndef abq_h
diff --git a/mps/code/arena.c b/mps/code/arena.c
index 665ffc59b25..2d6ace20240 100644
--- a/mps/code/arena.c
+++ b/mps/code/arena.c
@@ -3,7 +3,7 @@
 * $Id$
 * Copyright (c) 2001 Ravenbrook Limited.  See end of file for license.
 *
- * .sources: design.mps.arena is the main design document.  */
+ * .sources: <design/arena/> is the main design document.  */
 #include "tract.h"
 #include "poolmv.h"
@@ -32,7 +32,7 @@ static Res ArenaTrivDescribe(Arena arena, mps_lib_FILE *stream)
 /* AbstractArenaClass  -- The abstact arena class definition
 *
 * .null: Most abstract class methods are set to NULL.  See
- * design.mps.arena.class.abstract.null.  */
+ * <design/arena/#class.abstract.null>.  */
 typedef ArenaClassStruct AbstractArenaClassStruct;
@@ -91,7 +91,7 @@ Bool ArenaCheck(Arena arena)
  CHECKD(ArenaClass, arena->class);
  CHECKL(BoolCheck(arena->poolReady));
-  if (arena->poolReady) { /* design.mps.arena.pool.ready */
+  if (arena->poolReady) { /* <design/arena/#pool.ready> */
    CHECKD(MV, &arena->controlPoolStruct);
    CHECKD(Reservoir, &arena->reservoirStruct);
  }
@@ -154,7 +154,7 @@ Res ArenaInit(Arena arena, ArenaClass class)
  arena->alignment = 1 << ARENA_ZONESHIFT;
  /* zoneShift is usually overridden by init */
  arena->zoneShift = ARENA_ZONESHIFT;
-  arena->poolReady = FALSE;     /* design.mps.arena.pool.ready */
+  arena->poolReady = FALSE;     /* <design/arena/#pool.ready> */
  arena->lastTract = NULL;
  arena->lastTractBase = NULL;
@@ -171,7 +171,7 @@ Res ArenaInit(Arena arena, ArenaClass class)
  arena->sig = ArenaSig;
-  /* initialize the reservoir, design.mps.reservoir */
+  /* initialize the reservoir, <design/reservoir/> */
  res = ReservoirInit(&arena->reservoirStruct, arena);
  if (res != ResOK)
    goto failReservoirInit;
@@ -282,7 +282,7 @@ Res ControlInit(Arena arena)
                 ARENA_CONTROL_MAXSIZE);
  if (res != ResOK)
    return res;
-  arena->poolReady = TRUE;      /* design.mps.arena.pool.ready */
+  arena->poolReady = TRUE;      /* <design/arena/#pool.ready> */
  return ResOK;
 }
@@ -393,7 +393,7 @@ Res ArenaDescribeTracts(Arena arena, mps_lib_FILE *stream)
 * control pool, which is an MV pool embedded in the arena itself.
 *
 * .controlalloc.addr: In implementations where Addr is not compatible
- * with void* (design.mps.type.addr.use), ControlAlloc must take care of
+ * with void* (<design/type/#addr.use>), ControlAlloc must take care of
 * allocating so that the block can be addressed with a void*.  */
 Res ControlAlloc(void **baseReturn, Arena arena, size_t size,
@@ -474,7 +474,7 @@ Res ArenaAlloc(Addr *baseReturn, SegPref pref, Size size, Pool pool,
  return res;
 goodAlloc:
-  /* cache the tract - design.mps.arena.tract.cache */
+  /* cache the tract - <design/arena/#tract.cache> */
  arena->lastTract = baseTract;
  arena->lastTractBase = base;
@@ -503,7 +503,7 @@ void ArenaFree(Addr base, Size size, Pool pool)
  AVER(AddrIsAligned(base, arena->alignment));
  AVER(SizeIsAligned(size, arena->alignment));
-  /* uncache the tract if in range - design.mps.arena.tract.uncache */
+  /* uncache the tract if in range - <design/arena/#tract.uncache> */
  limit = AddrAdd(base, size);
  if ((arena->lastTractBase >= base) && (arena->lastTractBase < limit)) {
    arena->lastTract = NULL;
diff --git a/mps/code/arenacl.c b/mps/code/arenacl.c
index 89605fdd147..18ede55dafa 100644
--- a/mps/code/arenacl.c
+++ b/mps/code/arenacl.c
@@ -3,7 +3,7 @@
 * $Id$
 * Copyright (c) 2001 Ravenbrook Limited.  See end of file for license.
 *
- * .design: See design.mps.arena.client.
+ * .design: See <design/arena/#client>.
 *
 * .improve.remember: One possible performance improvement is to
 * remember (a conservative approximation to) the indices of the first
@@ -25,7 +25,7 @@ SRCID(arenacl, "$Id$");
 typedef struct ClientArenaStruct {
  ArenaStruct arenaStruct; /* generic arena structure */
-  Sig sig;                 /* design.mps.sig */
+  Sig sig;                 /* <design/sig/> */
 } ClientArenaStruct;
 typedef struct ClientArenaStruct *ClientArena;
@@ -43,7 +43,7 @@ typedef struct ClientChunkStruct {
  ChunkStruct chunkStruct;     /* generic chunk */
  Size freePages;              /* number of free pages in chunk */
  Addr pageBase;               /* base of first managed page in chunk */
-  Sig sig;                     /* design.mps.sig */
+  Sig sig;                     /* <design/sig/> */
 } ClientChunkStruct;
 #define ClientChunk2Chunk(clchunk) (&(clchunk)->chunkStruct)
@@ -110,7 +110,7 @@ static Res clientChunkCreate(Chunk *chunkReturn, Addr base, Addr limit,
    goto failBootInit;
  /* Allocate the chunk. */
-  /* See design.mps.arena.@@@@ */
+  /* See <design/arena/>.@@@@ */
  res = BootAlloc(&p, boot, sizeof(ClientChunkStruct), MPS_PF_ALIGN);
  if (res != ResOK)
    goto failChunkAlloc;
@@ -340,7 +340,7 @@ static Res chunkAlloc(Addr *baseReturn, Tract *baseTractReturn,
  /* Check commit limit.  Note that if there are multiple reasons */
  /* for failing the allocation we attempt to return other result codes */
-  /* in preference to ResCOMMIT_LIMIT.  See design.mps.arena.commit-limit */
+  /* in preference to ResCOMMIT_LIMIT.  See <design/arena/#commit-limit> */
  if (ArenaCommitted(arena) + pages * ChunkPageSize(chunk)
      > arena->commitLimit) {
    return ResCOMMIT_LIMIT;
@@ -382,7 +382,7 @@ static Res ClientAlloc(Addr *baseReturn, Tract *baseTractReturn,
  /* All chunks have same pageSize. */
  AVER(SizeIsAligned(size, ChunkPageSize(arena->primary)));
  /* NULL is used as a discriminator (see */
-  /* design.mps.arenavm.table.disc), therefore the real pool */
+  /* <design/arenavm/#table.disc>), therefore the real pool */
  /* must be non-NULL. */
  AVER(pool != NULL);
diff --git a/mps/code/arenavm.c b/mps/code/arenavm.c
index 6e1742bfadd..8c135c9742a 100644
--- a/mps/code/arenavm.c
+++ b/mps/code/arenavm.c
@@ -6,7 +6,7 @@
 *
 * DESIGN
 *
- * .design: See design.mps.arena.vm, and design.mps.arena.coop-vm
+ * .design: See <design/arenavm/>, and <design/arena/#coop-vm>
 *
 * .vm.addr-is-star: In this file, Addr is compatible with C
 * pointers, and Count with size_t (Index), because all refer to the
@@ -47,7 +47,7 @@ typedef struct VMChunkStruct {
  Addr overheadMappedLimit;           /* limit of pages mapped for overhead */
  BT pageTableMapped;           /* indicates mapped state of page table */
  BT noSparePages;             /* 1 bit per page of pageTable */
-  Sig sig;                      /* design.mps.sig */
+  Sig sig;                      /* <design/sig/> */
 } VMChunkStruct;
 #define VMChunk2Chunk(vmchunk) (&(vmchunk)->chunkStruct)
@@ -62,7 +62,7 @@ typedef struct VMChunkStruct {
 /* VMArena
 *
- * See design.mps.arena.coop-vm.struct.vmarena for description.
+ * See <design/arena/#coop-vm.struct.vmarena> for description.
 */
 typedef struct VMArenaStruct *VMArena;
@@ -77,7 +77,7 @@ typedef struct VMArenaStruct {  /* VM arena structure */
  ZoneSet genZoneSet[VMArenaGenCount]; /* .gencount.const */
  ZoneSet freeSet;               /* unassigned zones */
  Size extendBy;
-  Sig sig;                      /* design.mps.sig */
+  Sig sig;                      /* <design/sig/> */
 } VMArenaStruct;
 #define Arena2VMArena(arena) PARENT(VMArenaStruct, arenaStruct, arena)
@@ -273,7 +273,7 @@ static Res VMChunkCreate(Chunk *chunkReturn, VMArena vmArena, Size size)
    goto failBootInit;
  /* Allocate and map the descriptor. */
-  /* See design.mps.arena.@@@@ */
+  /* See <design/arena/>.@@@@ */
  res = BootAlloc(&p, boot, sizeof(VMChunkStruct), MPS_PF_ALIGN);
  if (res != ResOK)
    goto failChunkAlloc;
@@ -333,7 +333,7 @@ static Res VMChunkInit(Chunk chunk, BootBlock boot)
    goto failnoSparePages;
  vmChunk->noSparePages = p;
-  /* Actually commit all the tables. design.mps.arena.vm.@@@@ */
+  /* Actually commit all the tables. <design/arenavm/>.@@@@ */
  overheadLimit = AddrAdd(chunk->base, (Size)BootAllocated(boot));
  if (vmChunk->overheadMappedLimit < overheadLimit) {
    overheadLimit = AddrAlignUp(overheadLimit, ChunkPageSize(chunk));
@@ -438,7 +438,7 @@ static Res VMArenaInit(Arena *arenaReturn, ArenaClass class, va_list args)
    vmArena->genZoneSet[gen] = ZoneSetEMPTY;
  }
  vmArena->freeSet = ZoneSetUNIV; /* includes blacklist */
-  /* design.mps.arena.coop-vm.struct.vmarena.extendby.init */
+  /* <design/arena/#coop-vm.struct.vmarena.extendby.init> */
  vmArena->extendBy = userSize;
  /* have to have a valid arena before calling ChunkCreate */
@@ -452,7 +452,7 @@ static Res VMArenaInit(Arena *arenaReturn, ArenaClass class, va_list args)
  /* number of stripes as will fit into a reference set (the number of */
  /* bits in a word).  Fail if the chunk is so small stripes are smaller */
  /* than pages.  Note that some zones are discontiguous in the chunk if */
-  /* the size is not a power of 2.  See design.mps.arena.class.fields. */
+  /* the size is not a power of 2.  See <design/arena/#class.fields>. */
  chunkSize = AddrOffset(chunk->base, chunk->limit);
  arena->zoneShift = SizeFloorLog2(chunkSize >> MPS_WORD_SHIFT);
@@ -1221,7 +1221,7 @@ static Res vmAllocComm(Addr *baseReturn, Tract *baseTractReturn,
  AVER(SizeIsAligned(size, ChunkPageSize(arena->primary)));
 
  /* NULL is used as a discriminator */
-  /* (see design.mps.arena.vm.table.disc) therefore the real pool */
+  /* (see <design/arenavm/table.disc>) therefore the real pool */
  /* must be non-NULL. */
  AVER(pool != NULL);
diff --git a/mps/code/awlut.c b/mps/code/awlut.c
index 4f9410bd6f7..0f17b1efbd3 100644
--- a/mps/code/awlut.c
+++ b/mps/code/awlut.c
@@ -5,7 +5,7 @@
 *
 * DESIGN
 *
- * .design: see design.mps.poolawl.test.*
+ * .design: see <design/poolawl/#test>.*
 */
 #include "mpscawl.h"
diff --git a/mps/code/awluthe.c b/mps/code/awluthe.c
index aac1d45dabd..251ad76aaf6 100644
--- a/mps/code/awluthe.c
+++ b/mps/code/awluthe.c
@@ -5,7 +5,7 @@
 *
 * DESIGN
 *
- * .design: see design.mps.poolawl.test.*
+ * .design: see <design/poolawl/#test>.*
 */
 #include "mpscawl.h"
diff --git a/mps/code/awlutth.c b/mps/code/awlutth.c
index c4ce32428d9..a9d34e00dff 100644
--- a/mps/code/awlutth.c
+++ b/mps/code/awlutth.c
@@ -5,7 +5,7 @@
 *
 * DESIGN
 *
- * .design: see design.mps.poolawl.test.*
+ * .design: see <design/poolawl/#test>.*
 */
 #include "mpscawl.h"
diff --git a/mps/code/bt.c b/mps/code/bt.c
index 496479a94b6..687aa4675b7 100644
--- a/mps/code/bt.c
+++ b/mps/code/bt.c
@@ -9,7 +9,7 @@
 *
 * DESIGN
 *
- * .design: see design.mps.bt
+ * .design: see <design/bt/>
 */
 #include "mpm.h"
@@ -168,7 +168,7 @@ SRCID(bt, "$Id$");
 /* BTCreate -- allocate a BT from the control pool
 *
- * See design.mps.bt.if.create
+ * See <design/bt/#if.create>
 */
 Res BTCreate(BT *btReturn, Arena arena, Count length)
@@ -194,7 +194,7 @@ Res BTCreate(BT *btReturn, Arena arena, Count length)
 /* BTDestroy -- free a BT to the control pool.
 *
- * See design.mps.bt.if.destroy
+ * See <design/bt/#if.destroy>
 */
 void BTDestroy(BT bt, Arena arena, Count length)
@@ -223,7 +223,7 @@ static Bool BTCheck(BT bt)
 /* BTSize -- return the size of a BT
 *
- * See design.mps.bt.fun.size
+ * See <design/bt/#fun.size>
 */
 size_t (BTSize)(unsigned long n)
@@ -237,7 +237,7 @@ size_t (BTSize)(unsigned long n)
 /* BTGet -- get a bit from a BT
 *
- * See design.mps.bt.fun.get
+ * See <design/bt/#fun.get>
 */
 Bool (BTGet)(BT t, Index i)
@@ -252,7 +252,7 @@ Bool (BTGet)(BT t, Index i)
 /* BTSet -- set a bit in a BT
 *
- * See design.mps.bt.fun.set
+ * See <design/bt/#fun.set>
 */
 void (BTSet)(BT t, Index i)
@@ -267,7 +267,7 @@ void (BTSet)(BT t, Index i)
 /* BTRes -- reset a bit in a BT
 *
- * design.mps.bt.fun.res
+ * <design/bt/#fun.res>
 */
 void (BTRes)(BT t, Index i)
@@ -282,7 +282,7 @@ void (BTRes)(BT t, Index i)
 /* BTSetRange -- set a range of bits in a BT
 *
- * design.mps.bt.fun.set-range
+ * <design/bt/#fun.set-range>
 */
 void BTSetRange(BT t, Index base, Index limit)
@@ -304,7 +304,7 @@ void BTSetRange(BT t, Index base, Index limit)
 /* BTIsResRange -- test whether a range of bits is all reset
 *
- * See design.mps.bt.fun.is-reset-range.
+ * See <design/bt/#fun.is-reset-range>.
 */
 Bool BTIsResRange(BT bt, Index base, Index limit)
@@ -328,7 +328,7 @@ Bool BTIsResRange(BT bt, Index base, Index limit)
 /* BTIsSetRange -- test whether a range of bits is all set
 *
- * See design.mps.bt.fun.is-set-range.
+ * See <design/bt/#fun.is-set-range>.
 */
 Bool BTIsSetRange(BT bt, Index base, Index limit)
@@ -356,7 +356,7 @@ Bool BTIsSetRange(BT bt, Index base, Index limit)
 /* BTResRange -- reset a range of bits in a BT
 *
- * design.mps.bt.fun.res-range
+ * <design/bt/#fun.res-range>
 */
 void BTResRange(BT t, Index base, Index limit)
@@ -609,7 +609,7 @@ btFindResHighLabel:; \
 *
 * Starts searching at the low end of the search range.
 *
- * See design.mps.bt.fun.find-res-range.
+ * See <design/bt/#fun.find-res-range>.
 */
 static Bool BTFindResRange(Index *baseReturn, Index *limitReturn,
@@ -696,7 +696,7 @@ static Bool BTFindResRange(Index *baseReturn, Index *limitReturn,
 *
 * Starts searching at the high end of the search range.
 *
- * See design.mps.bt.fun.find-res-range.
+ * See <design/bt/#fun.find-res-range>.
 */
 static Bool BTFindResRangeHigh(Index *baseReturn, Index *limitReturn,
@@ -789,7 +789,7 @@ static Bool BTFindResRangeHigh(Index *baseReturn, Index *limitReturn,
 /* BTFindLongResRange -- find long range of reset bits in a bit table
 *
- * See design.mps.bt.fun.find-long-res-range.
+ * See <design/bt/#fun.find-long-res-range>.
 */
 Bool BTFindLongResRange(Index *baseReturn, Index *limitReturn,
@@ -807,7 +807,7 @@ Bool BTFindLongResRange(Index *baseReturn, Index *limitReturn,
 /* BTFindLongResRangeHigh -- find long range of reset bits in a bit table
 *
- * See design.mps.bt.fun.find-long-res-range-high.
+ * See <design/bt/#fun.find-long-res-range-high>.
 */
 Bool BTFindLongResRangeHigh(Index *baseReturn, Index *limitReturn,
@@ -825,7 +825,7 @@ Bool BTFindLongResRangeHigh(Index *baseReturn, Index *limitReturn,
 /* BTFindShortResRange -- find short range of reset bits in a bit table
 *
- * See design.mps.bt.fun.find-short-res-range.
+ * See <design/bt/#fun.find-short-res-range>.
 */
 Bool BTFindShortResRange(Index *baseReturn, Index *limitReturn,
@@ -844,7 +844,7 @@ Bool BTFindShortResRange(Index *baseReturn, Index *limitReturn,
 *
 * Starts looking from the top of the search range.
 *
- * See design.mps.bt.fun.find-short-res-range-high.
+ * See <design/bt/#fun.find-short-res-range-high>.
 */
 Bool BTFindShortResRangeHigh(Index *baseReturn, Index *limitReturn,
@@ -862,7 +862,7 @@ Bool BTFindShortResRangeHigh(Index *baseReturn, Index *limitReturn,
 /* BTRangesSame -- check that a range of bits in two BTs are the same.
 *
- * See design.mps.bt.if.ranges-same
+ * See <design/bt/#if.ranges-same>
 */
 Bool BTRangesSame(BT comparand, BT comparator, Index base, Index limit)
@@ -898,7 +898,7 @@ Bool BTRangesSame(BT comparand, BT comparator, Index base, Index limit)
 /* BTCopyInvertRange -- copy a range of bits from one BT to another,
 * inverting them as you go.
 *
- * See design.mps.bt.if.copy-invert-range
+ * See <design/bt/#if.copy-invert-range>
 */
 void BTCopyInvertRange(BT fromBT, BT toBT, Index base, Index limit)
@@ -933,7 +933,7 @@ void BTCopyInvertRange(BT fromBT, BT toBT, Index base, Index limit)
 /* BTCopyRange -- copy a range of bits from one BT to another
 *
- * See design.mps.bt.if.copy-range
+ * See <design/bt/#if.copy-range>
 */
 void BTCopyRange(BT fromBT, BT toBT, Index base, Index limit)
@@ -973,7 +973,7 @@ void BTCopyRange(BT fromBT, BT toBT, Index base, Index limit)
 * may differ for each range. We could try to be smart about
 * detecting similar alignment - but we don't.
 *
- * See design.mps.bt.if.copy-offset-range
+ * See <design/bt/#if.copy-offset-range>
 */
 void BTCopyOffsetRange(BT fromBT, BT toBT,
diff --git a/mps/code/buffer.c b/mps/code/buffer.c
index 635319d7a98..831efac5c06 100644
--- a/mps/code/buffer.c
+++ b/mps/code/buffer.c
@@ -10,7 +10,7 @@
 *
 * DESIGN
 *
- * .design: See design.mps.buffer.
+ * .design: See <design/buffer/>.
 *
 * .ap.async: The mutator is allowed to change certain AP fields
 * asynchronously.  Functions that can be called on buffers not
@@ -44,7 +44,7 @@ Bool BufferCheck(Buffer buffer)
  CHECKU(Arena, buffer->arena);
  CHECKU(Pool, buffer->pool);
  CHECKL(buffer->arena == buffer->pool->arena);
-  CHECKL(RingCheck(&buffer->poolRing)); /* design.mps.check.type.no-sig */
+  CHECKL(RingCheck(&buffer->poolRing)); /* <design/check/#type.no-sig> */
  CHECKL(BoolCheck(buffer->isMutator));
  CHECKL(buffer->fillSize >= 0.0);
  CHECKL(buffer->emptySize >= 0.0);
@@ -102,7 +102,7 @@ Bool BufferCheck(Buffer buffer)
    /* .lwcheck: If LW frames are enabled, the buffer may become */
    /* trapped asynchronously. It can't become untrapped */
-    /* asynchronously, though. See design.mps.alloc-frame.lw-frame.pop. */
+    /* asynchronously, though. See <design/alloc-frame/#lw-frame.pop>. */
    /* Read a snapshot value of the limit field. Use this to determine */
    /* if we are trapped, and to permit more useful checking when not */
    /* yet trapped. */
@@ -252,7 +252,7 @@ failInit:
 /* BufferCreate -- create an allocation buffer
 *
- * See design.mps.buffer.method.create.  */
+ * See <design/buffer/#method.create>.  */
 Res BufferCreate(Buffer *bufferReturn, BufferClass class,
                 Pool pool, Bool isMutator, ...)
@@ -269,7 +269,7 @@ Res BufferCreate(Buffer *bufferReturn, BufferClass class,
 /* BufferCreateV -- create an allocation buffer, with varargs
 *
- * See design.mps.buffer.method.create.  */
+ * See <design/buffer/#method.create>.  */
 Res BufferCreateV(Buffer *bufferReturn, BufferClass class,
                  Pool pool, Bool isMutator, va_list args)
@@ -360,7 +360,7 @@ void BufferDetach(Buffer buffer, Pool pool)
 /* BufferDestroy -- destroy an allocation buffer
 *
- * See design.mps.buffer.method.destroy.  */
+ * See <design/buffer/#method.destroy>.  */
 void BufferDestroy(Buffer buffer)
 {
@@ -390,7 +390,7 @@ void BufferFinish(Buffer buffer)
  AVER((pool->class->attr & AttrBUF)); /* .trans.mod */
  AVER(BufferIsReady(buffer));
-  /* design.mps.alloc-frame.lw-frame.sync.trip */
+  /* <design/alloc-frame/#lw-frame.sync.trip> */
  if (BufferIsTrappedByMutator(buffer)) {
    BufferFrameNotifyPopPending(buffer);
  }
@@ -473,7 +473,7 @@ static void BufferSetUnflipped(Buffer buffer)
 /* BufferFrameState
 *
 * Returns the frame state of a buffer.  See
- * design.mps.alloc-frame.lw-frame.states.  */
+ * <design/alloc-frame/#lw-frame.states>.  */
 FrameState BufferFrameState(Buffer buffer)
 {
@@ -496,7 +496,7 @@ FrameState BufferFrameState(Buffer buffer)
 /* BufferFrameSetState
 *
 * Sets the frame state of a buffer.  Only the mutator may set the
- * PopPending state.  See design.mps.alloc-frame.lw-frame.states.  */
+ * PopPending state.  See <design/alloc-frame/#lw-frame.states>.  */
 void BufferFrameSetState(Buffer buffer, FrameState state)
 {
@@ -529,7 +529,7 @@ void BufferSetAllocAddr(Buffer buffer, Addr addr)
 *
 * Notifies the pool when a lightweight frame pop operation has been
 * deferred and needs to be processed.  See
- * design.mps.alloc-frame.lw-frame.sync.trip.  */
+ * <design/alloc-frame/#lw-frame.sync.trip>.  */
 static void BufferFrameNotifyPopPending(Buffer buffer)
 {
@@ -553,7 +553,7 @@ static void BufferFrameNotifyPopPending(Buffer buffer)
 /* BufferFramePush
 *
- * See design.mps.alloc-frame.  */
+ * See <design/alloc-frame/>.  */
 Res BufferFramePush(AllocFrame *frameReturn, Buffer buffer)
 {
@@ -581,7 +581,7 @@ Res BufferFramePush(AllocFrame *frameReturn, Buffer buffer)
 /* BufferFramePop
 *
- * See design.mps.alloc-frame.  */
+ * See <design/alloc-frame/>.  */
 Res BufferFramePop(Buffer buffer, AllocFrame frame)
 {
@@ -659,7 +659,7 @@ void BufferAttach(Buffer buffer, Addr base, Addr limit,
  filled = AddrOffset(init, limit);
  buffer->fillSize += filled;
  if (buffer->isMutator) {
-    if (base != init) { /* see design.mps.buffer.count.alloc.how */
+    if (base != init) { /* see <design/buffer/#count.alloc.how> */
      Size prealloc = AddrOffset(base, init);
      ArenaGlobals(buffer->arena)->allocMutatorSize -= prealloc;
    }
@@ -708,7 +708,7 @@ Res BufferFill(Addr *pReturn, Buffer buffer, Size size,
      BufferSetUnflipped(buffer);
    }
-    /* design.mps.alloc-frame.lw-frame.sync.trip */
+    /* <design/alloc-frame/#lw-frame.sync.trip> */
    if (BufferIsTrappedByMutator(buffer)) {
      BufferFrameNotifyPopPending(buffer);
    }
@@ -764,7 +764,7 @@ Bool BufferCommit(Buffer buffer, Addr p, Size size)
  AVER(SizeIsAligned(size, BufferPool(buffer)->alignment));
  AVER(!BufferIsReady(buffer));
-  /* See design.mps.collection.flip. */
+  /* See <design/collection/#flip>. */
  /* .commit.before: If a flip occurs before this point, when the */
  /* pool reads "initAtFlip" it will point below the object, so it */
  /* will be trashed and the commit must fail when trip is called.  */
@@ -972,7 +972,7 @@ Bool BufferIsTrapped(Buffer buffer)
 /* BufferIsTrappedByMutator
 *
 * Indicates whether the mutator trapped the buffer.  See
- * design.mps.alloc-frame.lw-frame.sync.trip and .ap.async.  */
+ * <design/alloc-frame/#lw-frame.sync.trip> and .ap.async.  */
 Bool BufferIsTrappedByMutator(Buffer buffer)
 {
@@ -1207,7 +1207,7 @@ Bool BufferClassCheck(BufferClass class)
 /* BufferClass -- the vanilla buffer class definition
 *
- * See design.mps.buffer.class.hierarchy.buffer.  */
+ * See <design/buffer/#class.hierarchy.buffer>.  */
 DEFINE_CLASS(BufferClass, class)
 {
@@ -1458,7 +1458,7 @@ static Res segBufDescribe(Buffer buffer, mps_lib_FILE *stream)
 /* SegBufClass -- SegBuf class definition
 *
 * Supports an association with a single segment when attached.  See
- * design.mps.buffer.class.hierarchy.segbuf.  */
+ * <design/buffer/#class.hierarchy.segbuf>.  */
 typedef BufferClassStruct SegBufClassStruct;
diff --git a/mps/code/cbs.c b/mps/code/cbs.c
index 3ea8e263938..1fc89960a5a 100644
--- a/mps/code/cbs.c
+++ b/mps/code/cbs.c
@@ -9,7 +9,7 @@
 * .purpose: CBSs are used to manage potentially unbounded
 * collections of memory blocks.
 *
- * .sources: design.mps.cbs.
+ * .sources: <design/cbs/>.
 */
 #include "cbs.h"
@@ -22,7 +22,7 @@
 SRCID(cbs, "$Id$");
-/* See design.mps.cbs.align */
+/* See <design/cbs/#align> */
 #define cbsMinimumAlignment ((Align)sizeof(void *))
 #define cbsOfSplayTree(tree) PARENT(CBSStruct, splayTree, (tree))
@@ -34,7 +34,7 @@ SRCID(cbs, "$Id$");
 /* CBSEmergencyBlock* -- Getters and setters for emergency blocks
 *
- * See design.mps.cbs.impl.low-mem.inline.block.
+ * See <design/cbs/#impl.low-mem.inline.block>.
 */
 #define CBSEmergencyBlockBase(block) ((Addr)(block))
@@ -51,7 +51,7 @@ SRCID(cbs, "$Id$");
 /* CBSEmergencyGrain* -- Getters and setters for emergency grains
 *
- * See design.mps.cbs.impl.low-mem.inline.grain.
+ * See <design/cbs/#impl.low-mem.inline.grain>.
 */
 #define CBSEmergencyGrainBase(grain) ((Addr)(grain))
@@ -125,7 +125,7 @@ Bool CBSCheck(CBS cbs)
  CHECKL(cbs->shrink == NULL || FUNCHECK(cbs->shrink));
  CHECKL(cbs->mayUseInline || cbs->emergencyBlockList == NULL);
  CHECKL(cbs->mayUseInline || cbs->emergencyGrainList == NULL);
-  /* See design.mps.cbs.align */
+  /* See <design/cbs/#align> */
  CHECKL(!cbs->mayUseInline ||
         AlignIsAligned(cbs->alignment, cbsMinimumAlignment));
  /* can't check emergencyBlockList or emergencyGrainList more */
@@ -136,7 +136,7 @@ Bool CBSCheck(CBS cbs)
 }
-/* CBSBlockCheck -- See design.mps.cbs.function.cbs.block.check */
+/* CBSBlockCheck -- See <design/cbs/#function.cbs.block.check> */
 Bool CBSBlockCheck(CBSBlock block)
 {
@@ -153,7 +153,7 @@ Bool CBSBlockCheck(CBSBlock block)
 }
-/* CBSBlockSize -- see design.mps.cbs.function.cbs.block.size */
+/* CBSBlockSize -- see <design/cbs/#function.cbs.block.size> */
 Size (CBSBlockSize)(CBSBlock block)
 {
@@ -164,7 +164,7 @@ Size (CBSBlockSize)(CBSBlock block)
 /* cbsSplayCompare -- Compare key to [base,limit)
 *
- * See design.mps.splay.type.splay.compare.method
+ * See <design/splay/#type.splay.compare.method>
 */
 static Compare cbsSplayCompare(void *key, SplayNode node)
@@ -268,7 +268,7 @@ static void cbsUpdateNode(SplayTree tree, SplayNode node,
 /* CBSInit -- Initialise a CBS structure
 *
- * See design.mps.cbs.function.cbs.init.
+ * See <design/cbs/#function.cbs.init>.
 */
 Res CBSInit(Arena arena, CBS cbs, void *owner,
@@ -284,7 +284,7 @@ Res CBSInit(Arena arena, CBS cbs, void *owner,
  AVER(delete == NULL || FUNCHECK(delete));
  AVER(BoolCheck(mayUseInline));
  if (mayUseInline) {
-    /* See design.mps.cbs.align */
+    /* See <design/cbs/#align> */
    if (!AlignIsAligned(alignment, cbsMinimumAlignment))
      return ResPARAM;
  }
@@ -327,7 +327,7 @@ Res CBSInit(Arena arena, CBS cbs, void *owner,
 /* CBSFinish -- Finish a CBS structure
 *
- * See design.mps.cbs.function.cbs.finish.
+ * See <design/cbs/#function.cbs.finish>.
 */
 void CBSFinish(CBS cbs)
@@ -521,7 +521,7 @@ static Res cbsInsertIntoTree(Addr *baseReturn, Addr *limitReturn,
      Size oldRightSize = CBSBlockSize(rightCBS);
      /* must block larger neighbour and destroy smaller neighbour; */
-      /* see design.mps.cbs.function.cbs.insert.callback */
+      /* see <design/cbs/#function.cbs.insert.callback> */
      if (oldLeftSize >= oldRightSize) {
        Addr rightLimit = rightCBS->limit;
        cbsBlockDelete(cbs, rightCBS);
@@ -700,7 +700,7 @@ static Res cbsAddToEmergencyLists(CBS cbs, Addr base, Addr limit)
  AVER(cbs->mayUseInline);
  size = AddrOffset(base, limit);
-  /* Use the block list if possible.  See design.mps.cbs.align. */
+  /* Use the block list if possible.  See <design/cbs/#align>. */
  if (size > cbsMinimumAlignment) {
    CBSEmergencyBlock prev, block, new;
    new = CBSEmergencyBlockInit(base, limit);
@@ -834,7 +834,7 @@ static void cbsFlushEmergencyLists(CBS cbs)
 /* CBSInsert -- Insert a range into the CBS
 *
- * See design.mps.cbs.functions.cbs.insert.
+ * See <design/cbs/#functions.cbs.insert>.
 */
 Res CBSInsertReturningRange(Addr *baseReturn, Addr *limitReturn,
@@ -946,7 +946,7 @@ static Res cbsDeleteFromTree(CBS cbs, Addr base, Addr limit)
      Size leftNewSize = AddrOffset(cbsBlock->base, base);
      Size rightNewSize = AddrOffset(limit, cbsBlock->limit);
      /* must shrink larger fragment and create smaller; */
-      /* see design.mps.cbs.function.cbs.delete.callback */
+      /* see <design/cbs/#function.cbs.delete.callback> */
      if (leftNewSize >= rightNewSize) {
        Addr oldLimit = cbsBlock->limit;
        AVER(limit < cbsBlock->limit);
@@ -1090,7 +1090,7 @@ static Res cbsDeleteFromEmergencyGrainList(CBS cbs, Addr base, Addr limit)
 /* CBSDelete -- Remove a range from a CBS
 *
- * See design.mps.cbs.function.cbs.delete.
+ * See <design/cbs/#function.cbs.delete>.
 */
 Res CBSDelete(CBS cbs, Addr base, Addr limit)
@@ -1157,7 +1157,7 @@ static Res CBSSplayNodeDescribe(SplayNode splayNode, mps_lib_FILE *stream)
 /* CBSIterate -- Iterate all blocks in CBS
 *
 * This is not necessarily efficient.
- * See design.mps.cbs.function.cbs.iterate.
+ * See <design/cbs/#function.cbs.iterate>.
 */
 /* Internal version without enter/leave checking. */
@@ -1246,7 +1246,7 @@ void CBSIterateLarge(CBS cbs, CBSIterateMethod iterate, void *closureP)
 /* CBSSetMinSize -- Set minimum interesting size for cbs
 *
 * This function may invoke the shrink and grow methods as
- * appropriate.  See design.mps.cbs.function.cbs.set.min-size.
+ * appropriate.  See <design/cbs/#function.cbs.set.min-size>.
 */
 typedef struct {
@@ -1628,7 +1628,7 @@ Bool CBSFindLargest(Addr *baseReturn, Addr *limitReturn,
 /* CBSDescribe -- describe a CBS
 *
- * See design.mps.cbs.function.cbs.describe.
+ * See <design/cbs/#function.cbs.describe>.
 */
 Res CBSDescribe(CBS cbs, mps_lib_FILE *stream)
diff --git a/mps/code/cbs.h b/mps/code/cbs.h
index 452b7c2ef30..85f13082c27 100644
--- a/mps/code/cbs.h
+++ b/mps/code/cbs.h
@@ -3,7 +3,7 @@
 * $Id$
 * Copyright (c) 2001 Ravenbrook Limited.  See end of file for license.
 *
- * .source: design.mps.cbs.
+ * .source: <design/cbs/>.
 */
 #ifndef cbs_h
@@ -21,10 +21,10 @@ typedef void (*CBSChangeSizeMethod)(CBS cbs, CBSBlock block,
 typedef Bool (*CBSIterateMethod)(CBS cbs, CBSBlock block, void *closureP);
-/* See design.mps.cbs.impl.low-mem.inline.block */
+/* See <design/cbs/#impl.low-mem.inline.block> */
 typedef void **CBSEmergencyBlock; /* next, limit */
-/* See design.mps.cbs.impl.low-mem.inline.block */
+/* See <design/cbs/#impl.low-mem.inline.block> */
 typedef void **CBSEmergencyGrain; /* next */
@@ -87,9 +87,9 @@ extern void CBSSetMinSize(CBS cbs, Size minSize);
 extern Res CBSDescribe(CBS cbs, mps_lib_FILE *stream);
 extern Res CBSBlockDescribe(CBSBlock block, mps_lib_FILE *stream);
-/* CBSBlockBase -- See design.mps.cbs.function.cbs.block.base */
+/* CBSBlockBase -- See <design/cbs/#function.cbs.block.base> */
 #define CBSBlockBase(block) ((block)->base)
-/* CBSBlockLimit -- See design.mps.cbs.function.cbs.block.limit */
+/* CBSBlockLimit -- See <design/cbs/#function.cbs.block.limit> */
 #define CBSBlockLimit(block) ((block)->limit)
 #define CBSBlockSize(block) AddrOffset((block)->base, (block)->limit)
 extern Size (CBSBlockSize)(CBSBlock block);
diff --git a/mps/code/check.h b/mps/code/check.h
index b30e27e719b..84a87592ba6 100644
--- a/mps/code/check.h
+++ b/mps/code/check.h
@@ -111,8 +111,8 @@ extern void AssertFail1(const char *s);
 /* CHECKT -- check type simply
 *
- * Must be thread safe.  See design.mps.interface.c.thread-safety
+ * Must be thread safe.  See <design/interface-c/#thread-safety>
- * and design.mps.interface.c.check.space.
+ * and <design/interface-c/#check.space>.
 */
 #define CHECKT(type, val)       ((val) != NULL && (val)->sig == type ## Sig)
diff --git a/mps/code/config.h b/mps/code/config.h
index 0886f9686f0..3691e24c0ac 100644
--- a/mps/code/config.h
+++ b/mps/code/config.h
@@ -14,7 +14,7 @@
 *
 * DESIGN
 *
- * See design.mps.config.
+ * See <design/config/>.
 */
 #ifndef config_h
@@ -24,7 +24,7 @@
 /* Variety Configuration
 *
 * Convert CONFIG_VAR_* defined on compiler command line into
- * internal configuration parameters.  See design.mps.config.var
+ * internal configuration parameters.  See <design/config/#var>
 * and design.mps.variety.macro.  Note that MPS_HOT is subclassed
 * into MPS_HOT_RED and MPS_HOT_WHITE; this distinction should
 * be rarely used.
@@ -253,7 +253,7 @@
 /* Product Configuration
 *
 * Convert CONFIG_PROD_* defined on compiler command line into
- * internal configuration parameters.  See design.mps.config.prod.
+ * internal configuration parameters.  See <design/config/#prod>.
 */
 #if defined(CONFIG_PROD_EPCORE)
diff --git a/mps/code/dbgpool.c b/mps/code/dbgpool.c
index 5a1ba300a87..7254dc95f25 100644
--- a/mps/code/dbgpool.c
+++ b/mps/code/dbgpool.c
@@ -136,7 +136,7 @@ static Res DebugPoolInit(Pool pool, va_list args)
  /* fencepost init */
  /* @@@@ This parses a user argument, options, so it should really */
  /* go through the MPS interface.  The template needs to be copied */
-  /* into Addr memory, to avoid breaking design.mps.type.addr.use. */
+  /* into Addr memory, to avoid breaking <design/type/#addr.use>. */
  debug->fenceSize = options->fenceSize;
  if (debug->fenceSize != 0) {
    if (debug->fenceSize % PoolAlignment(pool) != 0) {
@@ -413,7 +413,7 @@ static void TagWalk(Pool pool, ObjectsStepMethod step, void *p)
 {
  SplayNode node;
  PoolDebugMixin debug;
-  Addr dummy = NULL; /* Breaks design.mps.type.addr.use, but it's */
+  Addr dummy = NULL; /* Breaks <design/type/#addr.use>, but it's */
                     /* only temporary until SplayTreeFirst is fixed. */
  AVERT(Pool, pool);
@@ -481,7 +481,7 @@ void mps_pool_check_fenceposts(mps_pool_t mps_pool)
  Pool pool = (Pool)mps_pool;
  Arena arena;
 
-  /* CHECKT not AVERT, see design.mps.interface.c.check.space */
+  /* CHECKT not AVERT, see <design/interface-c/#check.space> */
  AVER(CHECKT(Pool, pool));
  arena = PoolArena(pool);
diff --git a/mps/code/event.h b/mps/code/event.h
index d49c1efffb3..26538c91e6e 100644
--- a/mps/code/event.h
+++ b/mps/code/event.h
@@ -9,7 +9,7 @@
 *
 * DESIGN
 *
- * .design: design.mps.telemetry.
+ * .design: <design/telemetry/>.
 */
 #ifndef event_h
@@ -34,7 +34,7 @@ extern void EventLabelAddr(Addr, Word);
 extern Res EventFlush(void);
-/* Event Kinds --- see design.mps.telemetry
+/* Event Kinds --- see <design/telemetry/>
 *
 * All events are classified as being of one event type.
 * They are small enough to be able to be used as shifts within a word.
diff --git a/mps/code/eventcom.h b/mps/code/eventcom.h
index 72165a3fe23..79c87c7d46d 100644
--- a/mps/code/eventcom.h
+++ b/mps/code/eventcom.h
@@ -45,7 +45,7 @@ typedef EventUnion *Event;
 #endif
-/* Event types -- see design.mps.telemetry
+/* Event types -- see <design/telemetry/>
 *
 * These names are intended to be mnemonic.  They are derived from
 * selected letters as indicated, using the transliteration in
diff --git a/mps/code/eventdef.h b/mps/code/eventdef.h
index 88a656a3e60..9f312ff2a45 100644
--- a/mps/code/eventdef.h
+++ b/mps/code/eventdef.h
@@ -3,7 +3,7 @@
 * $Id$
 * Copyright (c) 2001 Ravenbrook Limited.  See end of file for license.
 *
- * .source: design.mps.telemetry
+ * .source: <design/telemetry/>
 *
 * .desc: This file declares relationships that define the various
 * event types.  It is intended to be used with clever definitions
diff --git a/mps/code/finalcv.c b/mps/code/finalcv.c
index 801dbd294e4..b9dc50602c6 100644
--- a/mps/code/finalcv.c
+++ b/mps/code/finalcv.c
@@ -5,7 +5,7 @@
 *
 * DESIGN
 *
- * See design.mps.poolmrg.test.
+ * See <design/poolmrg/#test>.
 *
 * DEPENDENCIES
 *
@@ -104,7 +104,7 @@ static void *test(void *arg, size_t s)
      "root_create\n");
  die(mps_ap_create(&ap, amc, MPS_RANK_EXACT), "ap_create\n");
-  /* design.mps.poolmrg.test.promise.ut.alloc */
+  /* <design/poolmrg/#test.promise.ut.alloc> */
  for(i = 0; i < rootCOUNT; ++i) {
    do {
      MPS_RESERVE_BLOCK(e, p, ap, slotSIZE);
@@ -117,7 +117,7 @@ static void *test(void *arg, size_t s)
  }
  p = NULL;
-  /* design.mps.poolmrg.test.promise.ut.drop */
+  /* <design/poolmrg/#test.promise.ut.drop> */
  for(i = 0; i < rootCOUNT; ++i) {
    if (rnd() % 2 == 0)
      root[i] = NULL;
@@ -125,7 +125,7 @@ static void *test(void *arg, size_t s)
  mps_message_type_enable(arena, mps_message_type_finalization());
-  /* design.mps.poolmrg.test.promise.ut.churn */
+  /* <design/poolmrg/#test.promise.ut.churn> */
  while(mps_collections(arena) < 3) {
    churn(ap);
    while(mps_message_poll(arena)) {
@@ -133,21 +133,21 @@ static void *test(void *arg, size_t s)
      mps_word_t objind;
      mps_addr_t objaddr;
-      /* design.mps.poolmrg.test.promise.ut.message */
+      /* <design/poolmrg/#test.promise.ut.message> */
      cdie(mps_message_get(&message, arena, mps_message_type_finalization()),
           "get");
      mps_message_finalization_ref(&objaddr, arena, message);
      obj = objaddr;
      objind = dylan_int_int(obj[2]);
      printf("Finalizing: object %lu at %p\n", objind, objaddr);
-      /* design.mps.poolmrg.test.promise.ut.final.check */
+      /* <design/poolmrg/#test.promise.ut.final.check> */
      cdie(root[objind] == NULL, "died");
      root[objind] = objaddr;
      mps_message_discard(arena, message);
    }
  }
-  /* @@@@ design.mps.poolmrg.test.promise.ut.nofinal.check missing */
+  /* @@@@ <design/poolmrg/#test.promise.ut.nofinal.check> missing */
  mps_ap_destroy(ap);
  mps_root_destroy(mps_root[1]);
diff --git a/mps/code/format.c b/mps/code/format.c
index 0ba8527f3c7..76dd4f33d65 100644
--- a/mps/code/format.c
+++ b/mps/code/format.c
@@ -122,7 +122,7 @@ void FormatDestroy(Format format)
 }
-/* Must be thread safe.  See design.mps.interface.c.thread-safety. */
+/* Must be thread safe.  See <design/interface-c/#thread-safety>. */
 Arena FormatArena(Format format)
 {
  /* Can't AVER format as that would not be thread-safe */
diff --git a/mps/code/global.c b/mps/code/global.c
index 3e3f26fa4e5..3bede9d3d6f 100644
--- a/mps/code/global.c
+++ b/mps/code/global.c
@@ -3,7 +3,7 @@
 * $Id$
 * Copyright (c) 2001 Ravenbrook Limited.  See end of file for license.
 *
- * .sources: See design.mps.arena.  design.mps.thread-safety is relevant
+ * .sources: See <design/arena/>.  design.mps.thread-safety is relevant
 * to the functions ArenaEnter and ArenaLeave in this file.
 *
 *
@@ -11,7 +11,7 @@
 *
 * .static: Static data is used in ArenaAccess (in order to find the
 * appropriate arena) and GlobalsInit.  It's checked in GlobalsCheck.
- * See design.mps.arena.static.
+ * See <design/arena/#static>.
 *
 * .non-mod: The Globals structure has many fields which properly belong
 * to other modules (see impl.h.mpmst); GlobalsInit contains code which
@@ -32,9 +32,9 @@ SRCID(global, "$Id$");
 /* All static data objects are declared here. See .static */
-/* design.mps.arena.static.ring.init */
+/* <design/arena/#static.ring.init> */
 static Bool arenaRingInit = FALSE;
-static RingStruct arenaRing;       /* design.mps.arena.static.ring */
+static RingStruct arenaRing;       /* <design/arena/#static.ring> */
 /* ArenaControlPool -- get the control pool */
@@ -44,7 +44,7 @@ static RingStruct arenaRing;       /* design.mps.arena.static.ring */
 /* arenaClaimRingLock, arenaReleaseRingLock -- lock/release the arena ring
 *
- * See design.mps.arena.static.ring.lock.  */
+ * See <design/arena/#static.ring.lock>.  */
 static void arenaClaimRingLock(void)
 {
@@ -171,11 +171,11 @@ Bool GlobalsCheck(Globals arenaGlobals)
  CHECKL(TraceSetSuper(arena->busyTraces, arena->flippedTraces));
  TRACE_SET_ITER(ti, trace, TraceSetUNIV, arena)
-    /* design.mps.arena.trace */
+    /* <design/arena/#trace> */
    if (TraceSetIsMember(arena->busyTraces, trace)) {
      CHECKD(Trace, trace);
    } else {
-      /* design.mps.arena.trace.invalid */
+      /* <design/arena/#trace.invalid> */
      CHECKL(trace->sig == SigInvalid);
    }
  TRACE_SET_ITER_END(ti, trace, TraceSetUNIV, arena);
@@ -197,7 +197,7 @@ Bool GlobalsCheck(Globals arenaGlobals)
  /* the oldest history entry must be a subset of the prehistory */
  CHECKL(RefSetSub(rs, arena->prehistory));
-  /* we also check the statics now. design.mps.arena.static.check */
+  /* we also check the statics now. <design/arena/#static.check> */
  CHECKL(BoolCheck(arenaRingInit));
  CHECKL(RingCheck(&arenaRing));
@@ -224,7 +224,7 @@ Res GlobalsInit(Globals arenaGlobals)
  /* Ensure static things are initialized. */
  if (!arenaRingInit) {
    /* there isn't an arena ring yet */
-    /* design.mps.arena.static.init */
+    /* <design/arena/#static.init> */
    arenaRingInit = TRUE;
    RingInit(&arenaRing);
    ProtSetup();
@@ -273,7 +273,7 @@ Res GlobalsInit(Globals arenaGlobals)
    arena->shCache[i] = NULL;
  for (i=0; i < TraceLIMIT; i++) {
-    /* design.mps.arena.trace.invalid */
+    /* <design/arena/#trace.invalid> */
    arena->trace[i].sig = SigInvalid;
  }
  for(rank = 0; rank < RankLIMIT; ++rank)
@@ -306,7 +306,7 @@ Res GlobalsCompleteCreate(Globals arenaGlobals)
  AVERT(Globals, arenaGlobals);
  arena = GlobalsArena(arenaGlobals);
-  /* initialize the message stuff, design.mps.message */
+  /* initialize the message stuff, <design/message/> */
  {
    void *v;
@@ -391,7 +391,7 @@ void GlobalsPrepareToDestroy(Globals arenaGlobals)
    arena->enabledMessageTypes = NULL;
  }
-  /* destroy the final pool (see design.mps.finalize) */
+  /* destroy the final pool (see <design/finalize/>) */
  if (arena->isFinalPool) {
    /* All this subtlety is because PoolDestroy will call */
    /* ArenaCheck several times.  The invariant on finalPool */
@@ -440,7 +440,7 @@ void ArenaLeave(Arena arena)
 {
  AVERT(Arena, arena);
  ShieldLeave(arena);
-  ProtSync(arena);              /* design.mps.prot.if.sync */
+  ProtSync(arena);              /* <design/prot/#if.sync> */
  LockReleaseMPM(ArenaGlobals(arena)->lock);
 }
 #endif
@@ -467,7 +467,7 @@ Bool ArenaAccess(Addr addr, AccessSet mode, MutatorFaultContext context)
  Ring node, nextNode;
  Res res;
-  arenaClaimRingLock();    /* design.mps.arena.lock.ring */
+  arenaClaimRingLock();    /* <design/arena/#lock.ring> */
  mps_exception_info = context;
  AVER(RingCheck(&arenaRing));
@@ -476,7 +476,7 @@ Bool ArenaAccess(Addr addr, AccessSet mode, MutatorFaultContext context)
    Arena arena = GlobalsArena(arenaGlobals);
    Root root;
-    ArenaEnter(arena);     /* design.mps.arena.lock.arena */
+    ArenaEnter(arena);     /* <design/arena/#lock.arena> */
    /* @@@@ The code below assumes that Roots and Segs are disjoint. */
    /* It will fall over (in TraceSegAccess probably) if there is a */
    /* protected root on a segment. */
@@ -582,7 +582,7 @@ Bool ArenaStep(Globals globals, double interval)
 /* ArenaFinalize -- registers an object for finalization
 *
- * See design.mps.finalize.  */
+ * See <design/finalize/>.  */
 Res ArenaFinalize(Arena arena, Ref obj)
 {
diff --git a/mps/code/lock.h b/mps/code/lock.h
index 09b23e882a3..b32b5ed4a73 100644
--- a/mps/code/lock.h
+++ b/mps/code/lock.h
@@ -3,7 +3,7 @@
 * $Id$
 * Copyright (c) 2001 Ravenbrook Limited.  See end of file for license.
 *
- * .description: [@@@@ Should be combined with design.mps.lock]
+ * .description: [@@@@ Should be combined with <design/lock/>]
 *  This defines the type Lock, which supports simple recursive
 *  locking.  Locking ensures that only a single thread may be running
 *  with a lock held.  By claiming a lock in some code, this ensures
diff --git a/mps/code/lockan.c b/mps/code/lockan.c
index 329743186f4..a2256404583 100644
--- a/mps/code/lockan.c
+++ b/mps/code/lockan.c
@@ -18,7 +18,7 @@ SRCID(lockan, "$Id$");
 typedef struct LockStruct {     /* ANSI fake lock structure */
-  Sig sig;                      /* design.mps.sig */
+  Sig sig;                      /* <design/sig/> */
  unsigned long claims;         /* # claims held by owner */
 } LockStruct;
diff --git a/mps/code/lockfr.c b/mps/code/lockfr.c
index 4b1c2708eb6..af4ebc5e508 100644
--- a/mps/code/lockfr.c
+++ b/mps/code/lockfr.c
@@ -43,7 +43,7 @@ SRCID(lockfr, "$Id$");
 */
 typedef struct LockStruct {
-  Sig sig;                      /* design.mps.sig */
+  Sig sig;                      /* <design/sig/> */
  unsigned long claims;         /* # claims held by owner */
  pthread_mutex_t mut;          /* the mutex itself */
 } LockStruct;
diff --git a/mps/code/lockli.c b/mps/code/lockli.c
index 7516fd669da..dc117172941 100644
--- a/mps/code/lockli.c
+++ b/mps/code/lockli.c
@@ -65,7 +65,7 @@ SRCID(lockli, "$Id$");
 */
 typedef struct LockStruct {
-  Sig sig;                      /* design.mps.sig */
+  Sig sig;                      /* <design/sig/> */
  unsigned long claims;         /* # claims held by owner */
  pthread_mutex_t mut;          /* the mutex itself */
 } LockStruct;
diff --git a/mps/code/lockw3.c b/mps/code/lockw3.c
index cd3f5c91db0..161bb6ac1de 100644
--- a/mps/code/lockw3.c
+++ b/mps/code/lockw3.c
@@ -34,7 +34,7 @@ SRCID(lockw3, "$Id$");
 /* .lock.win32: Win32 lock structure; uses CRITICAL_SECTION */
 typedef struct LockStruct {
-  Sig sig;                      /* design.mps.sig */
+  Sig sig;                      /* <design/sig/> */
  unsigned long claims;         /* # claims held by the owning thread */
  CRITICAL_SECTION cs;          /* Win32's recursive lock thing */
 } LockStruct;
diff --git a/mps/code/locus.c b/mps/code/locus.c
index 2359d4e1b07..2bb655c1d65 100644
--- a/mps/code/locus.c
+++ b/mps/code/locus.c
@@ -5,8 +5,8 @@
 *
 * DESIGN
 *
- * See design.mps.arena.vm and design.mps.locus for basic locus stuff.
+ * See <design/arenavm/> and <design/locus/> for basic locus stuff.
- * See design.mps.trace for chains.
+ * See <design/trace/> for chains.
 */
 #include "chain.h"
diff --git a/mps/code/message.c b/mps/code/message.c
index 196d688dd29..1714a506c0f 100644
--- a/mps/code/message.c
+++ b/mps/code/message.c
@@ -5,7 +5,7 @@
 *
 * DESIGN
 *
- * .design: See design.mps.message (it really exists).
+ * .design: See <design/message/> (it really exists).
 *
 * PURPOSE
 *
@@ -136,7 +136,7 @@ void MessagePost(Arena arena, Message message)
  AVERT(Message, message);
  /* queueRing field must be a singleton, see */
-  /* design.mps.message.fun.post.singleton */
+  /* <design/message/#fun.post.singleton> */
  AVER(!MessageOnQueue(message));
  if(MessageTypeEnabled(arena, message->type)) {
    RingAppend(&arena->messageRing, &message->queueRing);
diff --git a/mps/code/messtest.c b/mps/code/messtest.c
index da3d6236a34..b3ba19435ea 100644
--- a/mps/code/messtest.c
+++ b/mps/code/messtest.c
@@ -35,7 +35,7 @@ static MessageClassStruct DFMessageClassStruct = {
  MessageNoGCLiveSize,         /* GCLiveSize */   
  MessageNoGCCondemnedSize,    /* GCCondemnedSize */
  MessageNoGCNotCondemnedSize, /* GCNoteCondemnedSize */
-  MessageClassSig              /* design.mps.message.class.sig.double */
+  MessageClassSig              /* <design/message/#class.sig.double> */
 };
@@ -49,7 +49,7 @@ static MessageClassStruct DGCMessageClassStruct = {
  MessageNoGCLiveSize,         /* GCLiveSize */   
  MessageNoGCCondemnedSize,    /* GCCondemnedSize */
  MessageNoGCNotCondemnedSize, /* GCNoteCondemnedSize */
-  MessageClassSig              /* design.mps.message.class.sig.double */
+  MessageClassSig              /* <design/message/#class.sig.double> */
 };
diff --git a/mps/code/misc.h b/mps/code/misc.h
index 5c3bcdfbb59..89851f6918f 100644
--- a/mps/code/misc.h
+++ b/mps/code/misc.h
@@ -15,7 +15,7 @@
 #include <stddef.h>
-typedef int Bool;                       /* design.mps.type.bool */
+typedef int Bool;                       /* <design/type/#bool> */
 enum {
  FALSE = 0,
  TRUE = 1
diff --git a/mps/code/mpm.c b/mps/code/mpm.c
index a561dbd2b45..ba74cb50c98 100644
--- a/mps/code/mpm.c
+++ b/mps/code/mpm.c
@@ -6,7 +6,7 @@
 * .purpose: Miscellaneous support for the implementation of the MPM
 * and pool classes.
 *
- * .sources: design.mps.writef */
+ * .sources: <design/writef/> */
 #include "mpm.h"
 #include <stdarg.h>
@@ -393,7 +393,7 @@ static Res WriteDouble(mps_lib_FILE *stream, double d)
 /* WriteF -- write formatted output
 *
- * .writef.des: See design.mps.writef, also design.mps.lib
+ * .writef.des: See <design/writef/>, also <design/lib/>
 *
 * .writef.p: There is an assumption that void * fits in Word in
 * the case of $P, and unsigned long for $U and $B.  This is checked in
diff --git a/mps/code/mpm.h b/mps/code/mpm.h
index d5273db9d7c..b18a9b76fa7 100644
--- a/mps/code/mpm.h
+++ b/mps/code/mpm.h
@@ -32,7 +32,7 @@ extern Bool MPMCheck(void);
 /* Miscellaneous Checks -- see impl.c.mpm */
-/* design.mps.type.bool.check */
+/* <design/type/#bool.check> */
 #define BoolCheck(b) ((unsigned)(b) <= 1)
 extern Bool FunCheck(Fun f);
@@ -100,7 +100,7 @@ extern Addr (AddrAlignDown)(Addr addr, Align align);
 extern Addr (AddrSet)(Addr target, Byte value, Size size);
 /* This is one of the places that implements Addr, so it's allowed to */
-/* convert to void *, see design.mps.type.addr.ops.mem. */
+/* convert to void *, see <design/type/#addr.ops.mem>. */
 #define AddrSet(target, value, size) \
  mps_lib_memset(target, (int)(value), size)
@@ -139,7 +139,7 @@ extern Shift SizeLog2(Size size);
 extern Shift SizeFloorLog2(Size size);
-/* Formatted Output -- see design.mps.writef, impl.c.mpm */
+/* Formatted Output -- see <design/writef/>, impl.c.mpm */
 extern Res WriteF(mps_lib_FILE *stream, ...);
@@ -151,33 +151,33 @@ extern size_t StringLength(const char *s);
 /* Version Determination
 *
- * See design.mps.version-library.  */
+ * See <design/version/>-library.  */
 extern char *MPSVersion(void);
-/* Bit Table Interface -- see design.mps.bt.if.* for doc */
+/* Bit Table Interface -- see <design/bt/#if>.* for doc */
-/* design.mps.bt.if.size */
+/* <design/bt/#if.size> */
 extern size_t (BTSize)(unsigned long length);
 #define BTSize(n) (((n) + MPS_WORD_WIDTH-1) / MPS_WORD_WIDTH * sizeof(Word))
-/* design.mps.bt.if.get */
+/* <design/bt/#if.get> */
 extern Bool (BTGet)(BT bt, Index index);
 #define BTGet(a, i) \
  ((Bool)(((a)[((i) >> MPS_WORD_SHIFT)] \
           >> ((i) & ~((Word)-1 << MPS_WORD_SHIFT))) \
          & (Word)1))
-/* design.mps.bt.if.set */
+/* <design/bt/#if.set> */
 extern void (BTSet)(BT bt, Index index);
 #define BTSet(a, i) \
  BEGIN \
    (a)[((i)>>MPS_WORD_SHIFT)] |= (Word)1<<((i)&~((Word)-1<<MPS_WORD_SHIFT)); \
  END
-/* design.mps.bt.if.res */
+/* <design/bt/#if.res> */
 extern void (BTRes)(BT bt, Index index);
 #define BTRes(a, i) \
  BEGIN \
@@ -323,7 +323,7 @@ extern AbstractCollectPoolClass AbstractCollectPoolClassGet(void);
 /* DEFINE_POOL_CLASS
 *
- * Convenience macro -- see design.mps.protocol.int.define-special. */
+ * Convenience macro -- see <design/protocol/#int.define-special>. */
 #define DEFINE_POOL_CLASS(className, var) \
  DEFINE_ALIAS_CLASS(className, PoolClass, var)
@@ -332,7 +332,7 @@ extern AbstractCollectPoolClass AbstractCollectPoolClassGet(void);
  ((PoolClass)SUPERCLASS(className))
-/* Message Interface -- see design.mps.message */
+/* Message Interface -- see <design/message/> */
 extern Bool MessageCheck(Message message);
 extern Bool MessageClassCheck(MessageClass class);
@@ -467,7 +467,7 @@ extern void TraceScanSingleRef(TraceSet ts, Rank rank, Arena arena,
 /* DEFINE_ARENA_CLASS
 *
- * Convenience macro -- see design.mps.protocol.int.define-special. */
+ * Convenience macro -- see <design/protocol/#int.define-special>. */
 #define DEFINE_ARENA_CLASS(className, var) \
  DEFINE_ALIAS_CLASS(className, ArenaClass, var)
@@ -868,12 +868,12 @@ extern void (ShieldFlush)(Arena arena);
 /* Protection Interface
 *
- * See design.mps.prot for the design of the generic interface including
+ * See <design/prot/> for the design of the generic interface including
 * the contracts for these functions.
 *
 * This interface has several different implementations, typically one
 * per platform, see impl.c.prot* for the various implementations, and
- * design.mps.prot* for the corresponding designs. */
+ * <design/prot/>* for the corresponding designs. */
 extern void ProtSetup(void);
diff --git a/mps/code/mpmst.h b/mps/code/mpmst.h
index 12994ef60b3..673fd36e5a4 100644
--- a/mps/code/mpmst.h
+++ b/mps/code/mpmst.h
@@ -15,7 +15,7 @@
 * .rationale.sig: Object signatures (PoolSig, etc.) are defined here,
 * along with the structures, so that any code which can see a structure
 * can also check its signature before using any of its fields.  See
- * design.mps.sig.test.uniq to check that signatures are unique.  */
+ * <design/sig/#test.uniq> to check that signatures are unique.  */
 #ifndef mpmst_h
 #define mpmst_h
@@ -30,11 +30,11 @@
 /* PoolClassStruct -- pool class structure
 *
- * See design.mps.pool.
+ * See <design/pool/>.
 *
 * .class: The pool class structure is defined by each pool class
 * implementation in order to provide an interface between the MPM
- * and the class (see design.mps.class-interface) via generic
+ * and the class (see <design/class-interface/>) via generic
 * functions (see impl.c.pool).  A class XXX defines a function
 * PoolClassXXX() returning a PoolClass pointing to a PoolClassStruct
 * of methods which implement the memory management policy.
@@ -86,12 +86,12 @@ typedef struct PoolClassStruct {
 * a "subclass" of the pool structure (the "outer structure") which
 * contains PoolStruct as a a field.  The outer structure holds the
 * class-specific part of the pool's state.  See impl.c.pool,
- * design.mps.pool.  */
+ * <design/pool/>.  */
 #define PoolSig         ((Sig)0x519B0019) /* SIGnature POOL */
 typedef struct PoolStruct {     /* generic structure */
-  Sig sig;                      /* design.mps.sig */
+  Sig sig;                      /* <design/sig/> */
  Serial serial;                /* from arena->poolSerial */
  PoolClass class;              /* pool class structure */
  Arena arena;                  /* owning arena */
@@ -111,14 +111,14 @@ typedef struct PoolStruct {     /* generic structure */
 /* MFSStruct -- MFS (Manual Fixed Small) pool outer structure
 *
- * .mfs: See impl.c.poolmfs, design.mps.poolmfs.
+ * .mfs: See impl.c.poolmfs, <design/poolmfs/>.
 *
 * The MFS outer structure is declared here because it is inlined
 * in the control pool structure which is inlined in the arena.  Normally,
 * pool outer structures are declared with the pools.
 *
 * The signature is placed at the end, see
- * design.mps.pool.outer-structure.sig. */
+ * <design/pool/#outer-structure.sig>. */
 #define MFSSig          ((Sig)0x5193F599) /* SIGnature MFS */
@@ -130,13 +130,13 @@ typedef struct MFSStruct {      /* MFS outer structure */
  Word unitsPerExtent;          /* number of units per arena alloc */
  struct MFSHeaderStruct *freeList; /* head of the free list */
  Tract tractList;              /* the first tract */
-  Sig sig;                      /* design.mps.sig */
+  Sig sig;                      /* <design/sig/> */
 } MFSStruct;
 /* MVStruct -- MV (Manual Variable) pool outer structure
 *
- * .mv: See impl.c.poolmv, design.mps.poolmv.
+ * .mv: See impl.c.poolmv, <design/poolmv/>.
 *
 * The MV pool outer structure is declared here because it is the
 * control pool structure which is inlined in the arena.  Normally,
@@ -152,15 +152,15 @@ typedef struct MVStruct {       /* MV pool outer structure */
  Size avgSize;                 /* client estimate of allocation size */
  Size maxSize;                 /* client estimate of maximum size */
  Size space;                   /* total free space in pool */
-  Size lost;                    /* design.mps.poolmv.lost */
+  Size lost;                    /* <design/poolmv/#lost> */
  RingStruct spans;             /* span chain */
-  Sig sig;                      /* design.mps.sig */
+  Sig sig;                      /* <design/sig/> */
 } MVStruct;
 /* ReservoirStruct -- Reservoir structure
 *
- * .reservoir: See impl.c.reserv, design.mps.reservoir.
+ * .reservoir: See impl.c.reserv, <design/reservoir/>.
 *
 * The Reservoir structure is declared here because it is in-lined in
 * the arena for storing segments for the low-memory reservoir.  It is
@@ -175,19 +175,19 @@ typedef struct ReservoirStruct {   /* Reservoir structure */
  Tract reserve;                /* linked list of reserve tracts */
  Size reservoirLimit;          /* desired reservoir size */
  Size reservoirSize;           /* actual reservoir size */
-  Sig sig;                      /* design.mps.sig */
+  Sig sig;                      /* <design/sig/> */
 } ReservoirStruct;
 /* MessageClassStruct -- Message Class structure
 *
- * See design.mps.message.class.struct (and design.mps.message.message,
+ * See <design/message/#class.struct> (and <design/message/#message>,
- * and design.mps.message.class).  */
+ * and <design/message/#class>).  */
 #define MessageClassSig ((Sig)0x519359c1) /* SIGnature MeSsaGe CLass */
 typedef struct MessageClassStruct {
-  Sig sig;                      /* design.mps.sig */
+  Sig sig;                      /* <design/sig/> */
  const char *name;             /* Human readable Class name */
  /* generic methods */
@@ -201,17 +201,17 @@ typedef struct MessageClassStruct {
  MessageGCCondemnedSizeMethod gcCondemnedSize;
  MessageGCNotCondemnedSizeMethod gcNotCondemnedSize;
-  Sig endSig;                   /* design.mps.message.class.sig.double */
+  Sig endSig;                   /* <design/message/#class.sig.double> */
 } MessageClassStruct;
 #define MessageSig      ((Sig)0x5193e559) /* SIG MESSaGe */
 /* MessageStruct -- Message structure
 *
- * See design.mps.message.message.struct.  */
+ * See <design/message/#message.struct>.  */
 typedef struct MessageStruct {
-  Sig sig;                      /* design.mps.sig */
+  Sig sig;                      /* <design/sig/> */
  Arena arena;                  /* owning arena */
  MessageType type;             /* Message Type */
  MessageClass class;           /* Message Class Structure */
@@ -221,7 +221,7 @@ typedef struct MessageStruct {
 /* SegClassStruct -- segment class structure
 *
- * See design.mps.seg & design.mps.protocol.
+ * See <design/seg/> & <design/protocol/>.
 *
 * .seg.class: The segment class structure is defined by each segment
 * class implementation in order to provide a generic interface to
@@ -252,7 +252,7 @@ typedef struct SegClassStruct {
 /* SegStruct -- segment structure
 *
 * .seg: Segments are the basic units of protection and tracer activity
- * for allocated memory.  See design.mps.seg.  */
+ * for allocated memory.  See <design/seg/>.  */
 #define SegSig      ((Sig)0x5195E999) /* SIGnature SEG  */
@@ -275,7 +275,7 @@ typedef struct SegStruct {      /* segment structure */
 /* GCSegStruct -- GCable segment structure
 *
 * .seggc: GCSeg is a subclass of Seg with support for buffered
- * allocation and GC.  See design.mps.seg.  */
+ * allocation and GC.  See <design/seg/>.  */
 #define GCSegSig      ((Sig)0x5199C5E9) /* SIGnature GC SEG  */
@@ -284,7 +284,7 @@ typedef struct GCSegStruct {    /* GC segment structure */
  RingStruct greyRing;          /* link in list of grey segs */
  RefSet summary;               /* summary of references out of seg */
  Buffer buffer;                /* non-NULL if seg is buffered */
-  Sig sig;                      /* design.mps.sig */
+  Sig sig;                      /* <design/sig/> */
 } GCSegStruct;
@@ -310,7 +310,7 @@ typedef struct SegPrefStruct {  /* segment placement preferences */
 /* BufferClassStruct -- buffer class structure
 *
- * See design.mps.buffer & design.mps.protocol.
+ * See <design/buffer/> & <design/protocol/>.
 *
 * .buffer.class: The buffer class structure is defined by each buffer
 * class implementation in order to provide a generic interface to
@@ -339,7 +339,7 @@ typedef struct BufferClassStruct {
 /* APStruct -- allocation point structure
 *
- * AP are part of the design of buffers see design.mps.buffer.
+ * AP are part of the design of buffers see <design/buffer/>.
 *
 * The allocation point is exported to the client code so that it can
 * do in-line buffered allocation.
@@ -359,14 +359,14 @@ typedef struct APStruct {
 /* BufferStruct -- allocation buffer structure
 *
- * See impl.c.buffer, design.mps.buffer.
+ * See impl.c.buffer, <design/buffer/>.
 *
 * The buffer contains an AP which may be exported to the client.  */
 #define BufferSig       ((Sig)0x519B0FFE) /* SIGnature BUFFEr */
 typedef struct BufferStruct {
-  Sig sig;                      /* design.mps.sig */
+  Sig sig;                      /* <design/sig/> */
  BufferClass class;            /* buffer class structure */
  Serial serial;                /* from pool->bufferSerial */
  Arena arena;                  /* owning arena */
@@ -396,7 +396,7 @@ typedef struct SegBufStruct {
  BufferStruct bufferStruct;    /* superclass fields must come first */
  RankSet rankSet;              /* ranks of references being created */
  Seg seg;                      /* segment being buffered */
-  Sig sig;                      /* design.mps.sig */
+  Sig sig;                      /* <design/sig/> */
 } SegBufStruct;
@@ -462,7 +462,7 @@ typedef struct ScanStateStruct {
  Word zoneShift;               /* copy of arena->zoneShift.  See .ss.zone */
  ZoneSet white;                /* white set, for inline fix test */
  RefSet unfixedSummary;        /* accumulated summary of scanned references */
-  Sig sig;                      /* design.mps.sig */
+  Sig sig;                      /* <design/sig/> */
  Arena arena;                  /* owning arena */
  TraceSet traces;              /* traces to scan for */
  Rank rank;                    /* reference rank of scanning */
@@ -487,7 +487,7 @@ typedef struct ScanStateStruct {
 #define TraceSig ((Sig)0x51924ACE) /* SIGnature TRACE */
 typedef struct TraceStruct {
-  Sig sig;                      /* design.mps.sig */
+  Sig sig;                      /* <design/sig/> */
  TraceId ti;                   /* index into TraceSets */
  Arena arena;                  /* owning arena */
  ZoneSet white;                /* zones in the white set */
@@ -580,7 +580,7 @@ typedef struct GlobalsStruct {
  Lock lock;                    /* arena's lock */
  /* polling fields (impl.c.global) */
-  double pollThreshold;         /* design.mps.arena.poll */
+  double pollThreshold;         /* <design/arena/#poll> */
  Bool insidePoll;
  Bool clamped;                 /* prevent background activity */
  double fillMutatorSize;       /* total bytes filled, mutator buffers */
@@ -593,7 +593,7 @@ typedef struct GlobalsStruct {
  const char *mpsVersionString; /* MPSVersion() */
  /* buffer fields (impl.c.buffer) */
-  Bool bufferLogging;           /* design.mps.buffer.logging.control */
+  Bool bufferLogging;           /* <design/buffer/#logging.control> */
  /* pool fields (impl.c.pool) */
  RingStruct poolRing;          /* ring of pools in arena */
@@ -612,15 +612,15 @@ typedef struct GlobalsStruct {
 #define ArenaSig        ((Sig)0x519A6E4A) /* SIGnature ARENA */
 typedef struct ArenaStruct {
-  GlobalsStruct globals; /* must be first, see design.mps.arena.globals */
+  GlobalsStruct globals; /* must be first, see <design/arena/#globals> */
  Serial serial;
  ArenaClass class;             /* arena class structure */
-  Bool poolReady;               /* design.mps.arena.pool.ready */
+  Bool poolReady;               /* <design/arena/#pool.ready> */
-  MVStruct controlPoolStruct;   /* design.mps.arena.pool */
+  MVStruct controlPoolStruct;   /* <design/arena/#pool> */
-  ReservoirStruct reservoirStruct; /* design.mps.reservoir */
+  ReservoirStruct reservoirStruct; /* <design/reservoir/> */
  Size committed;               /* amount of committed RAM */
  Size commitLimit;             /* client-configurable commit limit */
@@ -646,11 +646,11 @@ typedef struct ArenaStruct {
  RingStruct formatRing;        /* ring of formats attached to arena */
  Serial formatSerial;          /* serial of next format */
-  /* message fields (design.mps.message, impl.c.message) */
+  /* message fields (<design/message/>, impl.c.message) */
  RingStruct messageRing;       /* ring of pending messages */
  BT enabledMessageTypes;       /* map of which types are enabled */
-  /* finalization fields (design.mps.finalize), impl.c.poolmrg */
+  /* finalization fields (<design/finalize/>), impl.c.poolmrg */
  Bool isFinalPool;             /* indicator for finalPool */
  Pool finalPool;               /* either NULL or an MRG pool */
@@ -670,15 +670,15 @@ typedef struct ArenaStruct {
  TraceSet busyTraces;          /* set of running traces */
  TraceSet flippedTraces;       /* set of running and flipped traces */
  TraceStruct trace[TraceLIMIT]; /* trace structures.  See
-                                   design.mps.trace.intance.limit */
+                                   <design/trace/#intance.limit> */
  RingStruct greyRing[RankLIMIT]; /* ring of grey segments at each rank */
  STATISTIC_DECL(Count writeBarrierHitCount); /* write barrier hits */
  RingStruct chainRing;         /* ring of chains */
  /* location dependency fields (impl.c.ld) */
-  Epoch epoch;                     /* design.mps.arena.ld.epoch */
+  Epoch epoch;                     /* <design/arena/#ld.epoch> */
-  RefSet prehistory;               /* design.mps.arena.ld.prehistory */
+  RefSet prehistory;               /* <design/arena/#ld.prehistory> */
-  RefSet history[LDHistoryLENGTH]; /* design.mps.arena.ld.history */
+  RefSet history[LDHistoryLENGTH]; /* <design/arena/#ld.history> */
  Sig sig;
 } ArenaStruct;
diff --git a/mps/code/mpmtypes.h b/mps/code/mpmtypes.h
index 7bcd2f00b5c..a92a38169c4 100644
--- a/mps/code/mpmtypes.h
+++ b/mps/code/mpmtypes.h
@@ -3,7 +3,7 @@
 * $Id$
 * Copyright (c) 2001 Ravenbrook Limited.  See end of file for license.
 *
- * .design: design.mps.type
+ * .design: <design/type/>
 *
 * .rationale: Types and type constants are almost all defined
 * in this header, in advance of any declarations of prototypes
@@ -24,21 +24,21 @@
 /* TYPES */
-typedef unsigned long Sig;              /* design.mps.sig */
+typedef unsigned long Sig;              /* <design/sig/> */
-typedef int Res;                        /* design.mps.type.res */
+typedef int Res;                        /* <design/type/#res> */
-typedef void (*Fun)(void);              /* design.mps.type.fun */
+typedef void (*Fun)(void);              /* <design/type/#fun> */
-typedef MPS_T_WORD Word;                /* design.mps.type.word */
+typedef MPS_T_WORD Word;                /* <design/type/#word> */
-typedef unsigned char Byte;             /* design.mps.type.byte */
+typedef unsigned char Byte;             /* <design/type/#byte> */
-typedef struct AddrStruct *Addr;        /* design.mps.type.addr */
+typedef struct AddrStruct *Addr;        /* <design/type/#addr> */
-typedef Word Size;                      /* design.mps.type.size */
+typedef Word Size;                      /* <design/type/#size> */
-typedef Word Count;                     /* design.mps.type.count */
+typedef Word Count;                     /* <design/type/#count> */
-typedef Word Index;                     /* design.mps.type.index */
+typedef Word Index;                     /* <design/type/#index> */
-typedef Word Align;                     /* design.mps.type.align */
+typedef Word Align;                     /* <design/type/#align> */
-typedef unsigned Shift;                 /* design.mps.type.shift */
+typedef unsigned Shift;                 /* <design/type/#shift> */
-typedef unsigned Serial;                /* design.mps.type.serial */
+typedef unsigned Serial;                /* <design/type/#serial> */
-typedef Addr Ref;                       /* design.mps.type.ref */
+typedef Addr Ref;                       /* <design/type/#ref> */
-typedef void *Pointer;                  /* design.mps.type.pointer */
+typedef void *Pointer;                  /* <design/type/#pointer> */
 typedef Word RefSet;                    /* design.mps.refset */
 typedef Word ZoneSet;                   /* design.mps.refset */
@@ -46,28 +46,28 @@ typedef unsigned Rank;
 typedef unsigned RankSet;
 typedef unsigned RootMode;
 typedef Size Epoch;                     /* design.mps.ld */
-typedef unsigned TraceId;               /* design.mps.trace */
+typedef unsigned TraceId;               /* <design/trace/> */
-typedef unsigned TraceSet;              /* design.mps.trace */
+typedef unsigned TraceSet;              /* <design/trace/> */
-typedef unsigned TraceState;            /* design.mps.trace */
+typedef unsigned TraceState;            /* <design/trace/> */
-typedef unsigned AccessSet;             /* design.mps.type.access-set */
+typedef unsigned AccessSet;             /* <design/type/#access-set> */
-typedef unsigned Attr;                  /* design.mps.type.attr */
+typedef unsigned Attr;                  /* <design/type/#attr> */
 typedef unsigned FormatVariety;        
-typedef int RootVar;                    /* design.mps.type.rootvar */
+typedef int RootVar;                    /* <design/type/#rootvar> */
-typedef Word *BT;                       /* design.mps.bt */
+typedef Word *BT;                       /* <design/bt/> */
 typedef struct BootBlockStruct *BootBlock; /* impl.c.boot */
-typedef struct BufferStruct *Buffer;    /* design.mps.buffer */
+typedef struct BufferStruct *Buffer;    /* <design/buffer/> */
-typedef struct SegBufStruct *SegBuf;    /* design.mps.buffer */
+typedef struct SegBufStruct *SegBuf;    /* <design/buffer/> */
-typedef struct BufferClassStruct *BufferClass; /* design.mps.buffer */
+typedef struct BufferClassStruct *BufferClass; /* <design/buffer/> */
-typedef BufferClass SegBufClass;        /* design.mps.buffer */
+typedef BufferClass SegBufClass;        /* <design/buffer/> */
-typedef BufferClass RankBufClass;       /* design.mps.buffer */
+typedef BufferClass RankBufClass;       /* <design/buffer/> */
-typedef unsigned BufferMode;            /* design.mps.buffer */
+typedef unsigned BufferMode;            /* <design/buffer/> */
-typedef unsigned FrameState;            /* design.mps.alloc-frame */
+typedef unsigned FrameState;            /* <design/alloc-frame/> */
-typedef struct APStruct *AP;            /* design.mps.buffer */
+typedef struct APStruct *AP;            /* <design/buffer/> */
 typedef struct FormatStruct *Format;    /* design.mps.format */
 typedef struct LDStruct *LD;            /* design.mps.ld */
 typedef struct LockStruct *Lock;        /* impl.c.lock* */
-typedef struct PoolStruct *Pool;        /* design.mps.pool */
+typedef struct PoolStruct *Pool;        /* <design/pool/> */
 typedef struct PoolClassStruct *PoolClass; /* impl.c.poolclas */
 typedef PoolClass AbstractPoolClass;    /* impl.c.poolabs */
 typedef PoolClass AbstractAllocFreePoolClass; /* impl.c.poolabs */
@@ -75,10 +75,10 @@ typedef PoolClass AbstractBufferPoolClass; /* impl.c.poolabs */
 typedef PoolClass AbstractSegBufPoolClass; /* impl.c.poolabs */
 typedef PoolClass AbstractScanPoolClass; /* impl.c.poolabs */
 typedef PoolClass AbstractCollectPoolClass; /* impl.c.poolabs */
-typedef struct TraceStruct *Trace;      /* design.mps.trace */
+typedef struct TraceStruct *Trace;      /* <design/trace/> */
-typedef struct ScanStateStruct *ScanState; /* design.mps.trace */
+typedef struct ScanStateStruct *ScanState; /* <design/trace/> */
-typedef struct ChainStruct *Chain;      /* design.mps.trace */
+typedef struct ChainStruct *Chain;      /* <design/trace/> */
-typedef struct TractStruct *Tract;      /* design.mps.arena */
+typedef struct TractStruct *Tract;      /* <design/arena/> */
 typedef struct ChunkStruct *Chunk;      /* impl.c.tract */
 typedef struct ChunkCacheEntryStruct *ChunkCacheEntry; /* impl.c.tract */
 typedef struct PageStruct *Page;        /* impl.c.tract */
@@ -88,19 +88,19 @@ typedef struct SegClassStruct *SegClass; /* impl.c.seg */
 typedef SegClass GCSegClass;            /* impl.c.seg */
 typedef struct SegPrefStruct *SegPref;  /* design.mps.pref, impl.c.locus */
 typedef int SegPrefKind;                /* design.mps.pref, impl.c.locus */
-typedef struct ArenaClassStruct *ArenaClass; /* design.mps.arena */
+typedef struct ArenaClassStruct *ArenaClass; /* <design/arena/> */
 typedef ArenaClass AbstractArenaClass;  /* impl.c.arena */
-typedef struct ArenaStruct *Arena;      /* design.mps.arena */
+typedef struct ArenaStruct *Arena;      /* <design/arena/> */
-typedef struct GlobalsStruct *Globals;  /* design.mps.arena */
+typedef struct GlobalsStruct *Globals;  /* <design/arena/> */
 typedef struct VMStruct *VM;            /* impl.c.vm* */
 typedef struct RootStruct *Root;        /* impl.c.root */
 typedef struct ThreadStruct *Thread;    /* impl.c.th* */
 typedef struct MutatorFaultContextStruct
-        *MutatorFaultContext;           /* design.mps.prot */
+        *MutatorFaultContext;           /* <design/prot/> */
 typedef struct PoolDebugMixinStruct *PoolDebugMixin;
 typedef struct AllocPatternStruct *AllocPattern;
-typedef struct AllocFrameStruct *AllocFrame; /* design.mps.alloc-frame */
+typedef struct AllocFrameStruct *AllocFrame; /* <design/alloc-frame/> */
-typedef struct ReservoirStruct *Reservoir;   /* design.mps.reservoir */
+typedef struct ReservoirStruct *Reservoir;   /* <design/reservoir/> */
 /* Arena*Method -- see impl.h.mpmst.ArenaClassStruct */
@@ -121,7 +121,7 @@ typedef Res (*ArenaDescribeMethod)(Arena arena, mps_lib_FILE *stream);
 /* Messages
 *
- * See design.mps.message
+ * See <design/message/>
 */
 typedef unsigned MessageType;
@@ -140,7 +140,7 @@ typedef Res (*TraceFixMethod)(ScanState ss, Ref *refIO);
 typedef void (*FormattedObjectsStepMethod)(Addr, Format, Pool,
                                           void *, Size);
-/* Seg*Method -- see design.mps.seg */
+/* Seg*Method -- see <design/seg/> */
 typedef Res (*SegInitMethod)(Seg seg, Pool pool, Addr base, Size size,
                             Bool withReservoirPermit, va_list args);
@@ -161,7 +161,7 @@ typedef Res (*SegSplitMethod)(Seg seg, Seg segHi,
                              Addr base, Addr mid, Addr limit,
                              Bool withReservoirPermit, va_list args);
-/* Buffer*Method -- see design.mps.buffer */
+/* Buffer*Method -- see <design/buffer/> */
 typedef Res (*BufferInitMethod)(Buffer buffer, Pool pool, va_list args);
 typedef void (*BufferFinishMethod)(Buffer buffer);
@@ -175,7 +175,7 @@ typedef void (*BufferReassignSegMethod)(Buffer buffer, Seg seg);
 typedef Res (*BufferDescribeMethod)(Buffer buffer, mps_lib_FILE *stream);
-/* Pool*Method -- see design.mps.class-interface */
+/* Pool*Method -- see <design/class-interface/> */
 /* Order of types corresponds to PoolClassStruct in impl.h.mpmst */
@@ -218,7 +218,7 @@ typedef Res (*PoolDescribeMethod)(Pool pool, mps_lib_FILE *stream);
 typedef PoolDebugMixin (*PoolDebugMixinMethod)(Pool pool);
-/* Message*Method -- design.mps.message */
+/* Message*Method -- <design/message/> */
 typedef void (*MessageDeleteMethod)(Message message);
 typedef void (*MessageFinalizationRefMethod)
@@ -228,7 +228,7 @@ typedef Size (*MessageGCCondemnedSizeMethod)(Message message);
 typedef Size (*MessageGCNotCondemnedSizeMethod)(Message message);
-/* Message Types -- design.mps.message and elsewhere */
+/* Message Types -- <design/message/> and elsewhere */
 typedef struct MessageFinalizationStruct *MessageFinalization;
@@ -246,7 +246,7 @@ typedef void (*FormatPadMethod)(Addr base, Size size);
 typedef Addr (*FormatClassMethod)(Addr object);
-/* Root*Method -- see design.mps.root-interface */
+/* Root*Method -- see <design/root/>-interface */
 /* .root-methods: These methods must match those defined in the */
 /* MPS C Interface.  (See impl.h.mps.root-methods.) */
@@ -257,11 +257,11 @@ typedef Res (*RootScanRegMethod)(ScanState ss, Thread thread, void *p, size_t s)
 /* CONSTANTS */
-/* design.mps.sig SIGnature IS BAD */
+/* <design/sig/> SIGnature IS BAD */
 #define SigInvalid      ((Sig)0x51915BAD)
 #define SizeMAX         ((Size)-1)
-#define AccessSetEMPTY  ((AccessSet)0) /* design.mps.type.access-set */
+#define AccessSetEMPTY  ((AccessSet)0) /* <design/type/#access-set> */
 #define AccessREAD      ((AccessSet)(1<<0))
 #define AccessWRITE     ((AccessSet)(1<<1))
 #define AccessSetWIDTH  (2)
@@ -273,7 +273,7 @@ typedef Res (*RootScanRegMethod)(ScanState ss, Thread thread, void *p, size_t s)
 #define TraceSetUNIV    ((TraceSet)((1u << TraceLIMIT) - 1))
 #define RankSetEMPTY    BS_EMPTY(RankSet)
 #define RankSetUNIV     ((RankSet)((1u << RankLIMIT) - 1))
-#define AttrFMT         ((Attr)(1<<0))  /* design.mps.type.attr */
+#define AttrFMT         ((Attr)(1<<0))  /* <design/type/#attr> */
 #define AttrSCAN        ((Attr)(1<<1))
 #define AttrPM_NO_READ  ((Attr)(1<<2))
 #define AttrPM_NO_WRITE ((Attr)(1<<3))
@@ -319,7 +319,7 @@ enum {
 #define BufferModeTRANSITION    ((BufferMode)(1<<3))
-/* Buffer frame states. See design.mps.alloc-frame.lw-frame.states */
+/* Buffer frame states. See <design/alloc-frame/#lw-frame.states> */
 enum {
  BufferFrameVALID = 1,
  BufferFramePOP_PENDING,
@@ -327,7 +327,7 @@ enum {
 };
-/* Rank constants -- see design.mps.type.rank */
+/* Rank constants -- see <design/type/#rank> */
 /* These definitions must match impl.h.mps.rank. */
 /* This is checked by impl.c.mpsi.check. */
@@ -350,7 +350,7 @@ enum {
 #define RootModePROTECTABLE_INNER ((RootMode)1<<2)
-/* Root Variants -- see design.mps.type.rootvar
+/* Root Variants -- see <design/type/#rootvar>
 *
 * .rootvar: Synchonize with impl.c.root.rootvarcheck
 */
@@ -365,7 +365,7 @@ enum {
 };
-/* .result-codes: Result Codes -- see design.mps.type.res */
+/* .result-codes: Result Codes -- see <design/type/#res> */
 /* These definitions must match impl.h.mps.result-codes. */
 /* This is checked by impl.c.mpsi.check.rc. */
 /* Changing this list entails changing the list in */
@@ -384,7 +384,7 @@ enum {
 };
-/* TraceStates -- see design.mps.trace */
+/* TraceStates -- see <design/trace/> */
 enum {
  TraceINIT = 1,
@@ -395,7 +395,7 @@ enum {
 };
-/* MessageTypes -- see design.mps.message */
+/* MessageTypes -- see <design/message/> */
 /* .message.types: Keep in sync with impl.h.mps.message.types */
 enum {
diff --git a/mps/code/mps.h b/mps/code/mps.h
index 823137e8f08..4fc132d7882 100644
--- a/mps/code/mps.h
+++ b/mps/code/mps.h
@@ -4,7 +4,7 @@
 * Copyright (c) 2001 Ravenbrook Limited.  See end of file for license.
 *
 * .readership: customers, MPS developers.
- * .sources: design.mps.interface.c.
+ * .sources: <design/interface-c/>.
 */
 #ifndef mps_h
diff --git a/mps/code/mpsi.c b/mps/code/mpsi.c
index ae4e3ae6ecf..a2caccc3a72 100644
--- a/mps/code/mpsi.c
+++ b/mps/code/mpsi.c
@@ -9,7 +9,7 @@
 * usage of the MPS Interface.  .purpose.thread: It excludes multiple
 * threads from the MPM by locking the Arena (see .thread-safety).
 *
- * .design: design.mps.interface.c
+ * .design: <design/interface-c/>
 *
 *
 * NOTES
@@ -44,7 +44,7 @@
 * interface is designed allows for the possibility of change.
 *
 * .naming: (rule.impl.guide) The exported identifiers do not follow the
- * normal MPS naming conventions.  See design.mps.interface.c.naming.  */
+ * normal MPS naming conventions.  See <design/interface-c/#naming>.  */
 #include "mpm.h"
 #include "mps.h"
@@ -91,7 +91,7 @@ static Bool mpsi_check(void)
  CHECKL((int)MPS_RANK_WEAK == (int)RankWEAK);
  /* The external idea of a word width and the internal one */
-  /* had better match.  See design.mps.interface.c.cons. */
+  /* had better match.  See <design/interface-c/#cons>. */
  CHECKL(sizeof(mps_word_t) == sizeof(void *));
  CHECKL(CHECKTYPE(mps_word_t, Word));
@@ -100,8 +100,8 @@ static Bool mpsi_check(void)
  CHECKL(CHECKTYPE(mps_addr_t, Addr));
  /* The external idea of size and the internal one had */
-  /* better match.  See design.mps.interface.c.cons.size */
+  /* better match.  See <design/interface-c/#cons.size> */
-  /* and design.mps.interface.c.pun.size. */
+  /* and <design/interface-c/#pun.size>. */
  CHECKL(CHECKTYPE(size_t, Size));
  /* Check ap_s/APStruct compatibility by hand */
@@ -146,7 +146,7 @@ static Bool mpsi_check(void)
  /* are not equal.  See impl.h.mpmst.ss.  CHECKFIELDAPPROX */
  /* is used on the fix field because its type is punned and */
  /* therefore isn't exactly checkable.  See */
-  /* design.mps.interface.c.pun.addr. */
+  /* <design/interface-c/#pun.addr>. */
  CHECKL(CHECKFIELDAPPROX(mps_ss_s, fix, ScanStateStruct, fix));
  CHECKL(CHECKFIELD(mps_ss_s, w0, ScanStateStruct, zoneShift));
  CHECKL(CHECKFIELD(mps_ss_s, w1, ScanStateStruct, white));
@@ -461,7 +461,7 @@ mps_bool_t mps_arena_has_addr(mps_arena_t mps_arena, mps_addr_t p)
 *
 * .fmt.create.A.purpose: This function converts an object format spec
 * of variant "A" into an MPM Format object.  See
- * design.mps.interface.c.fmt.extend for justification of the way that
+ * <design/interface-c/#fmt.extend> for justification of the way that
 * the format structure is declared as "mps_fmt_A".  */
 mps_res_t mps_fmt_create_A(mps_fmt_t *mps_fmt_o,
@@ -653,7 +653,7 @@ mps_res_t mps_alloc(mps_addr_t *p_o, mps_pool_t mps_pool, size_t size, ...)
  AVERT(Pool, pool);
  AVER(size > 0);
  /* Note: class may allow unaligned size, see */
-  /* design.mps.class-interface.alloc.size.align. */
+  /* <design/class-interface/#alloc.size.align>. */
  /* Rest ignored, see .varargs. */
  /* @@@@ There is currently no requirement for reservoirs to work */
@@ -693,7 +693,7 @@ void mps_free(mps_pool_t mps_pool, mps_addr_t p, size_t size)
  AVER(PoolHasAddr(pool, p));
  AVER(size > 0);
  /* Note: class may allow unaligned size, see */
-  /* design.mps.class-interface.alloc.size.align. */
+  /* <design/class-interface/#alloc.size.align>. */
  PoolFree(pool, (Addr)p, size);
  ArenaLeave(arena);
@@ -852,7 +852,7 @@ mps_bool_t (mps_commit)(mps_ap_t mps_ap, mps_addr_t p, size_t size)
 /* mps_ap_frame_push -- push a new allocation frame
 *
- * See design.mps.alloc-frame.lw-frame.push. */
+ * See <design/alloc-frame/#lw-frame.push>. */
 mps_res_t (mps_ap_frame_push)(mps_frame_t *frame_o, mps_ap_t mps_ap)
 {
@@ -893,7 +893,7 @@ mps_res_t (mps_ap_frame_push)(mps_frame_t *frame_o, mps_ap_t mps_ap)
 /* mps_ap_frame_pop -- push a new allocation frame
 *
- * See design.mps.alloc-frame.lw-frame.pop.  */
+ * See <design/alloc-frame/#lw-frame.pop>.  */
 mps_res_t (mps_ap_frame_pop)(mps_ap_t mps_ap, mps_frame_t frame)
 {
@@ -1402,7 +1402,7 @@ void mps_ld_reset(mps_ld_t mps_ld, mps_arena_t mps_arena)
 /* mps_ld_add -- add a reference to a location dependency
 *
- * See design.mps.interface.c.lock-free.  */
+ * See <design/interface-c/#lock-free>.  */
 void mps_ld_add(mps_ld_t mps_ld, mps_arena_t mps_arena, mps_addr_t addr)
 {
@@ -1415,7 +1415,7 @@ void mps_ld_add(mps_ld_t mps_ld, mps_arena_t mps_arena, mps_addr_t addr)
 /* mps_ld_merge -- merge two location dependencies
 *
- * See design.mps.interface.c.lock-free.  */
+ * See <design/interface-c/#lock-free>.  */
 void mps_ld_merge(mps_ld_t mps_ld, mps_arena_t mps_arena,
                  mps_ld_t mps_from)
@@ -1430,7 +1430,7 @@ void mps_ld_merge(mps_ld_t mps_ld, mps_arena_t mps_arena,
 /* mps_ld_isstale -- check whether a location dependency is "stale"
 *
- * See design.mps.interface.c.lock-free.  */
+ * See <design/interface-c/#lock-free>.  */
 mps_bool_t mps_ld_isstale(mps_ld_t mps_ld, mps_arena_t mps_arena,
                          mps_addr_t addr)
diff --git a/mps/code/mpsio.h b/mps/code/mpsio.h
index 43dfe096316..db3149dff58 100644
--- a/mps/code/mpsio.h
+++ b/mps/code/mpsio.h
@@ -4,7 +4,7 @@
 * Copyright (c) 2001 Ravenbrook Limited.  See end of file for license.
 *
 * .readership: For MPS client application developers, MPS developers.
- * .sources: design.mps.io
+ * .sources: <design/io/>
 */
 #ifndef mpsio_h
diff --git a/mps/code/mpsioan.c b/mps/code/mpsioan.c
index 99fd9e95cb7..fd7dea92601 100644
--- a/mps/code/mpsioan.c
+++ b/mps/code/mpsioan.c
@@ -4,7 +4,7 @@
 * Copyright (c) 2001 Ravenbrook Limited.  See end of file for license.
 *
 * .readership: For MPS client application developers and MPS developers.
- * .sources: design.mps.io
+ * .sources: <design/io/>
 */
 #include "mpsio.h"
diff --git a/mps/code/mpslib.h b/mps/code/mpslib.h
index 1c4864bff45..3d4251de2b5 100644
--- a/mps/code/mpslib.h
+++ b/mps/code/mpslib.h
@@ -4,7 +4,7 @@
 * Copyright (c) 2001 Ravenbrook Limited.  See end of file for license.
 *
 * .readership: MPS client application developers, MPS developers.
- * .sources: design.mps.lib
+ * .sources: <design/lib/>
 *
 * .purpose: The purpose of this file is to declare the functions and types
 * required for the MPS library interface.
diff --git a/mps/code/mpsliban.c b/mps/code/mpsliban.c
index 6b58c8417b5..4705b70c523 100644
--- a/mps/code/mpsliban.c
+++ b/mps/code/mpsliban.c
@@ -10,7 +10,7 @@
 *      Interface.
 *
 * .readership: For MPS client application developers and MPS developers.
- * .sources: design.mps.lib
+ * .sources: <design/lib/>
 *
 *
 * TRANSGRESSIONS (rule.impl.trans)
diff --git a/mps/code/mpsw3.h b/mps/code/mpsw3.h
index 4a11f66e9ea..e7cf8159606 100644
--- a/mps/code/mpsw3.h
+++ b/mps/code/mpsw3.h
@@ -4,7 +4,7 @@
 * Copyright (c) 2001 Ravenbrook Limited.  See end of file for license.
 *
 * .readership: customers, MPS developers.
- * .sources: design.mps.interface.c.
+ * .sources: <design/interface-c/>.
 */
 #ifndef mpsw3_h
diff --git a/mps/code/pool.c b/mps/code/pool.c
index bc4c49b774e..0728824743e 100644
--- a/mps/code/pool.c
+++ b/mps/code/pool.c
@@ -5,7 +5,7 @@
 *
 * DESIGN
 *
- * .design: See design.mps.class-interface and design.mps.pool.
+ * .design: See <design/class-interface/> and <design/pool/>.
 *
 * PURPOSE
 *
@@ -99,7 +99,7 @@ Bool PoolCheck(Pool pool)
 /* PoolInit, PoolInitV -- initialize a pool
 *
 * Initialize the generic fields of the pool and calls class-specific
- * init.  See design.mps.pool.align.  */
+ * init.  See <design/pool/#align>.  */
 Res PoolInit(Pool pool, Arena arena, PoolClass class, ...)
 {
@@ -130,7 +130,7 @@ Res PoolInitV(Pool pool, Arena arena, PoolClass class, va_list args)
    /* putting another lock in the code. */
    class->labelled = TRUE;
    classId = EventInternString(class->name);
-    /* @@@@ this breaks design.mps.type.addr.use */
+    /* @@@@ this breaks <design/type/#addr.use> */
    EventLabelAddr((Addr)class, classId);
  }
@@ -147,7 +147,7 @@ Res PoolInitV(Pool pool, Arena arena, PoolClass class, va_list args)
  pool->fillInternalSize = 0.0;
  pool->emptyInternalSize = 0.0;
-  /* Initialise signature last; see design.mps.sig */
+  /* Initialise signature last; see <design/sig/> */
  pool->sig = PoolSig;
  pool->serial = globals->poolSerial;
  ++(globals->poolSerial);
@@ -399,7 +399,7 @@ Res PoolScan(Bool *totalReturn, ScanState ss, Pool pool, Seg seg)
 /* PoolFix* -- fix a reference to an object in this pool
 *
- * See impl.h.mpm for macro version; see design.mps.pool.req.fix. */
+ * See impl.h.mpm for macro version; see <design/pool/#req.fix>. */
 Res (PoolFix)(Pool pool, ScanState ss, Seg seg, Addr *refIO)
 {
diff --git a/mps/code/poolabs.c b/mps/code/poolabs.c
index f888e9cb885..9269a586e53 100644
--- a/mps/code/poolabs.c
+++ b/mps/code/poolabs.c
@@ -181,7 +181,7 @@ DEFINE_CLASS(AbstractCollectPoolClass, class)
 /* PoolNo*, PoolTriv* -- Trivial and non-methods for Pool Classes
 *
- * See design.mps.pool.no and design.mps.pool.triv
+ * See <design/pool/#no> and <design/pool/#triv>
 */
diff --git a/mps/code/poolamc.c b/mps/code/poolamc.c
index 6a46d1554ec..62aad6f08be 100644
--- a/mps/code/poolamc.c
+++ b/mps/code/poolamc.c
@@ -3,7 +3,7 @@
 * $Id$
 * Copyright (c) 2001 Ravenbrook Limited.  See end of file for license.
 *
- * .sources: design.mps.poolamc.
+ * .sources: <design/poolamc/>.
 */
 #include "mpscamc.h"
@@ -76,7 +76,7 @@ typedef struct amcNailboardStruct {
 * .segtype: AMC segs have a pointer to the type field of either
 * a nailboard or a generation. This initial value is passed
 * as an additional parameter when the segment is allocated.
- * See design.mps.poolamc.fix.nail.distinguish.
+ * See <design/poolamc/#fix.nail.distinguish>.
 */
 typedef struct amcSegStruct *amcSeg;
@@ -140,7 +140,7 @@ static Res AMCSegInit(Seg seg, Pool pool, Addr base, Size size,
 /* AMCSegDescribe -- describe the contents of a segment
 *
- * See design.mps.poolamc.seg-describe.
+ * See <design/poolamc/#seg-describe>.
 */
 static Res AMCSegDescribe(Seg seg, mps_lib_FILE *stream)
 {
@@ -231,7 +231,7 @@ DEFINE_SEG_CLASS(amcSegClass, class)
 /* amcSegHasNailboard -- test whether the segment has a nailboard
 *
- * See design.mps.poolamc.fix.nail.distinguish.
+ * See <design/poolamc/#fix.nail.distinguish>.
 */
 static Bool amcSegHasNailboard(Seg seg)
 {
@@ -272,12 +272,12 @@ static amcGen amcSegGen(Seg seg)
 /* AMCStruct -- pool AMC descriptor
 *
- * See design.mps.poolamc.struct.
+ * See <design/poolamc/#struct>.
 */
 #define AMCSig          ((Sig)0x519A3C99) /* SIGnature AMC */
-typedef struct AMCStruct {      /* design.mps.poolamc.struct */
+typedef struct AMCStruct {      /* <design/poolamc/#struct> */
  PoolStruct poolStruct;        /* generic pool structure */
  RankSet rankSet;              /* rankSet for entire pool */
  RingStruct genRing;           /* ring of generations */
@@ -288,9 +288,9 @@ typedef struct AMCStruct {      /* design.mps.poolamc.struct */
  amcGen nursery;               /* the default mutator generation */
  amcGen rampGen;               /* the ramp generation */
  amcGen afterRampGen;          /* the generation after rampGen */
-  unsigned rampCount;           /* design.mps.poolamc.ramp.count */
+  unsigned rampCount;           /* <design/poolamc/#ramp.count> */
-  int rampMode;                 /* design.mps.poolamc.ramp.mode */
+  int rampMode;                 /* <design/poolamc/#ramp.mode> */
-  Sig sig;                      /* design.mps.pool.outer-structure.sig */
+  Sig sig;                      /* <design/pool/#outer-structure.sig> */
 } AMCStruct;
 #define Pool2AMC(pool) PARENT(AMCStruct, poolStruct, (pool))
@@ -348,7 +348,7 @@ typedef struct amcBufStruct *amcBuf;
 typedef struct amcBufStruct {
  SegBufStruct segbufStruct;      /* superclass fields must come first */
  amcGen gen;                     /* The AMC generation */
-  Sig sig;                        /* design.mps.sig */
+  Sig sig;                        /* <design/sig/> */
 } amcBufStruct;
@@ -419,7 +419,7 @@ static Res AMCBufInit(Buffer buffer, Pool pool, va_list args)
    /* Set up the buffer to be allocating in the nursery. */
    amcbuf->gen = amc->nursery;
  } else {
-    amcbuf->gen = NULL; /* no gen yet -- see design.mps.poolamc.forward.gen */
+    amcbuf->gen = NULL; /* no gen yet -- see <design/poolamc/#forward.gen> */
  }
  amcbuf->sig = amcBufSig;
  AVERT(amcBuf, amcbuf);
@@ -707,7 +707,7 @@ static Bool amcNailRangeIsMarked(Seg seg, Addr base, Addr limit)
 /* amcInitComm -- initialize AMC/Z pool
 *
- * See design.mps.poolamc.init.
+ * See <design/poolamc/#init>.
 * Shared by AMCInit and AMCZinit.
 */
 static Res amcInitComm(Pool pool, RankSet rankSet, va_list arg)
@@ -811,7 +811,7 @@ static Res AMCZInit(Pool pool, va_list arg)
 /* AMCFinish -- finish AMC pool
 *
- * See design.mps.poolamc.finish.
+ * See <design/poolamc/#finish>.
 */
 static void AMCFinish(Pool pool)
 {
@@ -865,7 +865,7 @@ static void AMCFinish(Pool pool)
 /* AMCBufferFill -- refill an allocation buffer
 *
- * See design.mps.poolamc.fill.
+ * See <design/poolamc/#fill>.
 */
 static Res AMCBufferFill(Addr *baseReturn, Addr *limitReturn,
                         Pool pool, Buffer buffer, Size size,
@@ -909,7 +909,7 @@ static Res AMCBufferFill(Addr *baseReturn, Addr *limitReturn,
  if (res != ResOK)
    return res;
-  /* design.mps.seg.field.rankSet.start */
+  /* <design/seg/#field.rankSet.start> */
  if (BufferRankSet(buffer) == RankSetEMPTY)
    SegSetRankAndSummary(seg, BufferRankSet(buffer), RefSetEMPTY);
  else
@@ -939,7 +939,7 @@ static Res AMCBufferFill(Addr *baseReturn, Addr *limitReturn,
 /* amcBufferEmpty -- detach a buffer from a segment
 *
- * See design.mps.poolamc.flush.
+ * See <design/poolamc/#flush>.
 */
 static void AMCBufferEmpty(Pool pool, Buffer buffer, Addr init, Addr limit)
 {
@@ -960,7 +960,7 @@ static void AMCBufferEmpty(Pool pool, Buffer buffer, Addr init, Addr limit)
  arena = BufferArena(buffer);
-  /* design.mps.poolamc.flush.pad */
+  /* <design/poolamc/#flush.pad> */
  size = AddrOffset(init, limit);
  if (size > 0) {
    ShieldExpose(arena, seg);
@@ -1109,7 +1109,7 @@ static Res AMCWhiten(Pool pool, Trace trace, Seg seg)
  amc = Pool2AMC(pool);
  AVERT(AMC, amc);
-  /* see design.mps.poolamc.gen.ramp */
+  /* see <design/poolamc/#gen.ramp> */
  /* This switching needs to be more complex for multiple traces. */
  AVER(TraceSetIsSingle(PoolArena(pool)->busyTraces));
  if (amc->rampMode == beginRamp && gen == amc->rampGen) {
@@ -1233,7 +1233,7 @@ static Res amcScanNailed(Bool *totalReturn, ScanState ss, Pool pool,
 /* AMCScan -- scan a single seg, turning it black
 *
- * See design.mps.poolamc.seg-scan.
+ * See <design/poolamc/#seg-scan>.
 */
 static Res AMCScan(Bool *totalReturn, ScanState ss, Pool pool, Seg seg)
 {
@@ -1261,7 +1261,7 @@ static Res AMCScan(Bool *totalReturn, ScanState ss, Pool pool, Seg seg)
  EVENT_PPP(AMCScanBegin, amc, seg, ss);
  base = AddrAdd(SegBase(seg), format->headerSize);
-  while(SegBuffer(seg) != NULL) {  /* design.mps.poolamc.seg-scan.loop */
+  while(SegBuffer(seg) != NULL) {  /* <design/poolamc/#seg-scan.loop> */
    limit = AddrAdd(BufferScanLimit(SegBuffer(seg)), format->headerSize);
    if (base >= limit) {
      /* @@@@ Are we sure we don't need scan the rest of the segment? */
@@ -1278,7 +1278,7 @@ static Res AMCScan(Bool *totalReturn, ScanState ss, Pool pool, Seg seg)
    base = limit;
  }
-  /* design.mps.poolamc.seg-scan.finish @@@@ base? */
+  /* <design/poolamc/#seg-scan.finish> @@@@ base? */
  limit = AddrAdd(SegLimit(seg), format->headerSize);
  AVER(SegBase(seg) <= base
       && base <= AddrAdd(SegLimit(seg), format->headerSize));
@@ -1338,7 +1338,7 @@ static void amcFixInPlace(Pool pool, Seg seg, ScanState ss, Ref *refIO)
 /* AMCFixEmergency -- fix a reference, without allocating
 *
- * See design.mps.poolamc.emergency.fix.
+ * See <design/poolamc/#emergency.fix>.
 */
 static Res AMCFixEmergency(Pool pool, ScanState ss, Seg seg, Ref *refIO)
 {
@@ -1371,7 +1371,7 @@ static Res AMCFixEmergency(Pool pool, ScanState ss, Seg seg, Ref *refIO)
    return ResOK;
  }
-fixInPlace: /* see design.mps.poolamc.Nailboard.emergency */
+fixInPlace: /* see <design/poolamc/>.Nailboard.emergency */
  amcFixInPlace(pool, seg, ss, refIO);
  return ResOK;
 }
@@ -1379,7 +1379,7 @@ fixInPlace: /* see design.mps.poolamc.Nailboard.emergency */
 /* AMCFix -- fix a reference to the pool
 *
- * See design.mps.poolamc.fix.
+ * See <design/poolamc/#fix>.
 */
 Res AMCFix(Pool pool, ScanState ss, Seg seg, Ref *refIO)
 {
@@ -1398,7 +1398,7 @@ Res AMCFix(Pool pool, ScanState ss, Seg seg, Ref *refIO)
  RefSet toSummary;     /* summary of object's destination */
  Seg toSeg;            /* segment to which object is being relocated */
-  /* design.mps.trace.fix.noaver */
+  /* <design/trace/#fix.noaver> */
  AVERT_CRITICAL(Pool, pool);
  AVERT_CRITICAL(ScanState, ss);
  AVERT_CRITICAL(Seg, seg);
@@ -1496,7 +1496,7 @@ Res AMCFix(Pool pool, ScanState ss, Seg seg, Ref *refIO)
      if (RefSetDiff(summary, toSummary) != RefSetEMPTY)
        SegSetSummary(toSeg, RefSetUnion(toSummary, summary));
-      /* design.mps.trace.fix.copy */
+      /* <design/trace/#fix.copy> */
      (void)AddrCopy(newRef, ref, length);
      ShieldCover(arena, toSeg);
@@ -1525,7 +1525,7 @@ returnRes:
 /* AMCHeaderFix -- fix a reference to the pool, with headers
 *
- * See design.mps.poolamc.header.fix.
+ * See <design/poolamc/#header.fix>.
 */
 static Res AMCHeaderFix(Pool pool, ScanState ss, Seg seg, Ref *refIO)
 {
@@ -1545,7 +1545,7 @@ static Res AMCHeaderFix(Pool pool, ScanState ss, Seg seg, Ref *refIO)
  RefSet toSummary;     /* summary of object's destination */
  Seg toSeg;            /* segment to which object is being relocated */
-  /* design.mps.trace.fix.noaver */
+  /* <design/trace/#fix.noaver> */
  AVERT_CRITICAL(Pool, pool);
  AVERT_CRITICAL(ScanState, ss);
  AVERT_CRITICAL(Seg, seg);
@@ -1645,7 +1645,7 @@ static Res AMCHeaderFix(Pool pool, ScanState ss, Seg seg, Ref *refIO)
      if (RefSetDiff(summary, toSummary) != RefSetEMPTY)
        SegSetSummary(toSeg, RefSetUnion(toSummary, summary));
-      /* design.mps.trace.fix.copy */
+      /* <design/trace/#fix.copy> */
      (void)AddrCopy(newBase, AddrSub(ref, headerSize), length);
      ShieldCover(arena, toSeg);
@@ -1701,7 +1701,7 @@ static void amcReclaimNailed(Pool pool, Trace trace, Seg seg)
    goto adjustColour;
  }
-  /* see design.mps.poolamc.Nailboard.limitations for improvements */
+  /* see <design/poolamc/>.Nailboard.limitations for improvements */
  headerSize = format->headerSize;
  ShieldExpose(arena, seg);
  p = AddrAdd(SegBase(seg), headerSize);
@@ -1745,7 +1745,7 @@ adjustColour:
 /* AMCReclaim -- recycle a segment if it is still white
 *
- * See design.mps.poolamc.reclaim.
+ * See <design/poolamc/#reclaim>.
 */
 static void AMCReclaim(Pool pool, Trace trace, Seg seg)
 {
@@ -1862,7 +1862,7 @@ static void amcWalkAll(Pool pool, FormattedObjectsStepMethod f,
 /* AMCDescribe -- describe the contents of the AMC pool
 *
- * See design.mps.poolamc.describe.
+ * See <design/poolamc/#describe>.
 */
 static Res AMCDescribe(Pool pool, mps_lib_FILE *stream)
 {
@@ -2015,7 +2015,7 @@ void mps_amc_apply(mps_pool_t mps_pool,
 /* AMCCheck -- check consistency of the AMC pool
 *
- * See design.mps.poolamc.check.
+ * See <design/poolamc/#check>.
 */
 static Bool AMCCheck(AMC amc)
 {
diff --git a/mps/code/poolams.c b/mps/code/poolams.c
index 4c2d0c33e31..480228c2b14 100644
--- a/mps/code/poolams.c
+++ b/mps/code/poolams.c
@@ -3,7 +3,7 @@
 * $Id$
 * Copyright (c) 2001 Ravenbrook Limited.  See end of file for license.
 *
- * .design: See design.mps.poolams.
+ * .design: See <design/poolams/>.
 *
 *
 * TRANSGRESSSIONS
@@ -41,7 +41,7 @@ Bool AMSSegCheck(AMSSeg amsseg)
  CHECKL(amsseg->grains >= amsseg->free + amsseg->newAlloc);
  if (SegWhite(seg) != TraceSetEMPTY)
-    /* design.mps.poolams.colour.single */
+    /* <design/poolams/#colour.single> */
    CHECKL(TraceSetIsSingle(SegWhite(seg)));
  CHECKL(BoolCheck(amsseg->marksChanged));
@@ -139,7 +139,7 @@ static Res AMSSegInit(Seg seg, Pool pool, Addr base, Size size,
  amsseg->grains = size >> ams->grainShift;
  amsseg->free = amsseg->grains;
  amsseg->newAlloc = (Count)0;
-  amsseg->marksChanged = FALSE; /* design.mps.poolams.marked.unused */
+  amsseg->marksChanged = FALSE; /* <design/poolams/#marked.unused> */
  amsseg->ambiguousFixes = FALSE;
  res = amsCreateTables(&amsseg->allocTable,
@@ -148,7 +148,7 @@ static Res AMSSegInit(Seg seg, Pool pool, Addr base, Size size,
  if (res != ResOK)
    goto failCreateTables;
-  /* start off using firstFree, see design.mps.poolams.no-bit */
+  /* start off using firstFree, see <design/poolams/#no-bit> */
  amsseg->allocTableInUse = FALSE;
  amsseg->firstFree = 0;
  amsseg->colourTablesInUse = FALSE;
@@ -209,15 +209,15 @@ static void AMSSegFinish(Seg seg)
 *
 * .empty: segment merging and splitting is limited to simple cases
 * where the high segment is empty.
- * See design.mps.poolams.split-merge.constrain.
+ * See <design/poolams/#split-merge.constrain>.
 *
 * .grain-align: segment merging and splitting is limited to cases
 * where the join is aligned with the grain alignment
- * See design.mps.poolams.split-merge.constrain.
+ * See <design/poolams/#split-merge.constrain>.
 *
 * .alloc-early: Allocations are performed before calling the
 * next method to simplify the fail cases. See
- * design.mps.seg.split-merge.fail
+ * <design/seg/#split-merge.fail>
 *
 * .table-names: The names of local variables holding the new
 * allocation and colour tables are chosen to have names which
@@ -383,10 +383,10 @@ static Res AMSSegSplit(Seg seg, Seg segHi,
  amsseg->free -= hiGrains;
  amssegHi->free = hiGrains;
  amssegHi->newAlloc = (Count)0;
-  amssegHi->marksChanged = FALSE; /* design.mps.poolams.marked.unused */
+  amssegHi->marksChanged = FALSE; /* <design/poolams/#marked.unused> */
  amssegHi->ambiguousFixes = FALSE;
-  /* start off using firstFree, see design.mps.poolams.no-bit */
+  /* start off using firstFree, see <design/poolams/#no-bit> */
  amssegHi->allocTableInUse = FALSE;
  amssegHi->firstFree = 0;
  /* use colour tables if the segment is white */
@@ -601,7 +601,7 @@ static Res AMSSegCreate(Seg *segReturn, Pool pool, Size size,
  }
  PoolGenUpdateZones(&ams->pgen, seg);
-  /* see design.mps.seg.field.rankset */
+  /* see <design/seg/#field.rankset> */
  if (rankSet != RankSetEMPTY) {
    SegSetRankAndSummary(seg, rankSet, RefSetUNIV);
  } else {
@@ -640,7 +640,7 @@ static Res AMSIterate(Seg seg, AMSObjectFunction f, void *closure);
 /* AMSInit -- the pool class initialization method
 *
 *  Takes one additional argument: the format of the objects
- *  allocated in the pool.  See design.mps.poolams.init.
+ *  allocated in the pool.  See <design/poolams/#init>.
 */
 static Res AMSInit(Pool pool, va_list args)
 {
@@ -777,7 +777,7 @@ static Bool amsSegAlloc(Index *baseReturn, Index *limitReturn,
 /* AMSBufferFill -- the pool class buffer fill method
 *
 * Iterates over the segments looking for space.  See
- * design.mps.poolams.fill.
+ * <design/poolams/#fill>.
 */
 Res AMSBufferFill(Addr *baseReturn, Addr *limitReturn,
                  Pool pool, Buffer buffer, Size size,
@@ -804,12 +804,12 @@ Res AMSBufferFill(Addr *baseReturn, Addr *limitReturn,
  AVER(BoolCheck(withReservoirPermit));
  /* Check that we're not in the grey mutator phase (see */
-  /* design.mps.poolams.fill.colour). */
+  /* <design/poolams/#fill.colour>). */
  AVER(PoolArena(pool)->busyTraces == PoolArena(pool)->flippedTraces);
  rankSet = BufferRankSet(buffer);
  ring = (ams->allocRing)(ams, rankSet, size);
-  /* design.mps.poolams.fill.slow */
+  /* <design/poolams/#fill.slow> */
  RING_FOR(node, ring, nextNode) {
    AMSSeg amsseg = RING_ELT(AMSSeg, segRing, node);
    AVERT_CRITICAL(AMSSeg, amsseg);
@@ -849,7 +849,7 @@ found:
 /* AMSBufferEmpty -- the pool class buffer empty method
 *
 * Frees the unused part of the buffer.  The colour of the area doesn't
- * need to be changed.  See design.mps.poolams.empty.
+ * need to be changed.  See <design/poolams/#empty>.
 */
 void AMSBufferEmpty(Pool pool, Buffer buffer, Addr init, Addr limit)
 {
@@ -954,13 +954,13 @@ Res AMSWhiten(Pool pool, Trace trace, Seg seg)
  amsseg = Seg2AMSSeg(seg);
  AVERT(AMSSeg, amsseg);
-  /* design.mps.poolams.colour.single */
+  /* <design/poolams/#colour.single> */
  AVER(SegWhite(seg) == TraceSetEMPTY);
  AVER(!amsseg->colourTablesInUse);
  amsseg->colourTablesInUse = TRUE;
  buffer = SegBuffer(seg);
-  if (buffer != NULL) { /* design.mps.poolams.condemn.buffer */
+  if (buffer != NULL) { /* <design/poolams/#condemn.buffer> */
    Index scanLimitIndex, limitIndex;
    scanLimitIndex = AMS_ADDR_INDEX(seg, BufferScanLimit(buffer));
    limitIndex = AMS_ADDR_INDEX(seg, BufferLimit(buffer));
@@ -980,7 +980,7 @@ Res AMSWhiten(Pool pool, Trace trace, Seg seg)
  /* The unused part of the buffer is new allocation by definition. */
  ams->pgen.newSize -= AMSGrainsSize(ams, amsseg->newAlloc - uncondemned);
  amsseg->newAlloc = uncondemned;
-  amsseg->marksChanged = FALSE; /* design.mps.poolams.marked.condemn */
+  amsseg->marksChanged = FALSE; /* <design/poolams/#marked.condemn> */
  amsseg->ambiguousFixes = FALSE;
  SegSetWhite(seg, TraceSetAdd(SegWhite(seg), trace));
@@ -1109,7 +1109,7 @@ static Res amsScanObject(Seg seg, Index i, Addr p, Addr next, void *clos)
 /* AMSScan -- the pool class segment scanning method
 *
- * See design.mps.poolams.scan
+ * See <design/poolams/#scan>
 */
 Res AMSScan(Bool *totalReturn, ScanState ss, Pool pool, Seg seg)
 {
@@ -1132,7 +1132,7 @@ Res AMSScan(Bool *totalReturn, ScanState ss, Pool pool, Seg seg)
  AVERT(AMSSeg, amsseg);
  /* Check that we're not in the grey mutator phase (see */
-  /* design.mps.poolams.not-req.grey). */
+  /* <design/poolams/#not-req.grey>). */
  AVER(TraceSetSub(ss->traces, arena->flippedTraces));
  closureStruct.scanAllObjects =
@@ -1153,13 +1153,13 @@ Res AMSScan(Bool *totalReturn, ScanState ss, Pool pool, Seg seg)
    format = pool->format;
    AVERT(Format, format);
    alignment = PoolAlignment(AMS2Pool(ams));
-    do { /* design.mps.poolams.scan.iter */
+    do { /* <design/poolams/#scan.iter> */
-      amsseg->marksChanged = FALSE; /* design.mps.poolams.marked.scan */
+      amsseg->marksChanged = FALSE; /* <design/poolams/#marked.scan> */
-      /* design.mps.poolams.ambiguous.middle */
+      /* <design/poolams/#ambiguous.middle> */
      if (amsseg->ambiguousFixes) {
        res = (ams->iterate)(seg, amsScanObject, &closureStruct);
        if (res != ResOK) {
-          /* design.mps.poolams.marked.scan.fail */
+          /* <design/poolams/#marked.scan.fail> */
          amsseg->marksChanged = TRUE;
          *totalReturn = FALSE;
          return res;
@@ -1180,7 +1180,7 @@ Res AMSScan(Bool *totalReturn, ScanState ss, Pool pool, Seg seg)
          j = AMS_ADDR_INDEX(seg, next);
          res = (*format->scan)(ss, clientP, clientNext);
          if (res != ResOK) {
-            /* design.mps.poolams.marked.scan.fail */
+            /* <design/poolams/#marked.scan.fail> */
            amsseg->marksChanged = TRUE;
            *totalReturn = FALSE;
            return res;
@@ -1224,7 +1224,7 @@ Res AMSFix(Pool pool, ScanState ss, Seg seg, Ref *refIO)
  AVER_CRITICAL(amsseg->colourTablesInUse);
  /* @@@@ We should check that we're not in the grey mutator phase */
-  /* (see design.mps.poolams.not-req.grey), but there's no way of */
+  /* (see <design/poolams/#not-req.grey>), but there's no way of */
  /* doing that here (this can be called from RootScan, during flip). */
  clientRef = *refIO;
@@ -1263,7 +1263,7 @@ Res AMSFix(Pool pool, ScanState ss, Seg seg, Ref *refIO)
      } else {
        ++ss->preservedInPlaceCount; /* Size updated on reclaim */
        if (SegRankSet(seg) == RankSetEMPTY && ss->rank != RankAMBIG) {
-          /* design.mps.poolams.fix.to-black */
+          /* <design/poolams/#fix.to-black> */
          Addr clientNext, next;
          ShieldExpose(PoolArena(pool), seg);
@@ -1276,7 +1276,7 @@ Res AMSFix(Pool pool, ScanState ss, Seg seg, Ref *refIO)
        } else { /* turn it grey */
          AMSWhiteGreyen(seg, i);
          SegSetGrey(seg, TraceSetUnion(SegGrey(seg), ss->traces));
-          /* mark it for scanning - design.mps.poolams.marked.fix */
+          /* mark it for scanning - <design/poolams/#marked.fix> */
          amsseg->marksChanged = TRUE;
        }
      }
diff --git a/mps/code/poolams.h b/mps/code/poolams.h
index 461150543ec..23482b6459b 100644
--- a/mps/code/poolams.h
+++ b/mps/code/poolams.h
@@ -59,7 +59,7 @@ typedef struct AMSStruct {
  AMSRingFunction allocRing;   /* fn to get the ring to allocate from */
  AMSSegsDestroyFunction segsDestroy;
  AMSSegClassFunction segClass;/* fn to get the class for segments */
-  Sig sig;                     /* design.mps.pool.outer-structure.sig */
+  Sig sig;                     /* <design/pool/#outer-structure.sig> */
 } AMSStruct;
@@ -73,7 +73,7 @@ typedef struct AMSSegStruct {
  Bool allocTableInUse;  /* whether we use allocTable */
  Index firstFree;       /* 1st free grain, if allocTable is not used */
  BT allocTable;         /* set if grain is allocated */
-  /* design.mps.poolams.colour.single */
+  /* <design/poolams/#colour.single> */
  Bool marksChanged;     /* has been marked since last scan */
  Bool ambiguousFixes;   /* has been ambiguously marked since last scan */
  Bool colourTablesInUse;/* whether we use the colour tables */
@@ -93,7 +93,7 @@ typedef struct AMSSegStruct {
 /* macros for abstracting index/address computations */
-/* design.mps.poolams.addr-index.slow */
+/* <design/poolams/#addr-index.slow> */
 /* only use when size is a multiple of the grain size */
 #define AMSGrains(ams, size) ((size) >> (ams)->grainShift)
diff --git a/mps/code/poolawl.c b/mps/code/poolawl.c
index b911f6fc0cc..9c8d062d083 100644
--- a/mps/code/poolawl.c
+++ b/mps/code/poolawl.c
@@ -6,7 +6,7 @@
 *
 * DESIGN
 *
- * .design: See design.mps.poolawl.  This is Dylan-specific pool.
+ * .design: See <design/poolawl/>.  This is Dylan-specific pool.
 *
 *
 * ASSUMPTIONS (about when to scan single references on accesses)
@@ -82,7 +82,7 @@ typedef Addr (*FindDependentMethod)(Addr object);
 /* AWLStruct -- AWL pool structure
 *
- * See design.mps.poolawl.poolstruct
+ * See <design/poolawl/#poolstruct>
 */
 typedef struct AWLStruct {
@@ -116,7 +116,7 @@ static Bool AWLCheck(AWL awl);
 #define AWLSegSig ((Sig)0x519A3759) /* SIGnature AWL SeG */
-/* design.mps.poolawl.seg */
+/* <design/poolawl/#seg> */
 typedef struct AWLSegStruct {
  GCSegStruct gcSegStruct;  /* superclass fields must come first */
  BT mark;
@@ -685,7 +685,7 @@ static Res AWLWhiten(Pool pool, Trace trace, Seg seg)
  buffer = SegBuffer(seg);
  /* can only whiten for a single trace, */
-  /* see design.mps.poolawl.fun.condemn */
+  /* see <design/poolawl/#fun.condemn> */
  AVER(SegWhite(seg) == TraceSetEMPTY);
  if (buffer == NULL) {
@@ -812,9 +812,9 @@ static Res awlScanObject(Arena arena, AWL awl, ScanState ss,
  dependentObject = awl->findDependent(base);
  dependent = SegOfAddr(&dependentSeg, arena, dependentObject);
  if (dependent) {
-      /* design.mps.poolawl.fun.scan.pass.object.dependent.expose */
+      /* <design/poolawl/#fun.scan.pass.object.dependent.expose> */
      ShieldExpose(arena, dependentSeg);
-      /* design.mps.poolawl.fun.scan.pass.object.dependent.summary */
+      /* <design/poolawl/#fun.scan.pass.object.dependent.summary> */
      SegSetSummary(dependentSeg, RefSetUNIV);
  }
@@ -873,7 +873,7 @@ static Res awlScanSinglePass(Bool *anyScannedReturn,
    Index i;        /* the index into the bit tables corresponding to p */
    Addr objectLimit;
-    /* design.mps.poolawl.fun.scan.pass.buffer */
+    /* <design/poolawl/#fun.scan.pass.buffer> */
    if (p == bufferScanLimit) {
      p = BufferLimit(buffer);
      continue;
@@ -886,7 +886,7 @@ static Res awlScanSinglePass(Bool *anyScannedReturn,
    }
    hp = AddrAdd(p, format->headerSize);
    objectLimit = (format->skip)(hp);
-    /* design.mps.poolawl.fun.scan.pass.object */
+    /* <design/poolawl/#fun.scan.pass.object> */
    if (scanAllObjects
        || (BTGet(awlseg->mark, i) && !BTGet(awlseg->scanned, i))) {
      Res res = awlScanObject(arena, awl, ss, pool->format,
diff --git a/mps/code/poollo.c b/mps/code/poollo.c
index 9edae934e20..6ef1df6ccf9 100644
--- a/mps/code/poollo.c
+++ b/mps/code/poollo.c
@@ -5,7 +5,7 @@
 *
 * DESIGN
 *
- * .design: See design.mps.poollo.  This is a leaf pool class.
+ * .design: See <design/poollo/>.  This is a leaf pool class.
 */
 #include "mpsclo.h"
diff --git a/mps/code/poolmrg.c b/mps/code/poolmrg.c
index 27ee414a5d9..17c40313af0 100644
--- a/mps/code/poolmrg.c
+++ b/mps/code/poolmrg.c
@@ -5,7 +5,7 @@
 *
 * DESIGN
 *
- * .design: See design.mps.poolmrg.
+ * .design: See <design/poolmrg/>.
 *
 * NOTES
 *
@@ -17,7 +17,7 @@
 *
 * TRANSGRESSIONS
 *
- * .addr.void-star: Breaks design.mps.type.addr.use all over the place,
+ * .addr.void-star: Breaks <design/type/#addr.use> all over the place,
 * accessing the segments acquired from SegAlloc with C pointers.  It
 * would not be practical to use ArenaPeek/Poke everywhere.  Blocks
 * acquired from ControlAlloc must be directly accessible from C, or else
@@ -110,10 +110,10 @@ static void MRGRefPartSetRef(Arena arena, RefPart refPart, Ref ref)
 typedef struct MRGStruct {
  PoolStruct poolStruct;    /* generic pool structure */
-  RingStruct entryRing;     /* design.mps.poolmrg.poolstruct.entry */
+  RingStruct entryRing;     /* <design/poolmrg/#poolstruct.entry> */
-  RingStruct freeRing;      /* design.mps.poolmrg.poolstruct.free */
+  RingStruct freeRing;      /* <design/poolmrg/#poolstruct.free> */
-  RingStruct refRing;       /* design.mps.poolmrg.poolstruct.refring */
+  RingStruct refRing;       /* <design/poolmrg/#poolstruct.refring> */
-  Size extendBy;            /* design.mps.poolmrg.extend */
+  Size extendBy;            /* <design/poolmrg/#extend> */
  Sig sig;                  /* impl.h.mps.sig */
 } MRGStruct;
@@ -144,14 +144,14 @@ typedef struct MRGRefSegStruct *MRGRefSeg;
 typedef struct MRGLinkSegStruct {
  SegStruct segStruct;      /* superclass fields must come first */
-  MRGRefSeg refSeg;         /* design.mps.poolmrg.mrgseg.link.refseg */
+  MRGRefSeg refSeg;         /* <design/poolmrg/#mrgseg.link.refseg> */
  Sig sig;                  /* impl.h.misc.sig */
 } MRGLinkSegStruct;
 typedef struct MRGRefSegStruct {
  GCSegStruct gcSegStruct;  /* superclass fields must come first */
-  RingStruct mrgRing;       /* design.mps.poolmrg.mrgseg.ref.segring */
+  RingStruct mrgRing;       /* <design/poolmrg/#mrgseg.ref.segring> */
-  MRGLinkSeg linkSeg;       /* design.mps.poolmrg.mrgseg.ref.linkseg */
+  MRGLinkSeg linkSeg;       /* <design/poolmrg/#mrgseg.ref.linkseg> */
  Sig sig;                  /* impl.h.misc.sig */
 } MRGRefSegStruct;
@@ -174,7 +174,7 @@ static SegClass MRGRefSegClassGet(void);
 *
 * .link.nullref: During initialization of a link segment the refSeg
 * field will be NULL. This will be initialized when the reference
- * segment is initialized.  See design.mps.poolmrg.mrgseg.link.refseg.
+ * segment is initialized.  See <design/poolmrg/#mrgseg.link.refseg>.
 */
 static Bool MRGLinkSegCheck(MRGLinkSeg linkseg)
 {
@@ -268,7 +268,7 @@ static Res MRGRefSegInit(Seg seg, Pool pool, Addr base, Size size,
  if (res != ResOK)
    return res;
-  /* design.mps.seg.field.rankset.start, .improve.rank */
+  /* <design/seg/#field.rankset.start>, .improve.rank */
  SegSetRankSet(seg, RankSetSingle(RankFINAL));
  RingInit(&refseg->mrgRing);
@@ -321,7 +321,7 @@ static Count MRGGuardiansPerSeg(MRG mrg)
 }
-/* design.mps.poolmrg.guardian.assoc */
+/* <design/poolmrg/#guardian.assoc> */
 #define refPartOfIndex(refseg, index) \
  ((RefPart)SegBase(RefSeg2Seg(refseg)) + (index))
@@ -387,7 +387,7 @@ static void MRGGuardianInit(MRG mrg, Link link, RefPart refPart)
  RingInit(&link->the.linkRing);
  link->state = MRGGuardianFREE;
  RingAppend(&mrg->freeRing, &link->the.linkRing);
-  /* design.mps.poolmrg.free.overwrite */
+  /* <design/poolmrg/#free.overwrite> */
  MRGRefPartSetRef(PoolArena(&mrg->poolStruct), refPart, 0);
 }
@@ -465,7 +465,7 @@ static MessageClassStruct MRGMessageClassStruct = {
  MessageNoGCLiveSize,         /* GCLiveSize */   
  MessageNoGCCondemnedSize,    /* GCCondemnedSize */
  MessageNoGCNotCondemnedSize, /* GCNoteCondemnedSize */
-  MessageClassSig              /* design.mps.message.class.sig.double */
+  MessageClassSig              /* <design/message/#class.sig.double> */
 };
@@ -682,7 +682,7 @@ static void MRGFinish(Pool pool)
  mrg->sig = SigInvalid;
  RingFinish(&mrg->refRing);
-  /* design.mps.poolmrg.trans.no-finish */
+  /* <design/poolmrg/#trans.no-finish> */
 }
@@ -705,7 +705,7 @@ Res MRGRegister(Pool pool, Ref ref)
  arena = PoolArena(pool);
  AVERT(Arena, arena);
-  /* design.mps.poolmrg.alloc.grow */
+  /* <design/poolmrg/#alloc.grow> */
  if (RingIsSingle(&mrg->freeRing)) {
    /* .refseg.useless: refseg isn't used */
    /* @@@@ Should the client be able to use the reservoir for this? */
@@ -718,12 +718,12 @@ Res MRGRegister(Pool pool, Ref ref)
  link = linkOfRing(freeNode);
  AVER(link->state == MRGGuardianFREE);
-  /* design.mps.poolmrg.alloc.pop */
+  /* <design/poolmrg/#alloc.pop> */
  RingRemove(freeNode);
  link->state = MRGGuardianPREFINAL;
  RingAppend(&mrg->entryRing, freeNode);
-  /* design.mps.poolmrg.guardian.ref.alloc */
+  /* <design/poolmrg/#guardian.ref.alloc> */
  refPart = MRGRefPartOfLink(link, arena);
  MRGRefPartSetRef(arena, refPart, ref);
@@ -752,7 +752,7 @@ static void MRGFree(Pool pool, Addr old, Size size)
  arena = PoolArena(pool);
  AVERT(Arena, arena);
-  /* design.mps.poolmrg.guardian.ref.free */
+  /* <design/poolmrg/#guardian.ref.free> */
  link = MRGLinkOfRefPart(refPart, arena);
  AVER(link->state == MRGGuardianPOSTFINAL);
diff --git a/mps/code/poolmv.c b/mps/code/poolmv.c
index 90de155bb12..8a02ce76f5d 100644
--- a/mps/code/poolmv.c
+++ b/mps/code/poolmv.c
@@ -113,7 +113,7 @@ static Bool MVBlockCheck(MVBlock block)
 typedef struct MVSpanStruct *MVSpan;
 typedef struct MVSpanStruct {
-  Sig sig;                      /* design.mps.sig */
+  Sig sig;                      /* <design/sig/> */
  RingStruct spans;             /* all the spans */
  MV mv;                        /* owning MV pool */
  Tract tract;                  /* first tract of the span */
diff --git a/mps/code/poolmv2.c b/mps/code/poolmv2.c
index e9e484c739c..9572504bab0 100644
--- a/mps/code/poolmv2.c
+++ b/mps/code/poolmv2.c
@@ -6,7 +6,7 @@
 * .purpose: A manual-variable pool designed to take advantage of
 * placement according to predicted deathtime.
 *
- * .design: See design.mps.poolmv2.
+ * .design: See <design/poolmvt/>.
 */
 #include "mpm.h"
@@ -63,20 +63,20 @@ typedef struct MVTStruct
  CBSStruct cbsStruct;          /* The coalescing block structure */
  ABQStruct abqStruct;          /* The available block queue */
  SegPrefStruct segPrefStruct;  /* The preferences for segments */
-  /* design.mps.poolmvt:arch.parameters */
+  /* <design/poolmvt/#arch.parameters> */
  Size minSize;                 /* Pool parameter */
  Size meanSize;                /* Pool parameter */
  Size maxSize;                 /* Pool parameter */
  Count fragLimit;              /* Pool parameter */
-  /* design.mps.poolmvt:arch.overview.abq.reuse.size */
+  /* <design/poolmvt/#arch.overview.abq.reuse.size> */
  Size reuseSize;               /* Size at which blocks are recycled */
-  /* design.mps.poolmvt:arch.ap.fill.size */
+  /* <design/poolmvt/#arch.ap.fill.size> */
  Size fillSize;                /* Size of pool segments */
-  /* design.mps.poolmvt:arch.contingency */
+  /* <design/poolmvt/#arch.contingency> */
  Size availLimit;              /* Limit on available */
-  /* design.mps.poolmvt:impl.c.free.merge.segment.overflow */
+  /* <design/poolmvt/#impl.c.free.merge.segment.overflow> */
  Bool abqOverflow;             /* ABQ dropped some candidates */
-  /* design.mps.poolmvt:arch.ap.no-fit.* */
+  /* <design/poolmvt/#arch.ap.no-fit>.* */
  Bool splinter;                /* Saved splinter */
  Seg splinterSeg;              /* Saved splinter seg */
  Addr splinterBase;            /* Saved splinter base */
@@ -227,9 +227,9 @@ static Res MVTInit(Pool pool, va_list arg)
  unless (fragLimit <= 100)
    return ResLIMIT;
-  /* see design.mps.poolmvt:arch.parameters */
+  /* see <design/poolmvt/#arch.parameters> */
  fillSize = SizeAlignUp(maxSize, ArenaAlign(arena));
-  /* see design.mps.poolmvt:arch.fragmentation.internal */
+  /* see <design/poolmvt/#arch.fragmentation.internal> */
  reuseSize = 2 * fillSize;
  abqDepth = (reserveDepth * meanSize + reuseSize - 1) / reuseSize;
  /* keep the abq from being useless */
@@ -393,7 +393,7 @@ static void MVTFinish(Pool pool)
 /* MVTBufferFill -- refill an allocation buffer from an MVT pool
 *
- * See design.mps.poolmvt:impl.c.ap.fill
+ * See <design/poolmvt/#impl.c.ap.fill>
 */
 static Res MVTBufferFill(Addr *baseReturn, Addr *limitReturn,
                         Pool pool, Buffer buffer, Size minSize,
@@ -422,7 +422,7 @@ static Res MVTBufferFill(Addr *baseReturn, Addr *limitReturn,
  fillSize = mvt->fillSize;
  alignedSize = SizeAlignUp(minSize, ArenaAlign(arena));
-  /* design.mps.poolmvt:arch.ap.no-fit.oversize */
+  /* <design/poolmvt/#arch.ap.no-fit.oversize> */
  /* Allocate oversize blocks exactly, directly from the arena */
  if (minSize > fillSize) {
    res = MVTSegAlloc(&seg, mvt, alignedSize, pool, withReservoirPermit);
@@ -445,7 +445,7 @@ static Res MVTBufferFill(Addr *baseReturn, Addr *limitReturn,
    return res;
  }
-  /* design.mps.poolmvt:arch.ap.no-fit.return */
+  /* <design/poolmvt/#arch.ap.no-fit.return> */
  /* Use any splinter, if available */
  if (mvt->splinter) {
    base = mvt->splinterBase;
@@ -463,7 +463,7 @@ static Res MVTBufferFill(Addr *baseReturn, Addr *limitReturn,
  res = ABQPeek(MVTABQ(mvt), &block);
  if (res != ResOK) {
    METER_ACC(mvt->underflows, minSize);
-    /* design.mps.poolmvt:arch.contingency.fragmentation-limit */
+    /* <design/poolmvt/#arch.contingency.fragmentation-limit> */
    if (mvt->available >=  mvt->availLimit) {
      METER_ACC(mvt->fragLimitContingencies, minSize);
      res = MVTContingencySearch(&block, MVTCBS(mvt), minSize);
@@ -514,7 +514,7 @@ found:
  }
 
  /* Attempt to request a block from the arena */
-  /* see design.mps.poolmvt:impl.c.free.merge.segment */
+  /* see <design/poolmvt/#impl.c.free.merge.segment> */
  res = MVTSegAlloc(&seg, mvt, fillSize, pool, withReservoirPermit);
  if (res == ResOK) {
    base = SegBase(seg);
@@ -553,7 +553,7 @@ done:
 /* MVTBufferEmpty -- return an unusable portion of a buffer to the MVT
 * pool
 *
- * See design.mps.poolmvt:impl.c.ap.empty
+ * See <design/poolmvt/#impl.c.ap.empty>
 */
 static void MVTBufferEmpty(Pool pool, Buffer buffer,
                           Addr base, Addr limit)
@@ -584,7 +584,7 @@ static void MVTBufferEmpty(Pool pool, Buffer buffer,
  METER_ACC(mvt->poolSize, mvt->size);
  METER_ACC(mvt->bufferEmpties, size);
-  /* design.mps.poolmvt:arch.ap.no-fit.splinter */
+  /* <design/poolmvt/#arch.ap.no-fit.splinter> */
  if (size < mvt->minSize) {
    res = CBSInsert(MVTCBS(mvt), base, limit);
    AVER(res == ResOK);
@@ -593,7 +593,7 @@ static void MVTBufferEmpty(Pool pool, Buffer buffer,
  }
  METER_ACC(mvt->splinters, size);
-  /* design.mps.poolmvt:arch.ap.no-fit.return */
+  /* <design/poolmvt/#arch.ap.no-fit.return> */
  if (mvt->splinter) {
    Size oldSize = AddrOffset(mvt->splinterBase, mvt->splinterLimit);
@@ -648,7 +648,7 @@ static void MVTFree(Pool pool, Addr base, Size size)
  METER_ACC(mvt->poolAllocated, mvt->allocated);
  METER_ACC(mvt->poolSize, mvt->size);
 
-  /* design.mps.poolmvt:arch.ap.no-fit.oversize.policy */
+  /* <design/poolmvt/#arch.ap.no-fit.oversize.policy> */
  /* Return exceptional blocks directly to arena */
  if (size > mvt->fillSize) {
    Seg seg;
@@ -862,7 +862,7 @@ static Res MVTSegAlloc(Seg *segReturn, MVT mvt, Size size,
  if (res == ResOK) {
    Size segSize = SegSize(*segReturn);
   
-    /* see design.mps.poolmvt:arch.fragmentation.internal */
+    /* see <design/poolmvt/#arch.fragmentation.internal> */
    AVER(segSize >= mvt->fillSize);
    mvt->size += segSize;
    mvt->available += segSize;
@@ -943,7 +943,7 @@ static void MVTNoteNew(CBS cbs, CBSBlock block, Size oldSize, Size newSize)
  UNUSED(newSize);
  res = ABQPush(MVTABQ(mvt), block);
-  /* See design.mps.poolmvt:impl.c.free.merge */
+  /* See <design/poolmvt/#impl.c.free.merge> */
  if (res != ResOK) {
    Arena arena = PoolArena(MVT2Pool(mvt));
    CBSBlock oldBlock;
diff --git a/mps/code/poolmv2.h b/mps/code/poolmv2.h
index a1d7a8d1e13..e62fe9a3a0d 100644
--- a/mps/code/poolmv2.h
+++ b/mps/code/poolmv2.h
@@ -5,7 +5,7 @@
 *
 * .purpose: The implementation of the new manual-variable pool class
 *
- * .design: See design.mps.poolmv2
+ * .design: See <design/poolmvt/>
 */
 #ifndef poolmv2_h
diff --git a/mps/code/poolmvff.c b/mps/code/poolmvff.c
index 820c4bfe1da..f3219dd9b0b 100644
--- a/mps/code/poolmvff.c
+++ b/mps/code/poolmvff.c
@@ -8,7 +8,7 @@
 * policy.  Provision is made to allocate in reverse.  This pool
 * can allocate across segment boundaries.
 *
- * .design: design.mps.poolmvff
+ * .design: <design/poolmvff/>
 *
 *
 * TRANSGRESSIONS
@@ -32,7 +32,7 @@ extern PoolClass PoolClassMVFF(void);
 /* MVFFStruct -- MVFF (Manual Variable First Fit) pool outer structure
 *
 * The signature is placed at the end, see
- * design.mps.pool.outer-structure.sig
+ * <design/pool/#outer-structure.sig>
 */
 #define MVFFSig           ((Sig)0x5193FFF9) /* SIGnature MVFF */
@@ -49,7 +49,7 @@ typedef struct MVFFStruct {     /* MVFF pool outer structure */
  CBSStruct cbsStruct;          /* free list */
  Bool firstFit;                /* as opposed to last fit */
  Bool slotHigh;                /* prefers high part of large block */
-  Sig sig;                      /* design.mps.sig */
+  Sig sig;                      /* <design/sig/> */
 } MVFFStruct;
@@ -188,7 +188,7 @@ static Res MVFFAddSeg(Seg *segReturn,
  AVER(SizeIsAligned(size, PoolAlignment(pool)));
  /* Use extendBy unless it's too small (see */
-  /* design.mps.poolmvff.design.seg-size). */
+  /* <design/poolmvff/#design.seg-size>). */
  if (size <= mvff->extendBy)
    segSize = mvff->extendBy;
  else
@@ -200,7 +200,7 @@ static Res MVFFAddSeg(Seg *segReturn,
                 withReservoirPermit);
  if (res != ResOK) {
    /* try again for a seg just large enough for object */
-    /* see design.mps.poolmvff.design.seg-fail */
+    /* see <design/poolmvff/#design.seg-fail> */
    segSize = SizeAlignUp(size, align);
    res = SegAlloc(&seg, SegClassGet(), mvff->segPref, segSize, pool,
                   withReservoirPermit);
@@ -420,7 +420,7 @@ static Res MVFFInit(Pool pool, va_list arg)
  AVERT(Pool, pool);
  /* .arg: class-specific additional arguments; see */
-  /* design.mps.poolmvff.method.init */
+  /* <design/poolmvff/#method.init> */
  /* .arg.check: we do the same checks here and in MVFFCheck */
  /* except for arenaHigh, which is stored only in the segPref. */
  extendBy = va_arg(arg, Size);
@@ -604,7 +604,7 @@ mps_class_t mps_class_mvff_debug(void)
 }
-/* Total free bytes. See design.mps.poolmvff.design.arena-enter */
+/* Total free bytes. See <design/poolmvff/#design.arena-enter> */
 size_t mps_mvff_free_size(mps_pool_t mps_pool)
 {
@@ -619,7 +619,7 @@ size_t mps_mvff_free_size(mps_pool_t mps_pool)
  return (size_t)mvff->free;
 }
-/* Total owned bytes. See design.mps.poolmvff.design.arena-enter */
+/* Total owned bytes. See <design/poolmvff/#design.arena-enter> */
 size_t mps_mvff_size(mps_pool_t mps_pool)
 {
diff --git a/mps/code/pooln.h b/mps/code/pooln.h
index 57c09b13152..e0cc5490854 100644
--- a/mps/code/pooln.h
+++ b/mps/code/pooln.h
@@ -31,7 +31,7 @@ extern PoolClass PoolClassN(void);
 /* PoolNCheck -- check a pool of class N
 *
 * Validates a PoolN object.  This function conforms to the validation
- * protocol defined in design.mps.check.
+ * protocol defined in <design/check/>.
 */
 extern Bool PoolNCheck(PoolN poolN);
diff --git a/mps/code/poolsnc.c b/mps/code/poolsnc.c
index 5d3227abe28..0198391ebb7 100644
--- a/mps/code/poolsnc.c
+++ b/mps/code/poolsnc.c
@@ -12,7 +12,7 @@
 * .lw-frame-state: The pool uses lightweight frames as its only
 * type of allocation frame. The lightweight frame state is set to
 * Valid whenever a buffer has a segment and Disabled otherwise.
- * See design.mps.alloc-frame.lw-frame.states.
+ * See <design/alloc-frame/#lw-frame.states>.
 *
 * .lw-frame-null: The frame marker NULL is used as a special value
 * to indicate bottom of stack.
@@ -75,7 +75,7 @@ typedef struct SNCBufStruct *SNCBuf;
 typedef struct SNCBufStruct {
  SegBufStruct segBufStruct;      /* superclass fields must come first */
  Seg topseg;                     /* The segment chain head -- may be NULL */
-  Sig sig;                        /* design.mps.sig */
+  Sig sig;                        /* <design/sig/> */
 } SNCBufStruct;
@@ -443,7 +443,7 @@ static Res SNCBufferFill(Addr *baseReturn, Addr *limitReturn,
    return res;
 found:
-  /* design.mps.seg.field.rankSet.start */
+  /* <design/seg/#field.rankSet.start> */
  if (BufferRankSet(buffer) == RankSetEMPTY)
    SegSetRankAndSummary(seg, BufferRankSet(buffer), RefSetEMPTY);
  else
diff --git a/mps/code/prmcan.c b/mps/code/prmcan.c
index 9c36baf90d8..86aaa37ee50 100644
--- a/mps/code/prmcan.c
+++ b/mps/code/prmcan.c
@@ -3,7 +3,7 @@
 * $Id$
 * Copyright (c) 2001 Ravenbrook Limited.  See end of file for license.
 *
- * .design: See design.mps.prot for the generic design of the interface
+ * .design: See <design/prot/> for the generic design of the interface
 * which is implemented in this module including the contracts for the
 * functions.
 *
diff --git a/mps/code/protan.c b/mps/code/protan.c
index e6d113a4849..ff02074fe3f 100644
--- a/mps/code/protan.c
+++ b/mps/code/protan.c
@@ -6,7 +6,7 @@
 *
 * DESIGN
 *
- * design.mps.protan
+ * <design/protan/>
 */
 #include "mpm.h"
@@ -36,7 +36,7 @@ void ProtSet(Addr base, Addr limit, AccessSet pm)
 /* ProtSync -- synchronize protection settings with hardware
 *
- * See design.mps.protan.fun.sync.
+ * See <design/protan/#fun.sync>.
 */
 void ProtSync(Arena arena)
@@ -53,7 +53,7 @@ void ProtSync(Arena arena)
      Addr base;
      do {
        base = SegBase(seg);
-        if (SegPM(seg) != AccessSetEMPTY) { /* design.mps.protan.fun.sync.seg */
+        if (SegPM(seg) != AccessSetEMPTY) { /* <design/protan/#fun.sync.seg> */
          ShieldEnter(arena);
          TraceSegAccess(arena, seg, SegPM(seg));
          ShieldLeave(arena);
diff --git a/mps/code/proti3.c b/mps/code/proti3.c
index caea8be71a7..72598f170ba 100644
--- a/mps/code/proti3.c
+++ b/mps/code/proti3.c
@@ -3,7 +3,7 @@
 * $Id$
 * Copyright (c) 2001 Ravenbrook Limited.  See end of file for license.
 *
- * .design: See design.mps.prot for the generic design of the interface
+ * .design: See <design/prot/> for the generic design of the interface
 * which is implemented in this module, including the contracts for the
 * functions.
 *
diff --git a/mps/code/protocol.c b/mps/code/protocol.c
index 4db59cbf9e0..9d8f6cff6d6 100644
--- a/mps/code/protocol.c
+++ b/mps/code/protocol.c
@@ -5,7 +5,7 @@
 *
 * DESIGN
 *
- * .design: See design.mps.protocol
+ * .design: See <design/protocol/>
 */
 #include "mpm.h"
diff --git a/mps/code/protocol.h b/mps/code/protocol.h
index a36b1055a8e..22fa6f21df7 100644
--- a/mps/code/protocol.h
+++ b/mps/code/protocol.h
@@ -25,7 +25,7 @@
 /* Macro to set the superclass field. This is not intended */
 /* to be used outside this file. This is a polymorphic macro */
-/* named as a function. See design.mps.protocol.introspect.c-lang */
+/* named as a function. See <design/protocol/#introspect.c-lang> */
 #define ProtocolClassSetSuperclassPoly(class, super) \
  (((ProtocolClass)(class))->superclass) = (ProtocolClass)(super)
@@ -120,7 +120,7 @@ typedef Bool (*ProtocolCoerceClassMethod)(ProtocolClass *coerceResult,
 typedef struct ProtocolClassStruct {
-  Sig sig;                               /* design.mps.sig */
+  Sig sig;                               /* <design/sig/> */
  ProtocolClass superclass;              /* the superclass */
  ProtocolCoerceInstMethod coerceInst;   /* coerce instance to super */
  ProtocolCoerceClassMethod coerceClass; /* coerce class to superclass */
@@ -128,7 +128,7 @@ typedef struct ProtocolClassStruct {
 typedef struct ProtocolInstStruct {
-  Sig sig;                      /* design.mps.sig */
+  Sig sig;                      /* <design/sig/> */
  ProtocolClass class;          /* the class  */
 } ProtocolInstStruct;
@@ -159,7 +159,7 @@ extern Bool ProtocolIsSubclass(ProtocolClass sub, ProtocolClass super);
 /* The following are macros because of the need to cast */
 /* subtypes of ProtocolClass. Nevertheless they are named */
-/* as functions. See design.mps.protocol.introspect.c-lang */
+/* as functions. See <design/protocol/#introspect.c-lang> */
 #define ProtocolClassSuperclassPoly(class) \
@@ -175,7 +175,7 @@ extern Bool ProtocolIsSubclass(ProtocolClass sub, ProtocolClass super);
 *
 * Returns the superclass, with type ProtocolClass. Clients will
 * probably wish to cast this. See
- * design.mps.protocol.int.static-superclass
+ * <design/protocol/#int.static-superclass>
 */
 #define SUPERCLASS(className)  \
  ProtocolClassSuperclassPoly(DERIVE_ENSURE(className)())
diff --git a/mps/code/protsu.c b/mps/code/protsu.c
index e28f0b1d873..0b02c05b5a2 100644
--- a/mps/code/protsu.c
+++ b/mps/code/protsu.c
@@ -5,8 +5,8 @@
 *
 * DESIGN
 *
- * see design.mps.prot for the generic design (including the interface),
+ * see <design/prot/> for the generic design (including the interface),
- * and design.mps.protsu for the design specific to this implementation.
+ * and <design/protsu/> for the design specific to this implementation.
 *
 * TRANSGRESSIONS
 *
@@ -153,7 +153,7 @@ void ProtSetup(void)
 {
  handler_t next;
-  /* ProtSetup is called exactly once, see design.mps.prot.if.setup */
+  /* ProtSetup is called exactly once, see <design/prot/#if.setup> */
  AVER(sigNext == NULL);
  next = signal(SIGSEGV, sigHandle);
@@ -206,7 +206,7 @@ void ProtSet(Addr base, Addr limit, AccessSet mode)
  /* 2nd arg to mprotect, .assume.size */
  if(mprotect((caddr_t)base, (int)AddrOffset(base, limit), flags) != 0) {
-    /* design.mps.protsu.fun.set.assume.mprotect */
+    /* <design/protsu/#fun.set.assume.mprotect> */
    NOTREACHED;
  }
 }
diff --git a/mps/code/pthrdext.c b/mps/code/pthrdext.c
index 5d19a744977..1aa4be26222 100644
--- a/mps/code/pthrdext.c
+++ b/mps/code/pthrdext.c
@@ -5,7 +5,7 @@
 *
 * .purpose: Provides extension to Pthreads.
 *
- * .design: see design.mps.pthreadext
+ * .design: see <design/pthreadext/>
 *
 * .acknowledgements: This was derived from code posted to
 * comp.programming.threads by Dave Butenhof and Raymond Lau
@@ -36,7 +36,7 @@ SRCID(pthreadext, "$Id$");
 /* PTHREADEXT_SIGSUSPEND, PTHREADEXT_SIGRESUME -- signals used
 *
- * See design.mps.pthreadext.impl.signals
+ * See <design/pthreadext/#impl.signals>
 */
 #define PTHREADEXT_SIGSUSPEND SIGXFSZ
@@ -44,7 +44,7 @@ SRCID(pthreadext, "$Id$");
 /* Static data initiatialized on first use of the module
- * See design.mps.pthreadext.impl.static.*
+ * See <design/pthreadext/#impl.static>.*
 */
 /* mutex */
@@ -59,7 +59,7 @@ static Bool pthreadextModuleInitialized = FALSE;
 /* Global variables protected by the mutex
- * See design.mps.pthreadext.impl.global.*
+ * See <design/pthreadext/#impl.global>.*
 */
 static PThreadext suspendingVictim = NULL;  /* current victim */
@@ -68,7 +68,7 @@ static RingStruct suspendedRing;            /* PThreadext suspend ring */
 /* suspendSignalHandler -- signal handler called when suspending a thread
 *
- * See design.mps.pthreadext.impl.suspend-handler
+ * See <design/pthreadext/#impl.suspend-handler>
 *
 * The interface for determining the MFC might be platform specific.
 *
@@ -140,7 +140,7 @@ static void suspendSignalHandler(int sig,
 /* resumeSignalHandler -- signal handler called when resuming a thread
 *
- * See design.mps.pthreadext.impl.suspend-handler
+ * See <design/pthreadext/#impl.suspend-handler>
 */
 static void resumeSignalHandler(int sig)
@@ -152,7 +152,7 @@ static void resumeSignalHandler(int sig)
 /* PThreadextModuleInit -- Initialize the PThreadext module
 *
- * See design.mps.pthreadext.impl.static.init
+ * See <design/pthreadext/#impl.static.init>
 *
 * Dynamically initialize all state when first used
 * (called by pthread_once).
@@ -263,7 +263,7 @@ extern void PThreadextInit(PThreadext pthreadext, pthread_t id)
 /* PThreadextFinish -- Finish a pthreadext
 *
- * See design.mps.pthreadext.impl.finish
+ * See <design/pthreadext/#impl.finish>
 */
 extern void PThreadextFinish(PThreadext pthreadext)
@@ -297,7 +297,7 @@ extern void PThreadextFinish(PThreadext pthreadext)
 /* PThreadextSuspend -- suspend a thread
 *
- * See design.mps.pthreadext.impl.suspend
+ * See <design/pthreadext/#impl.suspend>
 */
 Res PThreadextSuspend(PThreadext target, MutatorFaultContext *contextReturn)
@@ -359,7 +359,7 @@ unlock:
 /* PThreadextResume -- resume a suspended thread
 *
- * See design.mps.pthreadext.impl.resume
+ * See <design/pthreadext/#impl.resume>
 */
 Res PThreadextResume(PThreadext target)
diff --git a/mps/code/pthrdext.h b/mps/code/pthrdext.h
index c56fde4a08c..70a77a90e07 100644
--- a/mps/code/pthrdext.h
+++ b/mps/code/pthrdext.h
@@ -30,7 +30,7 @@ typedef struct PThreadextStruct *PThreadext;
 */
 typedef struct PThreadextStruct {
-  Sig sig;                         /* design.mps.sig */
+  Sig sig;                         /* <design/sig/> */
  pthread_t id;                    /* Thread ID */
  MutatorFaultContext suspendedMFC; /* context if suspended */
  RingStruct threadRing;           /* ring of suspended threads */
diff --git a/mps/code/reserv.c b/mps/code/reserv.c
index e7864e9ca58..f2888a6db8c 100644
--- a/mps/code/reserv.c
+++ b/mps/code/reserv.c
@@ -14,7 +14,7 @@
 SRCID(reserv, "$Id$");
-/* The reservoir pool is defined here. See design.mps.reservoir */
+/* The reservoir pool is defined here. See <design/reservoir/> */
 #define Pool2Reservoir(pool) PARENT(ReservoirStruct, poolStruct, pool)
@@ -129,7 +129,7 @@ static Bool reservoirIsConsistent(Reservoir reservoir)
  if (size != reservoir->reservoirSize)
    return FALSE;
-  /* design.mps.reservoir.align */
+  /* <design/reservoir/#align> */
  return SizeIsAligned(reservoir->reservoirLimit, alignment)
         && SizeIsAligned(reservoir->reservoirSize, alignment)
         && (reservoir->reservoirLimit >= reservoir->reservoirSize);
@@ -332,12 +332,12 @@ void ReservoirSetLimit(Reservoir reservoir, Size size)
  if (size > 0) {
    Size wastage;
-    /* design.mps.reservoir.wastage */
+    /* <design/reservoir/#wastage> */
    wastage = ArenaAlign(arena) * mutatorBufferCount(ArenaGlobals(arena));
-    /* design.mps.reservoir.align */
+    /* <design/reservoir/#align> */
    needed = SizeAlignUp(size, ArenaAlign(arena)) + wastage;
  } else {
-    needed = 0; /* design.mps.reservoir.really-empty */
+    needed = 0; /* <design/reservoir/#really-empty> */
  }
  AVER(SizeIsAligned(needed, ArenaAlign(arena)));
@@ -388,7 +388,7 @@ Res ReservoirInit(Reservoir reservoir, Arena arena)
  reservoir->reservoirSize = (Size)0;
  reservoir->reserve = NULL;
  reservoir->sig = ReservoirSig;
-  /* initialize the reservoir pool, design.mps.reservoir */
+  /* initialize the reservoir pool, <design/reservoir/> */
  res = PoolInit(&reservoir->poolStruct,
                 arena, EnsureReservoirPoolClass());
  if (res == ResOK) {
diff --git a/mps/code/ring.c b/mps/code/ring.c
index 4e2e08099dd..971384f6970 100644
--- a/mps/code/ring.c
+++ b/mps/code/ring.c
@@ -8,7 +8,7 @@
 * .purpose: Rings are used to manage potentially unbounded collections
 * of things.
 *
- * .sources: design.mps.ring,
+ * .sources: <design/ring/>,
 *   item 6 of mail.richard_brooksby.1996-03-25.16-02
 */
@@ -24,7 +24,7 @@ SRCID(ring, "$Id$");
 *
 * RingCheck performs a consistency check on the ring node.
 * RingCheckSingle performs the same check, but also checks that
- * the ring node is a singleton (design.mps.ring.def.singleton).
+ * the ring node is a singleton (<design/ring/#def.singleton>).
 */
 Bool RingCheck(Ring ring)
diff --git a/mps/code/ring.h b/mps/code/ring.h
index ae0f6229241..84cfb74c909 100644
--- a/mps/code/ring.h
+++ b/mps/code/ring.h
@@ -94,11 +94,11 @@ extern void (RingRemove)(Ring old);
 extern Ring (RingNext)(Ring ring);
 #define RingNext(ring)  ((ring)->next)
-/* .ring.elt: See design.mps.ring.elt */
+/* .ring.elt: See <design/ring/#elt> */
 #define RING_ELT(type, field, node) \
   ((type)((char *)(node) - (size_t)(&((type)0)->field)))
-/* .ring.for: See design.mps.ring.for */
+/* .ring.for: See <design/ring/#for> */
 #define RING_FOR(node, ring, next) \
  for(node = RingNext(ring), next = RingNext(node); \
      node != (ring); \
diff --git a/mps/code/root.c b/mps/code/root.c
index 736edc04e19..66cf2795db5 100644
--- a/mps/code/root.c
+++ b/mps/code/root.c
@@ -5,8 +5,8 @@
 *
 * .purpose: This is the implementation of the root datatype.
 *
- * .design: For design, see design.mps.root and
+ * .design: For design, see <design/root/> and
- * design.mps.root-interface. */
+ * <design/root/>-interface. */
 #include "mpm.h"
@@ -154,7 +154,7 @@ Bool RootCheck(Root root)
 * RootCreate* set up the appropriate union member, and call the generic
 * create function to do the actual creation
 *
- * See design.mps.root.init for initial value. */
+ * See <design/root/#init> for initial value. */
 static Res rootCreate(Root *rootReturn, Arena arena,
                      Rank rank, RootMode mode, RootVar type,
@@ -188,7 +188,7 @@ static Res rootCreate(Root *rootReturn, Arena arena,
  root->protBase = (Addr)0;
  root->protLimit = (Addr)0;
-  /* See design.mps.arena.root-ring */
+  /* See <design/arena/#root-ring> */
  RingInit(&root->arenaRing);
  root->serial = globals->rootSerial;
diff --git a/mps/code/seg.c b/mps/code/seg.c
index ca3c1c47b80..60157242c92 100644
--- a/mps/code/seg.c
+++ b/mps/code/seg.c
@@ -3,7 +3,7 @@
 * $Id$
 * Copyright (c) 2001 Ravenbrook Limited.  See end of file for license.
 *
- * .design: The design for this module is design.mps.seg.
+ * .design: The design for this module is <design/seg/>.
 *
 * PURPOSE
 *
@@ -169,7 +169,7 @@ static Res SegInit(Seg seg, Pool pool, Addr base, Size size,
  seg->sig = SegSig;  /* set sig now so tract checks will see it */
  TRACT_FOR(tract, addr, arena, base, limit) {
-    AVER(TractCheck(tract));  /* design.mps.check.type.no-sig */
+    AVER(TractCheck(tract));  /* <design/check/#type.no-sig> */
    AVER(TractP(tract) == NULL);
    AVER(!TractHasSeg(tract));
    AVER(TractPool(tract) == pool);
@@ -197,7 +197,7 @@ static Res SegInit(Seg seg, Pool pool, Addr base, Size size,
 failInit:
  RingFinish(SegPoolRing(seg));
  TRACT_FOR(tract, addr, arena, base, limit) {
-    AVER(TractCheck(tract));  /* design.mps.check.type.no-sig */
+    AVER(TractCheck(tract));  /* <design/check/#type.no-sig> */
    TRACT_UNSET_SEG(tract);
  }
  seg->sig = SigInvalid;
@@ -234,7 +234,7 @@ static void SegFinish(Seg seg)
  base = SegBase(seg);
  limit = SegLimit(seg);
  TRACT_TRACT_FOR(tract, addr, arena, seg->firstTract, limit) {
-    AVER(TractCheck(tract));  /* design.mps.check.type.no-sig */
+    AVER(TractCheck(tract));  /* <design/check/#type.no-sig> */
    TractSetWhite(tract, TraceSetEMPTY);
    TRACT_UNSET_SEG(tract);
  }
@@ -491,7 +491,7 @@ Bool SegNext(Seg *segReturn, Arena arena, Addr addr)
 /* SegMerge -- Merge two adjacent segments
 *
- * See design.mps.seg.merge
+ * See <design/seg/#merge>
 */
 Res SegMerge(Seg *mergedSegReturn, Seg segLo, Seg segHi,
@@ -516,7 +516,7 @@ Res SegMerge(Seg *mergedSegReturn, Seg segLo, Seg segHi,
  AVER(BoolCheck(withReservoirPermit));
  arena = PoolArena(SegPool(segLo));
-  ShieldFlush(arena);  /* see design.mps.seg.split-merge.shield */
+  ShieldFlush(arena);  /* see <design/seg/#split-merge.shield> */
  /* Invoke class-specific methods to do the merge */
  va_start(args, withReservoirPermit);
@@ -543,7 +543,7 @@ failMerge:
 /* SegSplit -- Split a segment
 *
 * The segment is split at the indicated position.
- * See design.mps.seg.split
+ * See <design/seg/#split>
 */
 Res SegSplit(Seg *segLoReturn, Seg *segHiReturn, Seg seg, Addr at,
@@ -569,7 +569,7 @@ Res SegSplit(Seg *segLoReturn, Seg *segHiReturn, Seg seg, Addr at,
  AVER(at < limit);
  AVER(BoolCheck(withReservoirPermit));
-  ShieldFlush(arena);  /* see design.mps.seg.split-merge.shield */
+  ShieldFlush(arena);  /* see <design/seg/#split-merge.shield> */
  /* Allocate the new segment object from the control pool */
  res = ControlAlloc((void **)&segNew, arena, class->size,
@@ -625,7 +625,7 @@ Bool SegCheck(Seg seg)
  /* can't assume nailed is subset of white - mightn't be during whiten */
  /* CHECKL(TraceSetSub(seg->nailed, seg->white)); */
  CHECKL(TraceSetCheck(seg->grey));
-  CHECKL(TractCheck(seg->firstTract));  /* design.mps.check.type.no-sig */
+  CHECKL(TractCheck(seg->firstTract));  /* <design/check/#type.no-sig> */
  pool = SegPool(seg);
  CHECKU(Pool, pool);
  arena = PoolArena(pool);
@@ -640,7 +640,7 @@ Bool SegCheck(Seg seg)
    Seg trseg;
    UNUSED(trseg); /* @@@@ unused in hot varieties */
-    CHECKL(TractCheck(tract));  /* design.mps.check.type.no-sig */
+    CHECKL(TractCheck(tract));  /* <design/check/#type.no-sig> */
    CHECKL(TRACT_SEG(&trseg, tract) && (trseg == seg));
    CHECKL(TractWhite(tract) == seg->white);
    CHECKL(TractPool(tract) == pool);
@@ -657,13 +657,13 @@ Bool SegCheck(Seg seg)
  /* "pm", "sm", and "depth" not checked.  See .check.shield. */
  CHECKL(RankSetCheck(seg->rankSet));
  if (seg->rankSet == RankSetEMPTY) {
-    /* design.mps.seg.field.rankSet.empty: If there are no refs */
+    /* <design/seg/#field.rankSet.empty>: If there are no refs */
    /* in the segment then it cannot contain black or grey refs. */
    CHECKL(seg->grey == TraceSetEMPTY);
    CHECKL(seg->sm == AccessSetEMPTY);
    CHECKL(seg->pm == AccessSetEMPTY);
  } else {
-    /* design.mps.seg.field.rankSet.single: The Tracer only permits */
+    /* <design/seg/#field.rankSet.single>: The Tracer only permits */
    /* one rank per segment [ref?] so this field is either empty or a */
    /* singleton. */
    CHECKL(RankSetIsSingle(seg->rankSet));
@@ -807,7 +807,7 @@ static Res segNoMerge(Seg seg, Seg segHi,
 /* segTrivMerge -- Basic Seg merge method
 *
 * .similar: Segments must be "sufficiently similar".
- * See design.mps.seg.merge.inv.similar
+ * See <design/seg/#merge.inv.similar>
 */
 static Res segTrivMerge(Seg seg, Seg segHi,
@@ -846,14 +846,14 @@ static Res segTrivMerge(Seg seg, Seg segHi,
  AVER(seg->sm == segHi->sm);
  AVER(seg->depth == segHi->depth);
  /* Neither segment may be exposed, or in the shield cache */
-  /* See design.mps.seg.split-merge.shield & impl.c.shield.def.depth */
+  /* See <design/seg/#split-merge.shield> & impl.c.shield.def.depth */
  AVER(seg->depth == 0);
  /* no need to update fields which match. See .similar */
  seg->limit = limit;
  TRACT_FOR(tract, addr, arena, mid, limit) {
-    AVER(TractCheck(tract));  /* design.mps.check.type.no-sig */
+    AVER(TractCheck(tract));  /* <design/check/#type.no-sig> */
    AVER(TractHasSeg(tract));
    AVER(segHi == TractP(tract));
    AVER(TractPool(tract) == pool);
@@ -919,7 +919,7 @@ static Res segTrivSplit(Seg seg, Seg segHi,
  UNUSED(args);
  /* Segment may not be exposed, or in the shield cache */
-  /* See design.mps.seg.split-merge.shield & impl.c.shield.def.depth */
+  /* See <design/seg/#split-merge.shield> & impl.c.shield.def.depth */
  AVER(seg->depth == 0);
 
  /* Full initialization for segHi. Just modify seg. */
@@ -938,7 +938,7 @@ static Res segTrivSplit(Seg seg, Seg segHi,
  RingInit(SegPoolRing(segHi));
  TRACT_FOR(tract, addr, arena, mid, limit) {
-    AVER(TractCheck(tract));  /* design.mps.check.type.no-sig */
+    AVER(TractCheck(tract));  /* <design/check/#type.no-sig> */
    AVER(TractHasSeg(tract));
    AVER(seg == TractP(tract));
    AVER(TractPool(tract) == pool);
@@ -1032,7 +1032,7 @@ Bool GCSegCheck(GCSeg gcseg)
  if (gcseg->buffer != NULL) {
    CHECKU(Buffer, gcseg->buffer);
-    /* design.mps.seg.field.buffer.owner */
+    /* <design/seg/#field.buffer.owner> */
    CHECKL(BufferPool(gcseg->buffer) == SegPool(seg));
    CHECKL(BufferRankSet(gcseg->buffer) == SegRankSet(seg));
  }
@@ -1043,7 +1043,7 @@ Bool GCSegCheck(GCSeg gcseg)
         RingIsSingle(&gcseg->greyRing));
  if (seg->rankSet == RankSetEMPTY) {
-    /* design.mps.seg.field.rankSet.empty */
+    /* <design/seg/#field.rankSet.empty> */
    CHECKL(gcseg->summary == RefSetEMPTY);
  }
@@ -1244,7 +1244,7 @@ static void gcSegSetWhite(Seg seg, TraceSet white)
    Seg trseg;
    UNUSED(trseg); /* @@@@ hack: unused in hot varieties */
-    AVER_CRITICAL(TractCheck(tract));  /* design.mps.check.type.no-sig */
+    AVER_CRITICAL(TractCheck(tract));  /* <design/check/#type.no-sig> */
    AVER_CRITICAL(TRACT_SEG(&trseg, tract) && (trseg == seg));
    TractSetWhite(tract, white);
  }
@@ -1406,7 +1406,7 @@ static void gcSegSetBuffer(Seg seg, Buffer buffer)
 /* gcSegMerge -- GCSeg merge method
 *
 * .buffer: Can't merge two segments both with buffers.
- * See design.mps.seg.merge.inv.buffer.
+ * See <design/seg/#merge.inv.buffer>.
 */
 static Res gcSegMerge(Seg seg, Seg segHi,
@@ -1450,7 +1450,7 @@ static Res gcSegMerge(Seg seg, Seg segHi,
  summary = RefSetUnion(gcseg->summary, gcsegHi->summary);
  if (summary != gcseg->summary) {
    gcSegSetSummary(seg, summary);
-    /* design.mps.seg.split-merge.shield.re-flush */
+    /* <design/seg/#split-merge.shield.re-flush> */
    ShieldFlush(PoolArena(SegPool(seg)));
  }
diff --git a/mps/code/segsmss.c b/mps/code/segsmss.c
index c4084813f6e..df3cca7cdad 100644
--- a/mps/code/segsmss.c
+++ b/mps/code/segsmss.c
@@ -51,7 +51,7 @@ typedef struct AMSTStruct {
  Count badMerges;          /* count of unsuccessful segment merges */
  Count bsplits;            /* count of buffered segment splits */
  Count bmerges;            /* count of buffered segment merges */
-  Sig sig;                  /* design.mps.pool.outer-structure.sig */
+  Sig sig;                  /* <design/pool/#outer-structure.sig> */
 } AMSTStruct;
 typedef struct AMSTStruct *AMST;
@@ -92,7 +92,7 @@ typedef struct AMSTSegStruct {
  AMSSegStruct amsSegStruct; /* superclass fields must come first */
  AMSTSeg next;          /* mergeable next segment, or NULL */
  AMSTSeg prev;          /* mergeable prev segment, or NULL */
-  Sig sig;               /* design.mps.pool.outer-structure.sig */
+  Sig sig;               /* <design/pool/#outer-structure.sig> */
 } AMSTSegStruct;
@@ -173,7 +173,7 @@ static void amstSegFinish(Seg seg)
 * .fail: Test proper handling of the most complex failure cases
 * by deliberately detecting failure sometimes after calling the
 * next method. We handle the error by calling the anti-method.
- * This isn't strictly safe (see design.mps.poolams.split-merge.fail).
+ * This isn't strictly safe (see <design/poolams/#split-merge.fail>).
 * But we assume here that we won't run out of memory when calling the
 * anti-method.
 */
diff --git a/mps/code/shield.c b/mps/code/shield.c
index d7727fec847..69f8e99929d 100644
--- a/mps/code/shield.c
+++ b/mps/code/shield.c
@@ -101,7 +101,7 @@ void (ShieldResume)(Arena arena)
 /* This ensures actual prot mode does not include mode */
 static void protLower(Arena arena, Seg seg, AccessSet mode)
 {
-  /* design.mps.trace.fix.noaver */
+  /* <design/trace/#fix.noaver> */
  AVERT_CRITICAL(Arena, arena);
  UNUSED(arena);
  AVERT_CRITICAL(Seg, seg);
@@ -153,7 +153,7 @@ static void flush(Arena arena, Size i)
 */
 static void cache(Arena arena, Seg seg)
 {
-  /* design.mps.trace.fix.noaver */
+  /* <design/trace/#fix.noaver> */
  AVERT_CRITICAL(Arena, arena);
  AVERT_CRITICAL(Seg, seg);
@@ -271,13 +271,13 @@ void (ShieldLeave)(Arena arena)
 void (ShieldExpose)(Arena arena, Seg seg)
 {
  AccessSet mode = AccessREAD | AccessWRITE;
-  /* design.mps.trace.fix.noaver */
+  /* <design/trace/#fix.noaver> */
  AVERT_CRITICAL(Arena, arena);
  AVER_CRITICAL(arena->insideShield);
  SegSetDepth(seg, SegDepth(seg) + 1);
  ++arena->shDepth;
-  /* design.mps.trace.fix.noaver */
+  /* <design/trace/#fix.noaver> */
  AVER_CRITICAL(arena->shDepth > 0);
  AVER_CRITICAL(SegDepth(seg) > 0);
  if (SegPM(seg) & mode)
@@ -290,7 +290,7 @@ void (ShieldExpose)(Arena arena, Seg seg)
 void (ShieldCover)(Arena arena, Seg seg)
 {
-  /* design.mps.trace.fix.noaver */
+  /* <design/trace/#fix.noaver> */
  AVERT_CRITICAL(Arena, arena);
  AVERT_CRITICAL(Seg, seg);
  AVER_CRITICAL(SegPM(seg) == AccessSetEMPTY);
diff --git a/mps/code/splay.c b/mps/code/splay.c
index fda71e8bd69..6e4beebc998 100644
--- a/mps/code/splay.c
+++ b/mps/code/splay.c
@@ -6,7 +6,7 @@
 * .purpose: Splay trees are used to manage potentially unbounded
 * collections of ordered things.
 *
- * .source: design.mps.splay
+ * .source: <design/splay/>
 *
 * .note.stack: It's important that the MPS have a bounded stack
 * size, and this is a problem for tree algorithms.  Basically,
@@ -108,7 +108,7 @@ static void SplayNodeUpdate(SplayTree tree, SplayNode node)
 * Link the current top node into the left child of the right tree,
 * leaving the top node as the left child of the old top node.
 *
- * See design.mps.splay.impl.link.right.
+ * See <design/splay/#impl.link.right>.
 */
 static void SplayLinkRight(SplayNode *topIO, SplayNode *rightIO)
@@ -135,7 +135,7 @@ static void SplayLinkRight(SplayNode *topIO, SplayNode *rightIO)
 * Link the current top node into the right child of the left tree,
 * leaving the top node as the right child of the old top node.
 *
- * See design.mps.splay.impl.link.left.
+ * See <design/splay/#impl.link.left>.
 */
 static void SplayLinkLeft(SplayNode *topIO, SplayNode *leftIO) {
@@ -161,7 +161,7 @@ static void SplayLinkLeft(SplayNode *topIO, SplayNode *leftIO) {
 * Rotates node, right child of node, and left child of right
 * child of node, leftwards in the order stated.
 *
- * See design.mps.splay.impl.rotate.left.
+ * See <design/splay/#impl.rotate.left>.
 */
 static void SplayRotateLeft(SplayNode *nodeIO, SplayTree tree) {
@@ -192,7 +192,7 @@ static void SplayRotateLeft(SplayNode *nodeIO, SplayTree tree) {
 * Rotates node, left child of node, and right child of left
 * child of node, leftwards in the order stated.
 *
- * See design.mps.splay.impl.rotate.right.
+ * See <design/splay/#impl.rotate.right>.
 */
 static void SplayRotateRight(SplayNode *nodeIO, SplayTree tree) {
@@ -228,7 +228,7 @@ static void SplayRotateRight(SplayNode *nodeIO, SplayTree tree) {
 * left and right trees and their last and first nodes respectively
 * will have out of date client properties.
 *
- * See design.mps.splay.impl.assemble.
+ * See <design/splay/#impl.assemble>.
 */
 static void SplayAssemble(SplayTree tree, SplayNode top,
@@ -317,7 +317,7 @@ static void SplayAssemble(SplayTree tree, SplayNode top,
 * Returns whether key was found.  This is the real logic behind
 * splay trees.
 *
- * See design.mps.splay.impl.splay.
+ * See <design/splay/#impl.splay>.
 */
 static Bool SplaySplay(SplayNode *nodeReturn, SplayTree tree,
@@ -464,8 +464,8 @@ assemble:
 /* SplayTreeInsert -- Insert a node into a splay tree
 *
- * See design.mps.splay.function.splay.tree.insert and
+ * See <design/splay/#function.splay.tree.insert> and
- * design.mps.splay.impl.insert.
+ * <design/splay/#impl.insert>.
 */
 Res SplayTreeInsert(SplayTree tree, SplayNode node, void *key) {
@@ -516,8 +516,8 @@ Res SplayTreeInsert(SplayTree tree, SplayNode node, void *key) {
 /* SplayTreeDelete -- Delete a node from a splay tree
 *
- * See design.mps.splay.function.splay.tree.delete and
+ * See <design/splay/#function.splay.tree.delete> and
- * design.mps.splay.impl.delete.
+ * <design/splay/#impl.delete>.
 */
 Res SplayTreeDelete(SplayTree tree, SplayNode node, void *key) {
@@ -558,8 +558,8 @@ Res SplayTreeDelete(SplayTree tree, SplayNode node, void *key) {
 /* SplayTreeSearch -- Search for a node in a splay tree matching a key
 *
- * See design.mps.splay.function.splay.tree.search and
+ * See <design/splay/#function.splay.tree.search> and
- * design.mps.splay.impl.search.
+ * <design/splay/#impl.search>.
 */
@@ -657,8 +657,8 @@ static SplayNode SplayTreeSuccessor(SplayTree tree, void *key) {
 *
 * Search for the two nodes in a splay tree neighbouring a key.
 *
- * See design.mps.splay.function.splay.tree.neighbours and
+ * See <design/splay/#function.splay.tree.neighbours> and
- * design.mps.splay.impl.neighbours.
+ * <design/splay/#impl.neighbours>.
 */
@@ -702,12 +702,12 @@ Res SplayTreeNeighbours(SplayNode *leftReturn, SplayNode *rightReturn,
 * SplayTreeFirst receives a key that must precede all
 * nodes in the tree.  It returns NULL if the tree is empty. 
 * Otherwise, it splays the tree to the first node, and returns the
- * new root.  See design.mps.splay.function.splay.tree.first.
+ * new root.  See <design/splay/#function.splay.tree.first>.
 *
 * SplayTreeNext takes a tree and splays it to the successor of the
 * old root, and returns the new root.  Returns NULL is there are
 * no successors.  It takes a key for the old root.  See
- * design.mps.splay.function.splay.tree.next.
+ * <design/splay/#function.splay.tree.next>.
 */
 SplayNode SplayTreeFirst(SplayTree tree, void *zeroKey) {
@@ -990,7 +990,7 @@ void SplayNodeRefresh(SplayTree tree, SplayNode node, void *key)
 /* SplayTreeDescribe -- Describe a splay tree
 *
- * See design.mps.splay.function.splay.tree.describe.
+ * See <design/splay/#function.splay.tree.describe>.
 */
 Res SplayTreeDescribe(SplayTree tree, mps_lib_FILE *stream,
diff --git a/mps/code/splay.h b/mps/code/splay.h
index 34f46e7b008..5a3060b1d8a 100644
--- a/mps/code/splay.h
+++ b/mps/code/splay.h
@@ -3,7 +3,7 @@
 * $Id$
 * Copyright (c) 2001 Ravenbrook Limited.  See end of file for license.
 *
- * .source: design.mps.splay
+ * .source: <design/splay/>
 */
 #ifndef splay_h
diff --git a/mps/code/sso1al.s b/mps/code/sso1al.s
index b55b387e315..3b592bb741d 100644
--- a/mps/code/sso1al.s
+++ b/mps/code/sso1al.s
@@ -6,7 +6,7 @@
 # .readership: Any MPS developer that is prepared to read Alpha
 # assembly code in DIGITAL UNIX 'as' syntax.
 #
- # See design.mps.sso1al for the design (exists).
+ # See <design/sso1al/> for the design (exists).
 .globl  StackScan
diff --git a/mps/code/than.c b/mps/code/than.c
index 1fb39eb1195..85753d9e6b2 100644
--- a/mps/code/than.c
+++ b/mps/code/than.c
@@ -18,7 +18,7 @@ SRCID(than, "$Id$");
 typedef struct ThreadStruct {   /* ANSI fake thread structure */
-  Sig sig;                      /* design.mps.sig */
+  Sig sig;                      /* <design/sig/> */
  Serial serial;                /* from arena->threadSerial */
  Arena arena;                  /* owning arena */
  RingStruct arenaRing;         /* attaches to arena */
@@ -112,7 +112,7 @@ Thread ThreadRingThread(Ring threadRing)
 }
-/* Must be thread-safe.  See design.mps.interface.c.thread-safety. */
+/* Must be thread-safe.  See <design/interface-c/#thread-safety>. */
 Arena ThreadArena(Thread thread)
 {
  /* Can't AVER thread as that would not be thread-safe */
diff --git a/mps/code/thfri4.c b/mps/code/thfri4.c
index 1276ee9d667..163b58c1450 100644
--- a/mps/code/thfri4.c
+++ b/mps/code/thfri4.c
@@ -52,7 +52,7 @@ SRCID(thfri4, "$Id$");
 /* ThreadStruct -- thread desriptor */
 typedef struct ThreadStruct {    /* PThreads thread structure */
-  Sig sig;                       /* design.mps.sig */
+  Sig sig;                       /* <design/sig/> */
  Serial serial;                 /* from arena->threadSerial */
  Arena arena;                   /* owning arena */
  RingStruct arenaRing;          /* threads attached to arena */
@@ -218,7 +218,7 @@ Thread ThreadRingThread(Ring threadRing)
 /* ThreadArena -- get the arena of a thread
 *
- * Must be thread-safe.  See design.mps.interface.c.thread-safety.
+ * Must be thread-safe.  See <design/interface-c/#thread-safety>.
 */
 Arena ThreadArena(Thread thread)
diff --git a/mps/code/thlii4.c b/mps/code/thlii4.c
index b4b7149c56b..29760d32227 100644
--- a/mps/code/thlii4.c
+++ b/mps/code/thlii4.c
@@ -52,7 +52,7 @@ SRCID(thlii4, "$Id$");
 /* ThreadStruct -- thread desriptor */
 typedef struct ThreadStruct {    /* PThreads thread structure */
-  Sig sig;                       /* design.mps.sig */
+  Sig sig;                       /* <design/sig/> */
  Serial serial;                 /* from arena->threadSerial */
  Arena arena;                   /* owning arena */
  RingStruct arenaRing;          /* threads attached to arena */
@@ -218,7 +218,7 @@ Thread ThreadRingThread(Ring threadRing)
 /* ThreadArena -- get the arena of a thread
 *
- * Must be thread-safe.  See design.mps.interface.c.thread-safety.
+ * Must be thread-safe.  See <design/interface-c/#thread-safety>.
 */
 Arena ThreadArena(Thread thread)
diff --git a/mps/code/thw3i3.c b/mps/code/thw3i3.c
index 6d550445e7c..fdbf7ee6374 100644
--- a/mps/code/thw3i3.c
+++ b/mps/code/thw3i3.c
@@ -84,7 +84,7 @@ SRCID(thw3i3, "$Id$");
 typedef struct ThreadStruct {   /* Win32 thread structure */
-  Sig sig;                      /* design.mps.sig */
+  Sig sig;                      /* <design/sig/> */
  Serial serial;                /* from arena->threadSerial */
  Arena arena;                  /* owning arena */
  RingStruct arenaRing;         /* threads attached to arena */
@@ -303,7 +303,7 @@ Res ThreadScan(ScanState ss, Thread thread, void *stackBot)
  return ResOK;
 }
-/* Must be thread-safe.  See design.mps.interface.c.thread-safety. */
+/* Must be thread-safe.  See <design/interface-c/#thread-safety>. */
 Arena ThreadArena(Thread thread)
 {
  /* Can't AVER thread as that would not be thread-safe */
diff --git a/mps/code/trace.c b/mps/code/trace.c
index 70892618e1c..d72f5aff1bf 100644
--- a/mps/code/trace.c
+++ b/mps/code/trace.c
@@ -3,7 +3,7 @@
 * $Id$
 * Copyright (c) 2001 Ravenbrook Limited.  See end of file for license.
 *
- * .design: design.mps.trace.  */
+ * .design: <design/trace/>.  */
 #include "chain.h"
 #include "mpm.h"
@@ -101,7 +101,7 @@ static MessageClassStruct TraceMessageClassStruct = {
  TraceMessageLiveSize,          /* GCLiveSize */
  TraceMessageCondemnedSize,     /* GCCondemnedSize */
  TraceMessageNotCondemnedSize,  /* GCNotCondemnedSize */
-  MessageClassSig                /* design.mps.message.class.sig.double */
+  MessageClassSig                /* <design/message/#class.sig.double> */
 };
 static void TraceMessageInit(Arena arena, TraceMessage tMessage)
@@ -578,7 +578,7 @@ static void traceFlip(Trace trace)
  /* needs to change when we flip later (i.e. have a read-barrier     */
  /* collector), so that we allocate grey or white before the flip    */
  /* and black afterwards. For instance, see                          */
-  /* design.mps.poolams.invariant.alloc.                              */
+  /* <design/poolams/#invariant.alloc>.                              */
  /* Now that the mutator is black we must prevent it from reading */
  /* grey objects so that it can't obtain white pointers.  This is */
@@ -640,7 +640,7 @@ Res TraceCreate(Trace *traceReturn, Arena arena)
 found:
  trace = ArenaTrace(arena, ti);
-  AVER(trace->sig == SigInvalid);       /* design.mps.arena.trace.invalid */
+  AVER(trace->sig == SigInvalid);       /* <design/arena/#trace.invalid> */
  trace->arena = arena;
  trace->white = ZoneSetEMPTY;
@@ -945,7 +945,7 @@ static Res traceScanSegRes(TraceSet ts, Rank rank, Arena arena, Seg seg)
      });
    /* following is true whether or not scan was total */
-    /* See design.mps.scan.summary.subset. */
+    /* See <design/scan/#summary.subset>. */
    AVER(RefSetSub(ss.unfixedSummary, SegSummary(seg)));
    if (res != ResOK || !wasTotal) {
@@ -1057,7 +1057,7 @@ Res TraceFix(ScanState ss, Ref *refIO)
  Tract tract;
  Pool pool;
-  /* See design.mps.trace.fix.noaver */
+  /* See <design/trace/#fix.noaver> */
  AVERT_CRITICAL(ScanState, ss);
  AVER_CRITICAL(refIO != NULL);
@@ -1085,7 +1085,7 @@ Res TraceFix(ScanState ss, Ref *refIO)
      }
    } else {
      /* Tract isn't white. Don't compute seg for non-statistical */
-      /* variety. See design.mps.trace.fix.tractofaddr */
+      /* variety. See <design/trace/#fix.tractofaddr> */
      STATISTIC_STAT
        ({
          Seg seg;
@@ -1096,12 +1096,12 @@ Res TraceFix(ScanState ss, Ref *refIO)
        });
    }
  } else {
-    /* See design.mps.trace.exact.legal */
+    /* See <design/trace/#exact.legal> */
    AVER(ss->rank < RankEXACT
         || !ArenaIsReservedAddr(ss->arena, ref));
  }
-  /* See design.mps.trace.fix.fixed.all */
+  /* See <design/trace/#fix.fixed.all> */
  ss->fixedSummary = RefSetAdd(ss->arena, ss->fixedSummary, *refIO);
  return ResOK;
@@ -1138,7 +1138,7 @@ Res TraceFixEmergency(ScanState ss, Ref *refIO)
      }
    } else {
      /* Tract isn't white. Don't compute seg for non-statistical */
-      /* variety. See design.mps.trace.fix.tractofaddr */
+      /* variety. See <design/trace/#fix.tractofaddr> */
      STATISTIC_STAT
        ({
          Seg seg;
@@ -1149,12 +1149,12 @@ Res TraceFixEmergency(ScanState ss, Ref *refIO)
        });
    }
  } else {
-    /* See design.mps.trace.exact.legal */
+    /* See <design/trace/#exact.legal> */
    AVER(ss->rank < RankEXACT ||
         !ArenaIsReservedAddr(ss->arena, ref));
  }
-  /* See design.mps.trace.fix.fixed.all */
+  /* See <design/trace/#fix.fixed.all> */
  ss->fixedSummary = RefSetAdd(ss->arena, ss->fixedSummary, *refIO);
  return ResOK;
@@ -1358,7 +1358,7 @@ double TraceWorkFactor = 0.25;
 * recently returned from TraceCreate, with some condemned segments
 * added.  mortality is the fraction of the condemned set expected to
 * survive.  finishingTime is relative to the current polling clock, see
- * design.mps.arena.poll.clock.
+ * <design/arena/#poll.clock>.
 *
 * .start.black: All segments are black w.r.t. a newly allocated trace.
 * However, if TraceStart initialized segments to black when it
diff --git a/mps/code/tract.c b/mps/code/tract.c
index 04aec3811ed..e79f0e9846e 100644
--- a/mps/code/tract.c
+++ b/mps/code/tract.c
@@ -411,14 +411,14 @@ Bool TractOfAddr(Tract *tractReturn, Arena arena, Addr addr)
  Index i;
  Chunk chunk;
 
-  /* design.mps.trace.fix.noaver */
+  /* <design/trace/#fix.noaver> */
  AVER_CRITICAL(tractReturn != NULL); /* .tract.critical */
  AVERT_CRITICAL(Arena, arena);
  b = ChunkOfAddr(&chunk, arena, addr);
  if (!b)
    return FALSE;
-  /* design.mps.trace.fix.tractofaddr */
+  /* <design/trace/#fix.tractofaddr> */
  i = INDEX_OF_ADDR(chunk, addr);
  /* .addr.free: If the page is recorded as being free then */
  /* either the page is free or it is */
@@ -446,7 +446,7 @@ Tract TractOfBaseAddr(Arena arena, Addr addr)
  AVERT_CRITICAL(Arena, arena);
  AVER_CRITICAL(AddrIsAligned(addr, arena->alignment));
-  /* Check first in the cache, see design.mps.arena.tract.cache. */
+  /* Check first in the cache, see <design/arena/#tract.cache>. */
  if (arena->lastTractBase == addr) {
    tract = arena->lastTract;
  } else {
diff --git a/mps/code/tract.h b/mps/code/tract.h
index 1a7f56f1b14..a08b1d655a6 100644
--- a/mps/code/tract.h
+++ b/mps/code/tract.h
@@ -15,14 +15,14 @@
 /* TractStruct -- tract structure
 *
 * .tract: Tracts represent the grains of memory allocation from
- * the arena.  See design.mps.arena.
+ * the arena.  See <design/arena/>.
 *
 * .bool: The hasSeg field is a boolean, but can't be represented
- * as type Bool. See design.mps.arena.tract.field.hasSeg.
+ * as type Bool. See <design/arena/#tract.field.hasSeg>.
 */
 typedef struct TractStruct { /* Tract structure */
-  Pool pool;      /* MUST BE FIRST (design.mps.arena.tract.field pool) */
+  Pool pool;      /* MUST BE FIRST (<design/arena/#tract.field> pool) */
  void *p;                     /* pointer for use of owning pool */
  Addr base;                   /* Base address of the tract */
  TraceSet white : TraceLIMIT; /* traces for which tract is white */
@@ -66,10 +66,10 @@ extern void TractFinish(Tract tract);
 *
 * .page-table: The page table (defined as a PageStruct array)
 * is central to the design of the arena.
- * See design.mps.arena.vm.table.*.
+ * See <design/arenavm/#table>.*.
 *
 * .page: The "pool" field must be the first field of the "tail"
- * field of this union.  See design.mps.arena.tract.field.pool.
+ * field of this union.  See <design/arena/#tract.field.pool>.
 *
 * .states: Pages (hence PageStructs that describe them) can be in
 * one of 3 states:
@@ -118,7 +118,7 @@ typedef struct PageStruct {     /* page structure */
 /* PageIsAllocated -- is a page allocated?
 *
- * See design.mps.arena.vm.table.disc.
+ * See <design/arenavm/#table.disc>.
 */
 #define PageIsAllocated(page) ((page)->the.rest.pool != NULL)
@@ -134,7 +134,7 @@ typedef struct PageStruct {     /* page structure */
 #define ChunkSig ((Sig)0x519C804C) /* SIGnature CHUNK */
 typedef struct ChunkStruct {
-  Sig sig;              /* design.mps.sig */
+  Sig sig;              /* <design/sig/> */
  Serial serial;        /* serial within the arena */
  Arena arena;          /* parent arena */
  RingStruct chunkRing; /* ring of all chunks in arena */
@@ -224,7 +224,7 @@ extern Index IndexOfAddr(Chunk chunk, Addr addr);
 /* PageIndexBase -- map page index to base address of page
 *
- * See design.mps.arena.vm.table.linear
+ * See <design/arenavm/#table.linear>
 */
 #define PageIndexBase(chunk, i) \
@@ -248,7 +248,7 @@ extern Bool TractNext(Tract *tractReturn, Arena arena, Addr addr);
 /* TRACT_TRACT_FOR -- iterate over a range of tracts
 *
- * See design.mps.arena.tract-iter.if.macro.
+ * See <design/arena/#tract-iter.if.macro>.
 * Parameters arena & limit are evaluated multiple times.
 * Check first tract & last tract lie with the same chunk.
 */
@@ -265,7 +265,7 @@ extern Bool TractNext(Tract *tractReturn, Arena arena, Addr addr);
 /* TRACT_FOR -- iterate over a range of tracts
 *
- * See design.mps.arena.tract.for.
+ * See <design/arena/#tract.for>.
 * Parameters arena & limit are evaluated multiple times.
 */
diff --git a/mps/code/version.c b/mps/code/version.c
index a2978fc0e5b..f7b3078948f 100644
--- a/mps/code/version.c
+++ b/mps/code/version.c
@@ -10,7 +10,7 @@
 *
 * DESIGN
 *
- * .design: See design.mps.version-library, but to let you in on a
+ * .design: See <design/version/>-library, but to let you in on a
 * secret it works by declaring a string with all the necessary info
 * in.
 */
diff --git a/mps/code/vman.c b/mps/code/vman.c
index 76935e2cb64..aaec2a4345f 100644
--- a/mps/code/vman.c
+++ b/mps/code/vman.c
@@ -16,9 +16,9 @@ SRCID(vman, "$Id$");
 #define VMSig           ((Sig)0x519B3999) /* SIGnature VM */
-/* ANSI fake VM structure, see design.mps.vman */
+/* ANSI fake VM structure, see <design/vman/> */
 typedef struct VMStruct {
-  Sig sig;                      /* design.mps.sig */
+  Sig sig;                      /* <design/sig/> */
  Addr base, limit;             /* boundaries of malloc'd memory */
  void *block;                  /* pointer to malloc'd block, for free() */
  Size reserved;                /* total reserved address space */
diff --git a/mps/code/vmfr.c b/mps/code/vmfr.c
index a8d33de92ae..ce87e1b8431 100644
--- a/mps/code/vmfr.c
+++ b/mps/code/vmfr.c
@@ -7,7 +7,7 @@
 * interface (vm.h) for FreeBSD.  It was created by copying vmli.c (the
 * DIGITAL UNIX implementation) as that seemed to be closest.
 *
- * .design: See design.mps.vm.  .design.freebsd: mmap(2) is used to
+ * .design: See <design/vm/>.  .design.freebsd: mmap(2) is used to
 * reserve address space by creating a mapping with page access none.
 * mmap(2) is used to map pages onto store by creating a copy-on-write
 * (MAP_PRIVATE) mapping with the flag MAP_ANON.
@@ -51,7 +51,7 @@ SRCID(vmfr, "$Id$");
 #define VMSig           ((Sig)0x519B3999) /* SIGnature VM */
 typedef struct VMStruct {
-  Sig sig;                      /* design.mps.sig */
+  Sig sig;                      /* <design/sig/> */
  Align align;                  /* page size */
  Addr base, limit;             /* boundaries of reserved space */
  Size reserved;                /* total reserved address space */
@@ -266,7 +266,7 @@ void VMUnmap(VM vm, Addr base, Addr limit)
  size = AddrOffset(base, limit);
-  /* see design.mps.vmo1.fun.unmap.offset */
+  /* see <design/vmo1/#fun.unmap.offset> */
  addr = mmap((void *)base, (size_t)size,
              PROT_NONE, MAP_ANON | MAP_PRIVATE | MAP_FIXED,
              -1, 0);
diff --git a/mps/code/vmi5.c b/mps/code/vmi5.c
index 3d712589337..20934f9698d 100644
--- a/mps/code/vmi5.c
+++ b/mps/code/vmi5.c
@@ -3,7 +3,7 @@
 * $Id$
 * Copyright (c) 2001 Ravenbrook Limited.  See end of file for license.
 *
- * Design: design.mps.vm
+ * Design: <design/vm/>
 *
 * This is the implementation of the virtual memory mapping interface
 * (vm.h) for IRIX 5.x.
@@ -60,7 +60,7 @@ SRCID(vmi5, "$Id$");
 /* The name zero_fd is a transgression, see .fildes.name. */
 typedef struct VMStruct {
-  Sig sig;                      /* design.mps.sig */
+  Sig sig;                      /* <design/sig/> */
  int zero_fd;                  /* fildes for mmap */
  Align align;                  /* page size */
  Addr base, limit;             /* boundaries of reserved space */
diff --git a/mps/code/vmli.c b/mps/code/vmli.c
index 6c4d0d53246..251cf0792b5 100644
--- a/mps/code/vmli.c
+++ b/mps/code/vmli.c
@@ -7,7 +7,7 @@
 * interface (vm.h) for Linux.  It was created by copying vmo1.c (the
 * DIGITAL UNIX implementation) as that seemed to be closest.
 *
- * .design: See design.mps.vm.  .design.linux: mmap(2) is used to
+ * .design: See <design/vm/>.  .design.linux: mmap(2) is used to
 * reserve address space by creating a mapping with page access none.
 * mmap(2) is used to map pages onto store by creating a copy-on-write
 * (MAP_PRIVATE) mapping with the flag MAP_ANONYMOUS.
@@ -63,7 +63,7 @@ SRCID(vmli, "$Id$");
 #define VMSig           ((Sig)0x519B3999) /* SIGnature VM */
 typedef struct VMStruct {
-  Sig sig;                      /* design.mps.sig */
+  Sig sig;                      /* <design/sig/> */
  Align align;                  /* page size */
  Addr base, limit;             /* boundaries of reserved space */
  Size reserved;                /* total reserved address space */
@@ -282,7 +282,7 @@ void VMUnmap(VM vm, Addr base, Addr limit)
  size = AddrOffset(base, limit);
-  /* see design.mps.vmo1.fun.unmap.offset */
+  /* see <design/vmo1/#fun.unmap.offset> */
  addr = mmap((void *)base, (size_t)size,
              PROT_NONE, MAP_ANONYMOUS | MAP_PRIVATE | MAP_FIXED,
              -1, 0);
diff --git a/mps/code/vmo1.c b/mps/code/vmo1.c
index ea75bc65785..dc65879ca30 100644
--- a/mps/code/vmo1.c
+++ b/mps/code/vmo1.c
@@ -3,7 +3,7 @@
 * $Id$
 * Copyright (c) 2001 Ravenbrook Limited.  See end of file for license.
 *
- * .design: design.mps.vm, design.mps.vmo1
+ * .design: <design/vm/>, <design/vmo1/>
 *
 * .status: A bit hacky, but probably working.
 *
@@ -61,7 +61,7 @@ extern int getpagesize(void);
 #define VMSig           ((Sig)0x519B3999) /* SIGnature VM */
 typedef struct VMStruct {
-  Sig sig;                      /* design.mps.sig */
+  Sig sig;                      /* <design/sig/> */
  Align align;                  /* page size */
  Addr base, limit;             /* boundaries of reserved space */
  Size reserved;                /* total reserved address space */
@@ -269,7 +269,7 @@ Res VMMap(VM vm, Addr base, Addr limit)
 /* VMUnmap -- unmap the given range of memory
 *
- * See design.mps.vmo1.fun.unmap.
+ * See <design/vmo1/#fun.unmap>.
 */
 void VMUnmap(VM vm, Addr base, Addr limit)
@@ -287,7 +287,7 @@ void VMUnmap(VM vm, Addr base, Addr limit)
  size = AddrOffset(base, limit);
-  /* see design.mps.vmo1.fun.unmap.offset */
+  /* see <design/vmo1/#fun.unmap.offset> */
  addr = mmap((void *)base, (size_t)size,
              PROT_NONE, MAP_FILE | MAP_SHARED | MAP_FIXED,
              vm->none_fd, (off_t)AddrOffset(vm->base, base));
diff --git a/mps/code/vmso.c b/mps/code/vmso.c
index f3d1059cb18..2329a034318 100644
--- a/mps/code/vmso.c
+++ b/mps/code/vmso.c
@@ -5,7 +5,7 @@
 *
 * DESIGN
 *
- * .design: design.mps.vmso
+ * .design: <design/vmso/>
 *
 * PURPOSE
 *
@@ -68,7 +68,7 @@ extern int munmap(caddr_t addr, size_t len);
 /* The names of zero_fd and none_fd are transgressions, see .fildes.name */
 typedef struct VMStruct {
-  Sig sig;                      /* design.mps.sig */
+  Sig sig;                      /* <design/sig/> */
  int zero_fd;                  /* fildes for mmap */
  int none_fd;                  /* fildes for mmap */
  Align align;                  /* page size */
diff --git a/mps/code/vmsu.c b/mps/code/vmsu.c
index 34c62a17eed..81513ee433b 100644
--- a/mps/code/vmsu.c
+++ b/mps/code/vmsu.c
@@ -3,7 +3,7 @@
 * $Id$
 * Copyright (c) 2001 Ravenbrook Limited.  See end of file for license.
 *
- * .design: See design.mps.vm for general design.
+ * .design: See <design/vm/> for general design.
 *
 * mmap(2) is used to reserve address space by creating a mapping to
 * /etc/passwd with page access none.  mmap(2) is used to map pages
@@ -65,7 +65,7 @@ extern int getpagesize(void);
 /* The names of zero_fd and none_fd are transgressions, see .fildes.name */
 typedef struct VMStruct {
-  Sig sig;                      /* design.mps.sig */
+  Sig sig;                      /* <design/sig/> */
  int zero_fd;                  /* fildes for mmap, see impl.c.vms{o,u} */
  int none_fd;                  /* fildes for mmap, see impl.c.vms{o,u} */
  Align align;                  /* page size */
diff --git a/mps/code/vmw3.c b/mps/code/vmw3.c
index 462d75e29f6..1e667151cf0 100644
--- a/mps/code/vmw3.c
+++ b/mps/code/vmw3.c
@@ -3,7 +3,7 @@
 * $Id$
 * Copyright (c) 2001 Ravenbrook Limited.  See end of file for license.
 *
- * .design: See design.mps.vm.
+ * .design: See <design/vm/>.
 *
 * .purpose: This is the implementation of the virtual memory mapping
 * interface (vm.h) for Win32s.
@@ -63,7 +63,7 @@ SRCID(vmw3, "$Id$");
 #define VMSig           ((Sig)0x519B3999) /* SIGnature VM */
 typedef struct VMStruct {
-  Sig sig;                      /* design.mps.sig */
+  Sig sig;                      /* <design/sig/> */
  Align align;                  /* page size */
  Addr base, limit;             /* boundaries of reserved space */
  Size reserved;                /* total reserved address space */
diff --git a/mps/code/vmxc.c b/mps/code/vmxc.c
index 7cb53ca5725..737ac2b4204 100644
--- a/mps/code/vmxc.c
+++ b/mps/code/vmxc.c
@@ -3,7 +3,7 @@
 * $Id$
 * Copyright (c) 2001 Ravenbrook Limited.  See end of file for license.
 *
- * .design: design.mps.vm
+ * .design: <design/vm/>
 *
 * .details: mmap(2) is used to reserve address space by creating a
 * mapping to the swap with page access none.  mmap(2) is used to map
@@ -46,7 +46,7 @@ SRCID(vmxc, "$Id$");
 #define VMSig           ((Sig)0x519B3999) /* SIGnature VM */
 typedef struct VMStruct {
-  Sig sig;                      /* design.mps.sig */
+  Sig sig;                      /* <design/sig/> */
  Align align;                  /* page size */
  Addr base, limit;             /* boundaries of reserved space */
  Size reserved;                /* total reserved address space */
diff --git a/mps/code/walk.c b/mps/code/walk.c
index 42f2cd21c3a..acbcbdb7454 100644
--- a/mps/code/walk.c
+++ b/mps/code/walk.c
@@ -254,11 +254,11 @@ static Res RootsWalkFix(ScanState ss, Ref *refIO)
      rsc->f((mps_addr_t*)refIO, (mps_root_t)rsc->root, rsc->p, rsc->s);
    }
  } else {
-    /* See design.mps.trace.exact.legal */
+    /* See <design/trace/#exact.legal> */
    AVER(ss->rank < RankEXACT || !ArenaIsReservedAddr(arena, ref));
  }
-  /* See design.mps.trace.fix.fixed.all */
+  /* See <design/trace/#fix.fixed.all> */
  ss->fixedSummary = RefSetAdd(ss->arena, ss->fixedSummary, *refIO);
  AVER(ref == *refIO);  /* can walk object graph - but not modify it */
author	Richard Brooksby	2002-06-07 16:47:14 +0100
committer	Richard Brooksby	2002-06-07 16:47:14 +0100
commit	97075f705350901f5ff46387f658ab459a4cd73f (patch)
tree	4349ad5e7200f072a800f48749d57f3625757e7e /mps/code
parent	8b990e4858b6f6d735de07a241b1785702bb16e7 (diff)
download	emacs-97075f705350901f5ff46387f658ab459a4cd73f.tar.gz emacs-97075f705350901f5ff46387f658ab459a4cd73f.zip