From ab17dc9dfd1ffa2b8577ab70bfe5f9a607cd5a5c Mon Sep 17 00:00:00 2001 From: Gareth Rees Date: Thu, 30 May 2013 17:31:42 +0100 Subject: [PATCH] Use restructuretext citations for references in design documents. Copied from Perforce Change: 182334 ServerID: perforce.ravenbrook.com --- mps/design/config.txt | 26 ++++++-------------------- mps/design/critical-path.txt | 3 +-- mps/design/diag.txt | 11 +++-------- mps/design/keyword-arguments.txt | 8 ++------ mps/design/pthreadext.txt | 18 ++++-------------- mps/design/shield.txt | 15 ++++----------- mps/design/sig.txt | 13 ++++--------- mps/design/sso1al.txt | 12 ++++-------- mps/design/trace.txt | 8 +++----- 9 files changed, 31 insertions(+), 83 deletions(-) diff --git a/mps/design/config.txt b/mps/design/config.txt index 38cca8f1bb7..3ca705fc09e 100644 --- a/mps/design/config.txt +++ b/mps/design/config.txt @@ -55,7 +55,7 @@ we can build variants of the MPS for use in different products. This requirement has been retired on 2012-09-03 as part of work on the variety-reform_ branch. Client-specific customisation of the MPS will be handled in source control, while the MPS source remains generic, to -reduce costs and increase reliability. See `[RB 2012-09-13]`_. +reduce costs and increase reliability. See [RB_2012-09-13]_. @@ -162,7 +162,7 @@ upper case. Currently (2012-09-03): _`.var.hot`: ``HOT`` Intended for release in products. Optimised, reduced internal - checking, especially on the critical path `[RB 2012-09-07]`_. + checking, especially on the critical path [RB_2012-09-07]_. _`.var.cool`: ``COOL`` @@ -532,27 +532,13 @@ To document References ---------- -* .. _[MPS Manual]: +.. [MPS_Manual] Ravenbrook Limited. "`Memory Pool System documentation `_". - Ravenbrook Limited. "`Memory Pool System documentation - `_". +.. [RB_2012-09-13] Richard Brooksby. Ravenbrook Limited. 2012-09-13. "`The Configura CET custom mainline `_". -* .. _[RB 2012-09-13]: +.. [PP_2005-03-01] Pekka P. Pirinen. Global Graphics. "`MPS platforms `_". - Richard Brooksby. Ravenbrook Limited. 2012-09-13. "`The Configura - CET custom mainline - `_". - -* .. _[PP 2005-03-01]: - - Pekka P. Pirinen. Global Graphics. "`MPS platforms - `_". - -* .. _[RB 2012-09-07]: - - Richard Brooksby. Ravenbrook Limited. 2012-09-07. "`The critical - path through the MPS - `_". +.. [RB_2012-09-07] Richard Brooksby. Ravenbrook Limited. 2012-09-07. "`The critical path through the MPS `_". .. _variety-reform: http://www.ravenbrook.com/project/mps/branch/2012-08-15/variety-reform/ diff --git a/mps/design/critical-path.txt b/mps/design/critical-path.txt index 2329ff6dca8..c195ee4e07b 100644 --- a/mps/design/critical-path.txt +++ b/mps/design/critical-path.txt @@ -346,9 +346,8 @@ And we write long documents about it. References ---------- -* .. _[MMRef]: - "`The Memory Management Reference `_". +.. [MMRef] "`The Memory Management Reference `_". .. _scanning: http://www.memorymanagement.org/glossary/s.html#scan .. _marking: http://www.memorymanagement.org/glossary/m.html#marking diff --git a/mps/design/diag.txt b/mps/design/diag.txt index 5aeb79160c7..0f3a84aeebe 100644 --- a/mps/design/diag.txt +++ b/mps/design/diag.txt @@ -17,8 +17,7 @@ Introduction _`.intro`: This document describes how to use the diagnostic feedback mechanism in the Memory Pool System. -_`.sources`: Initially abased on `[RHSK 2007-04-13]`_ and `[RHSK -2007-04-18]`_. +_`.sources`: Initially abased on [RHSK_2007-04-13]_ and [RHSK_2007-04-18]_. Overview @@ -284,13 +283,9 @@ systems: References ---------- -.. _[RHSK 2007-04-13]: +.. [RHSK_2007-04-13] Richard Kistruck. 2007-04-13. "`diagnostic feedback from the MPS `_". - Richard Kistruck. 2007-04-13. "`diagnostic feedback from the MPS `_". - -.. _[RHSK 2007-04-18]: - - Richard Kistruck. 2007-04-18. "`Diverse types of diagnostic feedback `_". +.. [RHSK_2007-04-18] Richard Kistruck. 2007-04-18. "`Diverse types of diagnostic feedback `_". Document History diff --git a/mps/design/keyword-arguments.txt b/mps/design/keyword-arguments.txt index a8e3855aae5..7783bdba444 100644 --- a/mps/design/keyword-arguments.txt +++ b/mps/design/keyword-arguments.txt @@ -143,16 +143,12 @@ methods can be deleted at some point in the future. References ---------- -* .. _[RB 2012-05-24]: - - Richard Brooksby. 2012-05-24. "`Keyword and optional arguments - `_" - (e-mail). Ravenbrook Limited. +.. [RB_2012-05-24] Richard Brooksby. 2012-05-24. "`Keyword and optional arguments `_" (e-mail). Ravenbrook Limited. Document History ---------------- -- 2013-05-09 RB_ Created based on [RB 2012-05-24]. +- 2013-05-09 RB_ Created based on [RB_2012-05-24]_. .. _RB: http://www.ravenbrook.com/consultants/rb/ diff --git a/mps/design/pthreadext.txt b/mps/design/pthreadext.txt index 56f26a05dc5..81744aeabc2 100644 --- a/mps/design/pthreadext.txt +++ b/mps/design/pthreadext.txt @@ -103,8 +103,8 @@ One of the few such functions related to synchronization is _`.anal.signal.example`: An example of how to suspend threads in POSIX was posted to newsgroup comp.programming.threads in August 1999 -`[Lau 1999-08-16]`_. The code in the post was written by David Butenhof, who -contributed some comments on his implementation `[Butenhof 1999-08-16]`_ +[Lau_1999-08-16]_. The code in the post was written by David Butenhof, who +contributed some comments on his implementation [Butenhof_1999-08-16]_ _`.anal.signal.linux-hack`: In the current implementation of Linux Pthreads, it would be possible to implement suspend/resume using @@ -337,19 +337,9 @@ Attachments References ---------- -* .. _[Butenhof 1999-08-16]: +.. [Butenhof_1999-08-16] Dave Butenhof. 1999-08-16. "`Re: Problem with Suspend & Resume Thread Example `_". comp.programming.threads. - Dave Butenhof. 1999-08-16. "`Re: Problem with Suspend & Resume - Thread Example - `_". - comp.programming.threads. - -* .. _[Lau 1999-08-16]: - - Raymond Lau. 1999-08-16. "`Problem with Suspend & Resume Thread - Example - `_". - comp.programming.threads. +.. [Lau_1999-08-16] Raymond Lau. 1999-08-16. "`Problem with Suspend & Resume Thread Example `_". comp.programming.threads. Document History diff --git a/mps/design/shield.txt b/mps/design/shield.txt index b82d446306d..8d19066b617 100644 --- a/mps/design/shield.txt +++ b/mps/design/shield.txt @@ -153,23 +153,16 @@ call in collector code, or an entry in the shield cache. Initial ideas ------------- -_`.ideas`: There never was an initial design document, but `[RB -1995-11-29]`_ and `[RB 1995-11-30]`_ contain some initial ideas. +_`.ideas`: There never was an initial design document, but +[RB_1995-11-29]_ and [RB_1995-11-30]_ contain some initial ideas. References ---------- -* .. _[RB 1995-11-29]: +.. [RB_1995-11-29] Richard Brooksby. 1995-11-29. "`Shield protocol for barriers `_". Harlequin. - Richard Brooksby. 1995-11-29. "`Shield protocol for barriers - `_". - Harlequin. - -* .. _[RB 1995-11-30]: - - Richard Brooksby. 1995-11-30. "`Exegesis of Incremental Tracing - `_". Harlequin. +.. [RB_1995-11-30] Richard Brooksby. 1995-11-30. "`Exegesis of Incremental Tracing `_". Harlequin. Document History diff --git a/mps/design/sig.txt b/mps/design/sig.txt index 28e6b53e340..95f7e73362b 100644 --- a/mps/design/sig.txt +++ b/mps/design/sig.txt @@ -29,7 +29,7 @@ they are created and invalidated (by overwriting with ``SigInvalid``) when they are destroyed. They provide a limited form of run-time type checking and dynamic scope checking. They are a simplified form of "Structure Marking", a technique used in the Multics filesystem -`[THVV 1995]`_. +[THVV_1995]_. Definitions @@ -144,20 +144,15 @@ undesirable and the problem should be investigated. References ---------- -* .. _[RB 1995-08-25]: - Richard Brooksby. Harlequin. 1995-08-25. "design.mps.sig: The design - of the Memory Pool System Signature System". +.. [RB_1995-08-25] Richard Brooksby. Harlequin. 1995-08-25. "design.mps.sig: The design of the Memory Pool System Signature System". -* .. _[THVV 1995]: - - Tom Van Vleck. 1995. "`Structure Marking - `_". +.. [THVV_1995] Tom Van Vleck. 1995. "`Structure Marking `_". Document History ---------------- -- 2013-05-09 RB_ Created based on scanty MM document `[RB 1995-08-25]`_. +- 2013-05-09 RB_ Created based on scanty MM document [RB_1995-08-25]_. .. _RB: http://www.ravenbrook.com/consultants/rb/ diff --git a/mps/design/sso1al.txt b/mps/design/sso1al.txt index a3ea82445f4..3f31cc240ad 100644 --- a/mps/design/sso1al.txt +++ b/mps/design/sso1al.txt @@ -31,11 +31,11 @@ describes the Alpha Architecture independently of any particular implementation. The instruction mnemonics and the semantics for each instruction are specified in that document. -`[DEC Assembler]`_ describes the assembler syntax and assembler +[DEC_Assembler]_ describes the assembler syntax and assembler directives. It also summarises the calling conventions used. Chapters 1 and 6 were especially useful, especially chapter 6. -`[DEC Alpha Calling Standard]`_ describes the calling conventions used +[DEC_Alpha_Calling_Standard]_ describes the calling conventions used for Digital Alpha systems. Chapter 2 was useful. But the whole document was not used as much as the previous 2 documents. @@ -123,13 +123,9 @@ _`.fun.stackscan.return`: The return value from References ---------- -.. _[DEC Assembler]: +.. [DEC_Assembler] Digital Equipment Corporation. 1996. "`Assembly Language Programmer's Guide `_". - Digital Equipment Corporation. 1996. "`Assembly Language Programmer's Guide `_". - -.. _[DEC Alpha Calling Standard]: - - Digital Equipment Corporation. 1996. "`Calling Standard for Alpha Systems `_". +.. [DEC_Alpha_Calling_Standard] Digital Equipment Corporation. 1996. "`Calling Standard for Alpha Systems `_". Document History diff --git a/mps/design/trace.txt b/mps/design/trace.txt index 576deee9f47..256b7114c37 100644 --- a/mps/design/trace.txt +++ b/mps/design/trace.txt @@ -207,7 +207,7 @@ all subsequent objects it can reach by following references of the second and first ranks. The third band is all subsequent objects it can reach by following references of the third, second, and first ranks. And so on. The description of the tracer working like this -originated in `[RHSK 2007-06-25]`_. +originated in [RHSK_2007-06-25]_. A trace keep track of which band it is tracing. This is returned by the ``TraceBand()`` method. Keeping this band information helps it @@ -215,7 +215,7 @@ implement the semantics of finalization and weakness. The band used to not be explicitly stored, but this hindered the implementation of good finalization semantics (essentially in some circumstances finalization messages were delayed by at least one collection cycle, see -`job001658`_. +job001658_. .. _job001658: https://info.ravenbrook.com/project/mps/issue/job001658/ @@ -232,9 +232,7 @@ all the ranks in this fashion there is no more tracing to be done. References ---------- -* .. _[RHSK 2007-06-25]: - - Richard Kistruck. 2007-06-25. "`The semantics of rank-based tracing `_". +.. [RHSK_2007-06-25] Richard Kistruck. 2007-06-25. "`The semantics of rank-based tracing `_". Document History