mirrors/emacs
1
Fork 0
mirror of git://git.sv.gnu.org/emacs.git synced 2026-01-07 12:20:39 -08:00
Code Issues Projects Releases Wiki Activity

New "deprecated" directive allows following paragraphs recommending what to use instead.

Browse source 
Copied from Perforce
 Change: 180122
 ServerID: perforce.ravenbrook.com
This commit is contained in:
Gareth Rees 2012-10-28 19:47:20 +00:00
parent 6f01e17f9f
commit f2baf0cfeb
6 changed files with 37 additions and 65 deletions
Download patch file Download diff file Expand all files Collapse all files

53
mps/manual/source/extensions/mps.py
View file

@ -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)

4
mps/manual/source/themes/mps/static/mps.css_t
View file

@ -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 }};

10
mps/manual/source/todo.rst
View file

@ -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`.

6
mps/manual/source/topic/arena.rst
View file

@ -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`.

25
mps/manual/source/topic/interface.rst
View file

@ -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;

4
mps/manual/source/topic/scanning.rst
View file

@ -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`.