Re: document symbols
Russ Allbery wrote:
> Okay, once more for the win.
Hoorah! :) I don't see any problems in the normative content, so I'd
second this if I could. Cosmetic nits (patch below):
[...]
> +++ b/policy.sgml
[...]
> @@ -5633,17 +5634,29 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1)
[...]
> <p>
> + To determine the <var>soversion</var>, look at
> + the <tt>SONAME</tt> of the library, stored in the
> + ELF <tt>SONAME</tt> attribute. it is usually of the
^^
Capitalization: s/it/It/
[...]
> + A common example of when a change to the is required is a
^^^^^^^^^
Missing word: s/to the/to the dependency version/. (In a previous
version of the patch, this passage was discussing symbols files only
and said <var>minimal-version</var>.)
[...]
> + no symbol version. <var>minimal-version</var> is the most
> + recent version of the shared library that changed the
> + behavior of that symbol, whether by adding it, changing its
~~~~~~ ~~~~~~~~
> + function signature (the parameters, their types, or the
> + return type), or its behavior in a way that is visible to a
~~~~~~~~~~~~~~~
> + caller. <var>id-of-dependency-template</var> is an optional
Maintaining parallel construction: s/its behavior/changing its
behavior/.
[...]
> + In our example, if the last change to the <tt>zlib1g</tt>
> + package that could change behavior for a client of that
> + library was in version <tt>1:1.2.3.3.dfsg-1</tt>, then
> + the <tt>shlibs</tt> entry for this library could say:
> + <example compact="compact">
> + libz 1 zlib1g (>= 1:1.2.3.3.dfsg-1)
> + </example>
Should this say (>= 1:1.2.3.3.dfsg-1~) or (>= 1:1.2.3.3.dfsg) to be
kind to backporters? Before the patch, the example said ">= 1:1.1.3".
-- >8 --
Subject: symbols/shlibs policy: cosmetic fixes
Use "zlib1g (>= 1:1.2.3.3.dfsg-2~)" in the sample shlibs dependency
field to emphasize the backport-friendly convention described in the
sharedlibs-updates section.
Also correct two small typos --- one sentence is uncapitalized and
another missing a noun --- and rephrase a sentence that describes when
to bump the dependency-version to make it easier to read.
---
diff --git a/policy.sgml b/policy.sgml
index fa1c39a..050c688 100644
--- a/policy.sgml
+++ b/policy.sgml
@@ -5646,7 +5646,7 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1)
<p>
To determine the <var>soversion</var>, look at
the <tt>SONAME</tt> of the library, stored in the
- ELF <tt>SONAME</tt> attribute. it is usually of the
+ ELF <tt>SONAME</tt> attribute. It is usually of the
form <tt><var>name</var>.so.<var>major-version</var></tt> (for
example, <tt>libz.so.1</tt>). The version part is the part
which comes after <tt>.so.</tt>, so in that example it
@@ -6238,9 +6238,9 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1)
</p>
<p>
- A common example of when a change to the is required is a
- function that takes an enum or struct argument that controls
- what the function does. For example:
+ A common example of when a change to the dependency version
+ is required is a function that takes an enum or struct
+ argument that controls what the function does. For example:
<example>
enum library_op { OP_FOO, OP_BAR };
int library_do_operation(enum library_op);
@@ -6489,8 +6489,9 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1)
recent version of the shared library that changed the
behavior of that symbol, whether by adding it, changing its
function signature (the parameters, their types, or the
- return type), or its behavior in a way that is visible to a
- caller. <var>id-of-dependency-template</var> is an optional
+ return type), or changing its behavior in a way that is
+ visible to a caller.
+ <var>id-of-dependency-template</var> is an optional
field that references
an <var>alternative-dependency-template</var>; see below for
a full description.
@@ -6795,10 +6796,10 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1)
<p>
In our example, if the last change to the <tt>zlib1g</tt>
package that could change behavior for a client of that
- library was in version <tt>1:1.2.3.3.dfsg-1</tt>, then
+ library was in version <tt>1:1.2.3.3.dfsg-2</tt>, then
the <tt>shlibs</tt> entry for this library could say:
<example compact="compact">
- libz 1 zlib1g (>= 1:1.2.3.3.dfsg-1)
+ libz 1 zlib1g (>= 1:1.2.3.3.dfsg-2~)
</example>
This version restriction must be new enough that any binary
built against the current version of the library will work
@@ -6810,7 +6811,7 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1)
As zlib1g also provides a udeb containing the shared
library, there would also be a second line:
<example compact="compact">
- udeb: libz 1 zlib1g-udeb (>= 1:1.2.3.3.dfsg-1)
+ udeb: libz 1 zlib1g-udeb (>= 1:1.2.3.3.dfsg-2~)
</example>
</p>
</sect2>
Reply to: