On 05/16/11 09:31 PM, bugmail-sen...@sun.com wrote:
> *Synopsis*: usr/share/doc/ksh/shell_styleguide.html has sporadic wsdiff
> changes
>
> CR 6914752 changed on May 17 2011 by <User 1-5Q-6276>
>
> === Field ============ === New Value ============= === Old Value =============
>
> Fixed in Build xx xx
> Status 8-Fix Available 7-Fix in Progress
> ====================== =========================== ===========================
http://journal.dedasys.com/2009/09/07/stopping-docbook-version-control-churn
discusses the root cause of this:
"The problem is that generate-id, at least in xsltproc, uses a fairly random
bit of data (memory location) to create the id."
The "sporadic" part is thus likely when a compiler version or flag change makes
the generated code a different size, or when the code of one of the libraries
is modified, thus resulting in slightly different memory addresses. If
we had address space layout randomization, it would be much worse for wsdiff.
While the above blog post gives an xsl snippet that can make the auto-generated
id's stable, since this is just one document I went with the simpler and lower
risk fix of just ensuring all tags that it was generating an id attribute for
got a manually assigned id instead - see the attached patch for details.
As a free bonus, this makes the sparc & x86 builds produce identical output,
which they didn't before, since sparc & x86 memory layouts are different.
IPS can then unify to a single copy when pkgmerging the sparc & x86 packages,
as well as share the same copy across many more builds in the package repos,
since they'll all have the same content hash now.
--
-<User 1-5Q-1267>- alan.coopersm...@oracle.com
Oracle Solaris Platform Engineering: X Window System
# HG changeset patch
# User Alan Coopersmith <alan.coopersm...@oracle.com>
# Date 1305564628 25200
# Node ID 1d68046627793732fb1f8d2b8dffbb3c4a9c0d9f
# Parent f60dee1e71fb8e51436653473eb7f53bd0c7ccfd
6914752 usr/share/doc/ksh/shell_styleguide.html has sporadic wsdiff changes
diff --git a/usr/src/lib/libshell/misc/shell_styleguide.docbook
b/usr/src/lib/libshell/misc/shell_styleguide.docbook
--- a/usr/src/lib/libshell/misc/shell_styleguide.docbook
+++ b/usr/src/lib/libshell/misc/shell_styleguide.docbook
@@ -33,8 +33,7 @@
<!--
- Copyright 2009 Sun Microsystems, Inc. All rights reserved.
- Use is subject to license terms.
+ Copyright (c) 2009, 2011, Oracle and/or its affiliates. All rights reserved.
-->
@@ -55,7 +54,18 @@
−−xinclude -o opensolaris_shell_styleguide.html
/usr/share/sgml/docbook/docbook-xsl-stylesheets-1.69.1/html/docbook.xsl
opensolaris_shell_styleguide.docbook
-->
+<!-- When changing this document, please ensure that all tags which get
+ generated with id attributes have xml:id attributes set in this source,
+ so they do not get automatically generated id attributes. Check the
+ output for id="id[0-9]*" style attributes. When xsltproc generates
+ those, they are based on the memory address when processing the
+ document, so will differ per-platform, and change (showing as wsdiff
+ changes) when the memory layout changes due to code size changes or
+ other differences that should not change the content of the document.
+-->
+
<article
+ xml:id="shell_styleguide"
xmlns:xlink="http://www.w3.org/1999/xlink";
xmlns="http://docbook.org/ns/docbook";
xml:lang="en">
@@ -508,7 +518,7 @@
<section xml:id="set_locale_when_comparing_against_localised_output">
<title>Set the message locale if you process output of tools which
may be localised</title>
<para>Set the message locale (<envar>LC_MESSAGES</envar>) if you
process output of tools which may be localised</para>
- <example><title>Set <envar>LC_MESSAGES</envar> when testing for
specific outout of the <filename>/usr/bin/file</filename> utility:</title>
+ <example xml:id="example_set_LC_MESSAGES"><title>Set
<envar>LC_MESSAGES</envar> when testing for specific outout of the
<filename>/usr/bin/file</filename> utility:</title>
<programlisting>
# set french as default message locale
export LC_MESSAGES=fr_FR.UTF-8
@@ -949,7 +959,7 @@
member separated by the first character of the
<envar>IFS</envar> variable, and "${mylist[@]}"
expands each element of name to a separate string.
</para>
- <example><title>Difference between [@] and [*] when expanding
arrays</title>
+ <example xml:id="example_expanding_arrays"><title>Difference
between [@] and [*] when expanding arrays</title>
<programlisting>
typeset -a mylist
mylist+=( "/etc/foo" )
@@ -1105,7 +1115,7 @@
integer variable rather than specifying a fixed descriptor
number.</para>
<para>This is highly recommended in functions to avoid that fixed
file
descriptor numbers interfere with the calling script.</para>
-<example><title>Open a network connection and store the file descriptor number
in a variable</title>
+<example xml:id="example_file_descriptor"><title>Open a network connection and
store the file descriptor number in a variable</title>
<programlisting>
function cat_http
{
@@ -1166,7 +1176,7 @@
<para>Print compound variables using <literal>print -C
varname</literal> or
<literal>print -v varname</literal> to make sure that non-printable
characters
are correctly encoded.</para>
-<example><title>Print compound variable with non-printable characters</title>
+<example xml:id="example_print_compound_variables"><title>Print compound
variable with non-printable characters</title>
<programlisting>
compound x=(
a=5
@@ -1210,7 +1220,7 @@
<para>Enable the <literal>gmacs</literal>editor mode before reading
user
input using the <literal>read</literal> builtin to enable the use of
cursor+backspace+delete keys in the edit line</para>
-<example><title>Prompt user for a string with gmacs editor mode enabled</title>
+<example xml:id="example_prompt_user_with_gmacs"><title>Prompt user for a
string with gmacs editor mode enabled</title>
<programlisting>
set -o gmacs <co xml:id="co.enable_gmacs" />
typeset inputstring="default value"
@@ -1345,7 +1355,7 @@
<para>Avoid string to number and/or number to string conversions in
arithmetic expressions expressions to avoid performance degradation
and rounding errors.</para>
- <example><title>(( x=$x*2 )) vs. (( x=x*2 ))</title>
+ <example xml:id="example_string_number_conversions"><title>(( x=$x*2
)) vs. (( x=x*2 ))</title>
<programlisting>
float x
...
@@ -1373,7 +1383,7 @@
</example>
- <example><title>x=$(( y+5.5 )) vs. (( x=y+5.5 ))</title>
+ <example xml:id="example_more_string_number_conversions"><title>x=$((
y+5.5 )) vs. (( x=y+5.5 ))</title>
<programlisting>
float x
float y=7.1
_______________________________________________
ksh93-integration-discuss mailing list
ksh93-integration-discuss@opensolaris.org
http://mail.opensolaris.org/mailman/listinfo/ksh93-integration-discuss
