From f2baf0cfeb36f0aa56f2c97f27a93d2c20ad3fec Mon Sep 17 00:00:00 2001 From: Gareth Rees Date: Sun, 28 Oct 2012 19:47:20 +0000 Subject: [PATCH] New "deprecated" directive allows following paragraphs recommending what to use instead. Copied from Perforce Change: 180122 ServerID: perforce.ravenbrook.com --- mps/manual/source/extensions/mps.py | 53 ++++--------------- mps/manual/source/themes/mps/static/mps.css_t | 4 ++ mps/manual/source/todo.rst | 10 ++-- mps/manual/source/topic/arena.rst | 6 +-- mps/manual/source/topic/interface.rst | 25 ++++----- mps/manual/source/topic/scanning.rst | 4 +- 6 files changed, 37 insertions(+), 65 deletions(-) diff --git a/mps/manual/source/extensions/mps.py b/mps/manual/source/extensions/mps.py index e432321a4d7..e69111e1ddd 100644 --- a/mps/manual/source/extensions/mps.py +++ b/mps/manual/source/extensions/mps.py @@ -19,45 +19,6 @@ class MpsDomain(Domain): label = 'MPS' name = 'mps' -class deprecated(addnodes.versionmodified): - pass - -class DeprecatedDirective(VersionChange): - # Copied from VersionChange: can't be subclassed because of the - # need to make a deprecated node rather than a versionmodified - # node. - def run(self): - node = deprecated() - node.document = self.state.document - set_source_info(self, node) - node['type'] = self.name - node['version'] = self.arguments[0] - if len(self.arguments) == 2: - inodes, messages = self.state.inline_text(self.arguments[1], - self.lineno+1) - node.extend(inodes) - if self.content: - self.state.nested_parse(self.content, self.content_offset, node) - ret = [node] + messages - else: - ret = [node] - env = self.state.document.settings.env - # XXX should record node.source as well - env.note_versionchange(node['type'], node['version'], node, node.line) - return ret - -def version_compare(*args): - return cmp(*[map(int, v.split('.')) for v in args]) - -def visit_deprecated_node(self, node): - if (node['type'] == 'deprecated' - and version_compare(node['version'], self.builder.config.version) >= 0): - node['type'] = 'deprecatedstarting' - self.visit_versionmodified(node) - -def depart_deprecated_node(self, node): - self.depart_versionmodified(node) - class Admonition(nodes.Admonition, nodes.Element): pass @@ -104,6 +65,13 @@ class BibrefDirective(PluralDirective): label = 'Related publication' plural = 'Related publications' +class deprecated(Admonition): + pass + +class DeprecatedDirective(AdmonitionDirective): + cls = deprecated + label = 'Deprecated' + class historical(Admonition): pass @@ -188,6 +156,7 @@ class TopicsDirective(PluralDirective): all_admonitions = [ AkaDirective, BibrefDirective, + DeprecatedDirective, HistoricalDirective, LinkDirective, NoteDirective, @@ -241,7 +210,7 @@ def warn_indirect_terms(app, exception): if not exception: for i in see_only_ids: for doc, line in xref_ids[i]: - print('Cross-reference to {} at {} line {}.'.format(i, doc, line)) + print('Warning: cross-reference to {} at {} line {}.'.format(i, doc, line)) def setup(app): app.add_domain(MpsDomain) @@ -255,7 +224,3 @@ def setup(app): app.add_directive_to_domain(d.domain, d.cls.__name__, d) except AttributeError: app.add_directive(d.cls.__name__, d) - - visit = (visit_deprecated_node, depart_deprecated_node) - app.add_node(deprecated, html = visit, latex = visit, text = visit) - app.add_directive('deprecated', DeprecatedDirective) diff --git a/mps/manual/source/themes/mps/static/mps.css_t b/mps/manual/source/themes/mps/static/mps.css_t index 48762d0a7d8..5620ccb4218 100644 --- a/mps/manual/source/themes/mps/static/mps.css_t +++ b/mps/manual/source/themes/mps/static/mps.css_t @@ -95,6 +95,10 @@ div.admonition p.admonition-title + p + p { margin-top: 1em; } +div.admonition-deprecated { + border: 2px solid {{ theme_relbarbgcolor }}; +} + .xref.std-term { font-style: normal; color: {{ theme_textcolor }}; diff --git a/mps/manual/source/todo.rst b/mps/manual/source/todo.rst index e9d4da473e9..fe68f7d3fb3 100644 --- a/mps/manual/source/todo.rst +++ b/mps/manual/source/todo.rst @@ -52,10 +52,6 @@ Outstanding 95. Bring :ref:`lang` up to date. Add C#, Lua, Python. -115. Need to associate paragraph of text with deprecation notice. (See - for example :c:func:`mps_fix`.) Also, deprecation notices need - nicer formatting. - Complete -------- @@ -916,6 +912,10 @@ Complete exploit this pattern. Perhaps in use in ScriptWorks? Write to Pekka and ask him how this has worked out. (After 1.111.0.) +115. Need to associate paragraph of text with deprecation notice. (See + for example :c:func:`mps_fix`.) Also, deprecation notices need + nicer formatting. + 116. "The maximum number of arenas that the system can support is around 10." Is this true? What goes wrong? (I tried creating lots of arenas and nothing seemed to go wrong.) @@ -923,7 +923,7 @@ Complete *Answer:* this was probably a finger in the air. Remove it. 117. Consistent pluralization in headings. "Arena states". "Other - notes" -> "Ambiguous references". "You could use this to optimize + notes" → "Ambiguous references". "You could use this to optimize the scan by avoiding the need to reassemble and store the updated reference after calling :c:func:`MPS_FIX2`. diff --git a/mps/manual/source/topic/arena.rst b/mps/manual/source/topic/arena.rst index 2065c7956d7..c3d52806598 100644 --- a/mps/manual/source/topic/arena.rst +++ b/mps/manual/source/topic/arena.rst @@ -701,7 +701,7 @@ Protection interface .. c:function:: void mps_arena_expose(mps_arena_t arena) - .. deprecated:: 1.111 + .. deprecated:: starting with version 1.111. Ensure that the MPS is not protecting any :term:`page` in the :term:`arena` with a :term:`read barrier` or :term:`write @@ -735,7 +735,7 @@ Protection interface .. c:function:: void mps_arena_unsafe_expose_remember_protection(mps_arena_t arena) - .. deprecated:: 1.111 + .. deprecated:: starting with 1.111. Ensure that the MPS is not protecting any :term:`page` in the :term:`arena` with a :term:`read barrier` or :term:`write @@ -772,7 +772,7 @@ Protection interface .. c:function:: void mps_arena_unsafe_restore_protection(mps_arena_t arena) - .. deprecated:: 1.111 + .. deprecated:: starting with 1.111. Restore the remembered protection state for an :term:`arena`. diff --git a/mps/manual/source/topic/interface.rst b/mps/manual/source/topic/interface.rst index 44afb31937e..0d81c41a1f5 100644 --- a/mps/manual/source/topic/interface.rst +++ b/mps/manual/source/topic/interface.rst @@ -94,17 +94,17 @@ Identifiers Types ----- -1. There are three kinds of types declared in the MPS interface: - *transparent types*, *opaque types*, and *derived types*. See below. +There are three kinds of types declared in the MPS interface: +*transparent types*, *opaque types*, and *derived types*. See below. -2. A *transparent type* is an alias defined using ``typedef``, and this +1. A *transparent type* is an alias defined using ``typedef``, and this is documented so that the :term:`client program` can rely on that fact. For example, :c:type:`mps_addr_t` is a transparent alias for ``void *``. Transparent types express intentions in the interface: in the case of :c:type:`mps_addr_t` it represents a pointer that is under the control of the MPS. -3. An *opaque type* is a pointer to an incomplete structure type. The +2. An *opaque type* is a pointer to an incomplete structure type. The client program must not rely on details of its implementation. For example, the type :c:type:`mps_arena_t` is an alias for ``struct mps_arena_s *``, but the implementation of ``struct mps_arena_s`` @@ -117,7 +117,7 @@ Types scanning macros such as :c:func:`MPS_SCAN_BEGIN` and :c:func:`MPS_FIX12`. -4. A *derived type* is a structure or function type based on +3. A *derived type* is a structure or function type based on transparent and opaque types and on built-in C types. The degree to which you may or must depend upon the implementation of a derived type is covered by the documentation for the type. For @@ -157,18 +157,19 @@ Functions Type punning ------------ -It's tempting to use a type cast to change the type of a in/out or out -parameter, like this:: +It's tempting to use a type cast to change the type of an in/out or +out parameter, like this:: /* allocate a struct foo */ struct foo *fp; res = mps_alloc((mps_addr_t *)&fp, pool, sizeof(struct foo)); -This is known as :term:`type punning`, and its behaviour is undefined -in ANSI/ISO Standard C. (See §6.3.2.3, which defines the conversion of -a pointer from one type to another: the behaviour of this cast is not -covered by any of the cases in the standard.) Instead, we recommend -this approach:: +This is known as :term:`type punning`, and its behaviour is not +defined in ANSI/ISO Standard C. See §6.3.2.3, which defines the +conversion of a pointer from one type to another: the behaviour of +this cast is not covered by any of the cases in the standard. + +Instead, we recommend this approach:: mps_addr_t p; struct foo *fp; diff --git a/mps/manual/source/topic/scanning.rst b/mps/manual/source/topic/scanning.rst index dd25f81fc2d..caf589cedb4 100644 --- a/mps/manual/source/topic/scanning.rst +++ b/mps/manual/source/topic/scanning.rst @@ -456,7 +456,9 @@ Fixing interface .. c:function:: mps_res_t mps_fix(mps_ss_t ss, mps_addr_t *ref_io) - .. deprecated:: 1.111 + .. deprecated:: starting with version 1.111. + + Use :c:func:`MPS_FIX1` and :c:func:`MPS_FIX2` instead. :term:`Fix` a :term:`reference`.