diff --git a/mps/code/abq.c b/mps/code/abq.c
index 29f60148057..1ea2835907b 100644
--- a/mps/code/abq.c
+++ b/mps/code/abq.c
@@ -7,7 +7,7 @@
  *
  * .purpose: A FIFO queue substrate for <code/poolmv2.c>
  *
- * .design: See <design/poolmv2/>
+ * .design: See <design/poolmvt/>
  */
 
 #include "meter.h"
diff --git a/mps/code/abq.h b/mps/code/abq.h
index 85a62ab719f..e39635dfcaa 100644
--- a/mps/code/abq.h
+++ b/mps/code/abq.h
@@ -5,7 +5,7 @@
  *
  * .purpose: A FIFO queue substrate for <code/poolmv2.c>
  *
- * .source: <design/poolmv2/>
+ * .source: <design/poolmvt/>
  */
 
 #ifndef abq_h
diff --git a/mps/code/bt.h b/mps/code/bt.h
index c97190a13b0..7f318f8ee85 100644
--- a/mps/code/bt.h
+++ b/mps/code/bt.h
@@ -3,7 +3,8 @@
  * $Id$
  * Copyright (c) 2001 Ravenbrook Limited.  See end of file for license.
  *
- * .source: design.mps.bt.  */
+ * .source: <design/bt/>
+ */
 
 #ifndef bt_h
 #define bt_h
@@ -11,11 +12,10 @@
 #include "mpmtypes.h"
 
 
-/* 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/bt/#if.get> */
 extern Bool (BTGet)(BT bt, Index index);
 #define BTGet(a, i) \
diff --git a/mps/code/dbgpool.c b/mps/code/dbgpool.c
index 26165f27eb8..79d14a77727 100644
--- a/mps/code/dbgpool.c
+++ b/mps/code/dbgpool.c
@@ -160,7 +160,7 @@ static Res DebugPoolInit(Pool pool, va_list args)
   /* free-checking 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->freeSize = options->freeSize;
   if (debug->freeSize != 0) {
     if (PoolAlignment(pool) % debug->freeSize != 0) {
@@ -420,7 +420,7 @@ static Res tagAlloc(PoolDebugMixin debug,
   UNUSED(pool);
   res = PoolAlloc((Addr*)&tag, debug->tagPool, debug->tagSize, FALSE);
   if (res != ResOK) {
-    if (withReservoir) { /* design.mps.object-debug.out-of-space */
+    if (withReservoir) { /* <design/object-debug/#out-of-space */
       debug->missingTags++;
       return ResOK;
     } else {
diff --git a/mps/code/dbgpooli.c b/mps/code/dbgpooli.c
index 7c3b8648e11..52b6e7d3916 100644
--- a/mps/code/dbgpooli.c
+++ b/mps/code/dbgpooli.c
@@ -21,7 +21,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);
 
@@ -41,7 +41,7 @@ void mps_pool_check_free_space(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/finalcv.c b/mps/code/finalcv.c
index af021086aee..bada75a88b8 100644
--- a/mps/code/finalcv.c
+++ b/mps/code/finalcv.c
@@ -141,7 +141,7 @@ static void *test(void *arg, size_t s)
   /* <design/poolmrg/#test.promise.ut.churn> */
   while (mps_collections(arena) < collectionCOUNT) {
     churn(ap);
-    /* design.mps.poolmrg.test.promise.ut.drop */
+    /* <design/poolmrg/#test.promise.ut.drop> */
     for (i = 0; i < rootCOUNT; ++i) {
       if (root[i] != NULL && state[i] == rootSTATE) {
         if (rnd() % finalizationRATE == 0) {
diff --git a/mps/code/global.c b/mps/code/global.c
index 42dd9b4ae99..679ca4e04e0 100644
--- a/mps/code/global.c
+++ b/mps/code/global.c
@@ -91,7 +91,7 @@ static void arenaDenounce(Arena arena)
   AVERT(Arena, arena);
 
   /* Temporarily give up the arena lock to avoid deadlock, */
-  /* see design.mps.thread-safety.deadlock. */
+  /* see <design/thread-safety/#deadlock>. */
   ArenaLeave(arena);
 
   /* Detach the arena from the global list. */
@@ -599,7 +599,7 @@ Res ArenaFinalize(Arena arena, Ref obj)
 
 /* ArenaDefinalize -- removes one finalization registration of an object
  *
- * See design.mps.finalize.  */
+ * See <design/finalize>.  */
 
 Res ArenaDefinalize(Arena arena, Ref obj)
 {
diff --git a/mps/code/mpm.h b/mps/code/mpm.h
index 7c292da7b0f..d3845e00174 100644
--- a/mps/code/mpm.h
+++ b/mps/code/mpm.h
@@ -152,7 +152,7 @@ extern size_t StringLength(const char *s);
 
 /* Version Determination
  *
- * See <design/version/>-library.  */
+ * See <design/version-library/>.  */
 
 extern char *MPSVersion(void);
 
diff --git a/mps/code/mpmtypes.h b/mps/code/mpmtypes.h
index 55a990438b0..67b2b7886a4 100644
--- a/mps/code/mpmtypes.h
+++ b/mps/code/mpmtypes.h
@@ -252,7 +252,7 @@ typedef void (*FormatPadMethod)(Addr base, Size size);
 typedef Addr (*FormatClassMethod)(Addr object);
 
 
-/* Root*Method -- see <design/root/>-interface */
+/* Root*Method -- see design.mps.root-interface */
 /* .root-methods: These methods must match those defined in the */
 /* MPS C Interface.  (See <code/mps.h#root-methods>.) */
 
diff --git a/mps/code/poolamc.c b/mps/code/poolamc.c
index 08ebe20bccd..14cb1b441d9 100644
--- a/mps/code/poolamc.c
+++ b/mps/code/poolamc.c
@@ -1408,7 +1408,7 @@ Res AMCFix(Pool pool, ScanState ss, Seg seg, Ref *refIO)
   EVENT_0(AMCFix);
 
   /* For the moment, assume that the object was already marked. */
-  /* (See design.mps.fix.protocol.was-marked.) */
+  /* (See <design/fix/#protocol.was-marked>.) */
   ss->wasMarked = TRUE;
 
   /* If the reference is ambiguous, set up the datastructures for */
@@ -1467,7 +1467,7 @@ Res AMCFix(Pool pool, ScanState ss, Seg seg, Ref *refIO)
     /* object is not preserved yet (neither moved, nor nailed) */
     /* so should be preserved by forwarding */
     EVENT_A(AMCFixForward, newRef);
-    /* design.mps.fix.protocol.was-marked */
+    /* <design/fix/#protocol.was-marked> */
     ss->wasMarked = FALSE;
 
     /* Get the forwarding buffer from the object's generation. */
@@ -1555,7 +1555,7 @@ static Res AMCHeaderFix(Pool pool, ScanState ss, Seg seg, Ref *refIO)
   EVENT_0(AMCFix);
 
   /* For the moment, assume that the object was already marked. */
-  /* (See design.mps.fix.protocol.was-marked.) */
+  /* (See <design/fix/#protocol.was-marked>.) */
   ss->wasMarked = TRUE;
 
   /* If the reference is ambiguous, set up the datastructures for */
@@ -1613,7 +1613,7 @@ static Res AMCHeaderFix(Pool pool, ScanState ss, Seg seg, Ref *refIO)
     /* object is not preserved yet (neither moved, nor nailed) */
     /* so should be preserved by forwarding */
     EVENT_A(AMCFixForward, newRef);
-    /* design.mps.fix.protocol.was-marked */
+    /* <design/fix/#protocol.was-marked> */
     ss->wasMarked = FALSE;
 
     /* Get the forwarding buffer from the object's generation. */
diff --git a/mps/code/poollo.c b/mps/code/poollo.c
index bb14f82dc32..c5bc67bd44f 100644
--- a/mps/code/poollo.c
+++ b/mps/code/poollo.c
@@ -713,7 +713,7 @@ static Res LOFix(Pool pool, ScanState ss, Seg seg, Ref *refIO)
   loseg = SegLOSeg(seg);
   AVERT_CRITICAL(LOSeg, loseg);
 
-  ss->wasMarked = TRUE;         /* design.mps.fix.protocol.was-marked */
+  ss->wasMarked = TRUE;         /* <design/fix/#protocol.was-marked> */
 
   clientRef = *refIO;
   base = AddrSub((Addr)clientRef, pool->format->headerSize);
@@ -738,7 +738,7 @@ static Res LOFix(Pool pool, ScanState ss, Seg seg, Ref *refIO)
     Size i = AddrOffset(SegBase(seg), base) >> lo->alignShift;
 
     if(!BTGet(loseg->mark, i)) {
-      ss->wasMarked = FALSE;  /* design.mps.fix.protocol.was-marked */
+      ss->wasMarked = FALSE;  /* <design/fix/#protocol.was-marked> */
       if(ss->rank == RankWEAK) {
         *refIO = (Addr)0;
       } else {
diff --git a/mps/code/root.c b/mps/code/root.c
index dde4664cf3a..8ba4104bf7d 100644
--- a/mps/code/root.c
+++ b/mps/code/root.c
@@ -6,7 +6,7 @@
  * .purpose: This is the implementation of the root datatype.
  *
  * .design: For design, see <design/root/> and
- * <design/root/>-interface. */
+ * design.mps.root-interface. */
 
 #include "mpm.h"
 
diff --git a/mps/code/ssfri3.c b/mps/code/ssfri3.c
index baf402aef63..1a40225911b 100644
--- a/mps/code/ssfri3.c
+++ b/mps/code/ssfri3.c
@@ -4,7 +4,7 @@
  * Copyright (c) 2001 Ravenbrook Limited.  See end of file for license.
  *
  *  This scans the stack and fixes the registers which may contain
- *  roots.  See design.mps.thread-manager
+ *  roots.  See <design/thread-manager/>.
  *
  *  The registers edi, esi, ebx are the registers defined to be preserved
  *  across function calls and therefore may contain roots.
diff --git a/mps/code/sslii3.c b/mps/code/sslii3.c
index 549287e5a45..565872c1ab6 100644
--- a/mps/code/sslii3.c
+++ b/mps/code/sslii3.c
@@ -4,7 +4,7 @@
  * Copyright (c) 2001 Ravenbrook Limited.  See end of file for license.
  *
  *  This scans the stack and fixes the registers which may contain
- *  roots.  See design.mps.thread-manager
+ *  roots.  See <design/thread-manager/>
  *
  *  The registers edi, esi, ebx are the registers defined to be preserved
  *  across function calls and therefore may contain roots.
diff --git a/mps/code/sssos8.s b/mps/code/sssos8.s
index f4f405df1aa..047e2d94e38 100644
--- a/mps/code/sssos8.s
+++ b/mps/code/sssos8.s
@@ -5,7 +5,7 @@
 !  Copyright (c) 2001 Ravenbrook Limited.  See end of file for license.
 !
 !  This scans the stack and the preserved integer registers.
-!  See design.mps.thread-manager
+!  See <design/thread-manager/>.
 !
 !  This file is identical to <code/sssus8.s>, except for the
 !  leading underscore convention on C names.  They should be
diff --git a/mps/code/sssus8.c b/mps/code/sssus8.c
index cd5639fb982..0a28bfc6650 100644
--- a/mps/code/sssus8.c
+++ b/mps/code/sssus8.c
@@ -5,7 +5,7 @@
  * Portions copyright (c) 2002 Global Graphics Software.
  *
  * This scans the stack and fixes the registers which may contain
- * roots.  See design.mps.thread-manager.
+ * roots.  See <design/thread-manager/>.
  *
  * .roots: The non-global registers are preserved into the stackframe
  * by the "ta 3" instruction.  This leaves the global registers.
diff --git a/mps/code/sssus8.s b/mps/code/sssus8.s
index 23fd3d333ed..d8ed21fffc7 100644
--- a/mps/code/sssus8.s
+++ b/mps/code/sssus8.s
@@ -5,7 +5,7 @@
 !  Copyright (c) 2001 Ravenbrook Limited.  See end of file for license.
 !
 !  This scans the stack and the preserved integer registers.
-!  See design.mps.thread-manager
+!  See <design/thread-manager/>.
 !
 !  This file is identical to <code/sssos8.s>, except for the
 !  leading underscore convention on C names.  They should be
diff --git a/mps/code/ssw3i3.c b/mps/code/ssw3i3.c
index ef76a106fd4..f9b2646b3b6 100644
--- a/mps/code/ssw3i3.c
+++ b/mps/code/ssw3i3.c
@@ -4,7 +4,7 @@
  * Copyright (c) 2001 Ravenbrook Limited.  See end of file for license.
  *
  *  This scans the stack and fixes the registers which may contain
- *  roots.  See design.mps.thread-manager
+ *  roots.  See <design/thread-manager/>.
  *
  *  The registers edi, esi, ebx are the registers defined to be preserved
  *  across function calls and therefore may contain roots.
diff --git a/mps/code/th.h b/mps/code/th.h
index 37c182a9416..30a2205a356 100644
--- a/mps/code/th.h
+++ b/mps/code/th.h
@@ -4,7 +4,7 @@
  *  Copyright (c) 2001 Ravenbrook Limited.  See end of file for license.
  *
  *  .purpose: Provides thread suspension facilities to the shield.
- *  See design.mps.thread-manager.  Each thread has to be
+ *  See <design/thread-manager/>.  Each thread has to be
  *  individually registered and deregistered with an arena.
  */
 
diff --git a/mps/code/than.c b/mps/code/than.c
index 2cae435fd05..96553c7cd75 100644
--- a/mps/code/than.c
+++ b/mps/code/than.c
@@ -5,7 +5,7 @@
  *
  *  This is a single-threaded implementation of the threads manager.
  *  Has stubs for thread suspension.
- *  See design.mps.thread-manager.
+ *  See <design/thread-manager/>.
  *
  *  .single: We only expect at most one thread on the ring.
  *
diff --git a/mps/code/thfri4.c b/mps/code/thfri4.c
index 0f56e7108e8..5c3d70e16c4 100644
--- a/mps/code/thfri4.c
+++ b/mps/code/thfri4.c
@@ -6,7 +6,7 @@
  * .purpose: This is a pthreads implementation of the threads manager.
  * This implements <code/th.h>.
  *
- * .design: See design.mps.thread-manager.
+ * .design: See <design/thread-manager/>.
  *
  * .thread.id: The thread id is used to identify the current thread.
  *
diff --git a/mps/code/thlii4.c b/mps/code/thlii4.c
index 54e05539f60..fbd376c6352 100644
--- a/mps/code/thlii4.c
+++ b/mps/code/thlii4.c
@@ -6,7 +6,7 @@
  * .purpose: This is a pthreads implementation of the threads manager.
  * This implements <code/th.h>.
  *
- * .design: See design.mps.thread-manager.
+ * .design: See <design/thread-manager/>.
  *
  * .thread.id: The thread id is used to identify the current thread.
  *
diff --git a/mps/code/thw3i3.c b/mps/code/thw3i3.c
index ebb17783b62..873f2b4643e 100644
--- a/mps/code/thw3i3.c
+++ b/mps/code/thw3i3.c
@@ -4,7 +4,7 @@
  * Copyright (c) 2001 Ravenbrook Limited.  See end of file for license.
  *
  * Implements thread registration, suspension, and stack
- * scanning.  See design.mps.thread-manager
+ * scanning.  See <design/thread-manager/>.
  *
  * This supports the <code/th.h>
  *
diff --git a/mps/code/tract.h b/mps/code/tract.h
index 983c79cff60..c6ac2ae3bc8 100644
--- a/mps/code/tract.h
+++ b/mps/code/tract.h
@@ -249,7 +249,7 @@ extern Bool TractNext(Tract *tractReturn, Arena arena, Addr addr);
 
 /* TRACT_TRACT_FOR -- iterate over a range of tracts
  *
- * See <design/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.
  */