Merge branch 'dev' into major

* dev: Improve the generation of man pages Correct XML files
blackberry · Sep 27, 2011 · 67e216c · 67e216c
2 parents 0e132c0 + adeb8ab
commit 67e216c
Show file tree

Hide file tree

Showing 33 changed files with 214 additions and 219 deletions.
diff --git a/erts/doc/src/erl_prim_loader.xml b/erts/doc/src/erl_prim_loader.xml
@@ -101,7 +101,7 @@
           <c><anno>Bin</anno></c> is the contents of the file as a binary.</p>
 
 	  <p>The <c><anno>Filename</anno></c> can also be a file in an archive. For example
-          <c>/otp/root/lib/mnesia-4.4.7.ez/mnesia-4.4.7/ebin/mnesia_backup.beam</c>.
+          <c>$OTPROOT/lib/</c><c>mnesia-4.4.7.ez/mnesia-4.4.7/ebin/</c><c>mnesia.beam</c>.
           See <seealso marker="kernel:code">code(3)</seealso> about archive files.</p>
       </desc>
     </func>
@@ -124,7 +124,7 @@
           the names of all the files in the directory. The names are
           not sorted.</p>
 	  <p>The <c><anno>Dir</anno></c> can also be a directory in an archive. For example
-          <c>/otp/root/lib/mnesia-4.4.7.ez/mnesia-4.4.7/ebin</c>.
+          <c>$OTPROOT/lib/</c><c>mnesia-4.4.7.ez/mnesia-4.4.7/ebin</c>.
            See <seealso marker="kernel:code">code(3)</seealso> about archive files.</p>
       </desc>
     </func>
@@ -143,7 +143,7 @@
         <p>See <seealso marker="kernel:file">file(3)</seealso> for more info about
           the record <c>file_info</c>.</p>
 	<p>The <c><anno>Filename</anno></c> can also be a file in an archive. For example
-          <c>/otp/root/lib/mnesia-4.4.7.ez/mnesia-4.4.7/ebin/mnesia_backup.beam</c>.
+          <c>$OTPROOT/lib/</c><c>mnesia-4.4.7.ez/mnesia-4.4.7/ebin/</c><c>mnesia</c>.
           See <seealso marker="kernel:code">code(3)</seealso> about archive files.</p>
       </desc>
     </func>

diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml
@@ -2909,11 +2909,11 @@ os_prompt%</pre>
 	      <seealso marker="stdlib:unicode_usage">stdlib users guide
 	      </seealso> for details.</p>
 
-	      <note>The characters in the name (if given as a list)
+	      <note><p>The characters in the name (if given as a list)
 	      can only be &gt; 255 if the Erlang VM is started in
 	      Unicode file name translation mode, otherwise the name
 	      of the executable is limited to the ISO-latin-1
-	      character set.</note>
+	      character set.</p></note>
 
 	      <p>If the <c>Command</c> cannot be run, an error
 	      exception, with the posix error code as the reason, is
@@ -3026,11 +3026,11 @@ os_prompt%</pre>
 	    Unicode translation of arguments, they can be supplied as
 	    binaries in whatever encoding is deemed appropriate.</p>
 
-	      <note>The characters in the arguments (if given as a
+	      <note><p>The characters in the arguments (if given as a
 	      list of characters) can only be &gt; 255 if the Erlang
 	      VM is started in Unicode file name mode,
 	      otherwise the arguments are limited to the
-	      ISO-latin-1 character set.</note>
+	      ISO-latin-1 character set.</p></note>
 
 	    <p>If one, for any reason, wants to explicitly set the
 	    program name in the argument vector, the <c>arg0</c>

diff --git a/erts/doc/src/erts_alloc.xml b/erts/doc/src/erts_alloc.xml
@@ -4,7 +4,7 @@
 <cref>
   <header>
     <copyright>
-      <year>2002</year><year>2010</year>
+      <year>2002</year><year>2011</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -126,9 +126,8 @@
       carrier". Main multiblock carriers are never deallocated. The
       size of the main multiblock carrier is determined by the value
       of the <seealso marker="#M_mmbcs">mmbcs</seealso> parameter.</p>
-    <p>      <marker id="mseg_mbc_sizes"></marker>
-
-      Sizes of multiblock carriers allocated via <c>mseg_alloc</c> are
+    <p><marker id="mseg_mbc_sizes"></marker>Sizes of multiblock carriers
+      allocated via <c>mseg_alloc</c> are
       decided based on the values of the largest multiblock carrier
       size (<seealso marker="#M_lmbcs">lmbcs</seealso>), the smallest
       multiblock carrier size (<seealso marker="#M_smbcs">smbcs</seealso>),
@@ -157,9 +156,8 @@
     <p>Coalescing of free blocks are always performed immediately.
       Boundary tags (headers and footers) in free blocks are used
       which makes the time complexity for coalescing constant.</p>
-    <p>      <marker id="strategy"></marker>
-
-      The memory allocation strategy used for multiblock carriers by an
+    <p><marker id="strategy"></marker>The memory allocation strategy
+      used for multiblock carriers by an
       allocator is configurable via the <seealso marker="#M_as">as</seealso>
       parameter. Currently the following strategies are available:</p>
     <taglist>
@@ -445,10 +443,10 @@
        in "the <c>alloc_util</c> framework" section.</item>
       <tag><marker id="M_t"><c><![CDATA[+M<S>t true|false|<amount>]]></c></marker></tag>
       <item>
-       Multiple, thread specific instances of the allocator.
-       This option will only have any effect on the runtime system
-       with SMP support. Default behaviour on the runtime system with
-       SMP support (<c>N</c> equals the number of scheduler threads):
+        <p>Multiple, thread specific instances of the allocator.
+           This option will only have any effect on the runtime system
+           with SMP support. Default behaviour on the runtime system with
+           SMP support (<c>N</c> equals the number of scheduler threads):</p>
        <taglist>
          <tag><c>temp_alloc</c></tag>
 	 <item><c>N + 1</c> instances.</item>
@@ -459,10 +457,10 @@
 	 <c>16</c>. <c>16</c> instances when <c>N</c> is greater than
 	 <c>16</c>.</item>
        </taglist>
-       <c>temp_alloc</c> will always use <c>N + 1</c> instances when
-       this option has been enabled regardless of the amount passed.
-       Other allocators will use the same amount of instances as the
-       amount passed as long as it isn't greater than <c>N</c>.       
+       <p><c>temp_alloc</c> will always use <c>N + 1</c> instances when
+          this option has been enabled regardless of the amount passed.
+          Other allocators will use the same amount of instances as the
+          amount passed as long as it isn't greater than <c>N</c>.</p>
       </item>
     </taglist>
     <p>Currently the following flags are available for configuration of

diff --git a/lib/cosFileTransfer/doc/src/CosFileTransfer_FileTransferSession.xml b/lib/cosFileTransfer/doc/src/CosFileTransfer_FileTransferSession.xml
@@ -159,7 +159,7 @@
     </func>
     <func>
       <name>insert(FTS, SourceFile, DestinationFile, Offset) -> Return</name>
-      <fsummary>Insert the <c>SourceFile</c>into the <c>DestinationFile</c><c>Offset</c>bytes from the start of the file</fsummary>
+      <fsummary>Insert the <c>SourceFile</c>into the <c>DestinationFile</c> <c>Offset</c>bytes from the start of the file</fsummary>
       <type>
         <v>FTS = SourceFile = DestinationFile = #objref</v>
         <v>Offset = long()</v>
@@ -168,7 +168,7 @@
       <desc>
         <p>This operation behaves almost like the <c>append/3</c> operation. The 
           difference is that the <c>SourceFile</c> will be inserted into the
-          <c>DestinationFile</c><c>Offset</c> bytes from the start of the file.</p>
+          <c>DestinationFile</c> <c>Offset</c> bytes from the start of the file.</p>
         <p>Currently, it is not possible to use this operation when the target 
           object represents FTP.</p>
       </desc>

diff --git a/lib/erl_docgen/priv/xsl/db_man.xsl b/lib/erl_docgen/priv/xsl/db_man.xsl
@@ -25,12 +25,12 @@
   xmlns:exsl="http://exslt.org/common"
   extension-element-prefixes="exsl">
 
-  <xsl:preserve-space elements="code pre"/>
+  <xsl:preserve-space elements="code pre p"/>
   <xsl:strip-space elements="*"/>
   <xsl:output method="text" encoding="UTF-8" indent="no"/>
 
   <!-- Start of Dialyzer type/spec tags. See also the templates
-        matching "name" and "seealso"
+        matching "name", "seealso" and "br"
   -->
 
   <!-- Note: specs data for *one* module (as opposed to html and pdf) -->
@@ -137,8 +137,8 @@
          (there is no spec with more than one clause) -->
     <xsl:if test="count($clause/guard) > 0 or count($type) > 0">
       <xsl:text>&#10;.RS</xsl:text>
-      <xsl:text>&#10;.TP</xsl:text>
-      <xsl:text>&#10;Types</xsl:text>
+      <xsl:text>&#10;.TP 3</xsl:text>
+      <xsl:text>&#10;Types:&#10;</xsl:text>
 
         <xsl:choose>
           <xsl:when test="$output_subtypes">
@@ -223,10 +223,13 @@
 
     <xsl:for-each select="$subtype">
       <xsl:variable name="tname" select="typename"/>
-      <xsl:text>&#10;</xsl:text>
-      <xsl:apply-templates select="string"/>
-      <xsl:text>&#10;.br</xsl:text>
-      <xsl:apply-templates select="$type_desc[@variable = $tname]"/>
+      <xsl:variable name="string" select="string"/>
+      <xsl:if test="string-length($string) > 0">
+	<xsl:text>&#10;</xsl:text>
+	<xsl:apply-templates select="$string"/>
+	<xsl:text>&#10;.br</xsl:text>
+	<xsl:apply-templates select="$type_desc[@variable = $tname]"/>
+      </xsl:if>
     </xsl:for-each>
   </xsl:template>
 
@@ -319,8 +322,7 @@
   </xsl:template>
 
   <xsl:template match="typehead">
-    <xsl:text>&#10;.nf&#10;</xsl:text>
-    <xsl:text>&#10;.B&#10;</xsl:text>
+    <xsl:text>&#10;.nf&#10;&#10;</xsl:text>
     <xsl:apply-templates/>
     <xsl:text>&#10;.br</xsl:text>
     <xsl:text>&#10;.fi</xsl:text>
@@ -345,6 +347,13 @@
     <xsl:text>&#10;.br</xsl:text>
   </xsl:template>
 
+  <!-- The name of data types -->
+  <xsl:template match="marker">
+    <xsl:if test="string-length(.) != 0">
+      <xsl:text>\fB</xsl:text><xsl:apply-templates/><xsl:text>\fR\&amp;</xsl:text>
+    </xsl:if>
+  </xsl:template>
+
   <!-- Used both in <datatype> and in <func>! -->
   <xsl:template match="anno">
     <xsl:variable name="curModule" select="ancestor::erlref/module"/>
@@ -465,13 +474,13 @@
     <xsl:text>&#10;.TP 2&#10;</xsl:text>
     <xsl:text>*&#10;</xsl:text>
     <xsl:apply-templates/>
-    <xsl:text>&#10;.LP&#10;</xsl:text>
+    <xsl:text>&#10;.LP</xsl:text>
   </xsl:template>
 
   <xsl:template match="taglist">
     <xsl:text>&#10;.RS 2</xsl:text>
     <xsl:apply-templates select="tag|item"/>
-    <xsl:text>&#10;.RE&#10;</xsl:text>
+    <xsl:text>&#10;.RE</xsl:text>
   </xsl:template>
 
   <xsl:template match="taglist/tag">
@@ -494,7 +503,7 @@
       </xsl:when>
       <xsl:otherwise>
         <xsl:text>&#10;.RS 2</xsl:text>
-        <xsl:text>&#10;.LP&#10;&#10;.LP&#10;</xsl:text>
+        <xsl:text>&#10;.LP&#10;</xsl:text>
         <xsl:value-of select="$content"/>
         <xsl:text>&#10;.RE</xsl:text>
       </xsl:otherwise>
@@ -529,7 +538,16 @@
   </xsl:template>
 
   <xsl:template match="br">
-    <xsl:text>&#10;.br&#10;</xsl:text>
+    <xsl:choose>
+      <xsl:when test="ancestor::head">
+        <!-- The header of Dialyzer specs.
+             .B makes next line appear in bold face -->
+        <xsl:text>&#10;.B&#10;</xsl:text>
+      </xsl:when>
+      <xsl:otherwise>
+        <xsl:text>&#10;.br&#10;</xsl:text>
+      </xsl:otherwise>
+    </xsl:choose>
   </xsl:template>
 
   <xsl:template match="c">
@@ -547,17 +565,17 @@
   <!-- Code -->
   <xsl:template match="code">
     <xsl:text>&#10;.LP&#10;</xsl:text>
-    <xsl:text>&#10;.nf&#10;</xsl:text>
+    <xsl:text>.nf&#10;</xsl:text>
     <xsl:apply-templates/>
-    <xsl:text>&#10;.fi&#10;</xsl:text>
+    <xsl:text>&#10;.fi</xsl:text>
   </xsl:template>
 
   <!-- Pre -->
   <xsl:template match="pre">
     <xsl:text>&#10;.LP&#10;</xsl:text>
-    <xsl:text>&#10;.nf&#10;</xsl:text>
+    <xsl:text>.nf&#10;</xsl:text>
     <xsl:apply-templates/>
-    <xsl:text>&#10;.fi&#10;</xsl:text>
+    <xsl:text>&#10;.fi</xsl:text>
   </xsl:template>
 
 
@@ -715,8 +733,8 @@
     <!-- The case where @name != 0 is taken care of in "type_name" -->
     <xsl:if test="string-length(@name) = 0 and string-length(@variable) = 0">
       <xsl:text>&#10;.RS</xsl:text>
-      <xsl:text>&#10;.TP</xsl:text>
-      <xsl:text>&#10;Types</xsl:text>
+      <xsl:text>&#10;.TP 3</xsl:text>
+      <xsl:text>&#10;Types:&#10;</xsl:text>
       <xsl:apply-templates/>
       <xsl:text>&#10;.RE</xsl:text>
     </xsl:if>
@@ -788,7 +806,36 @@
   <!-- Replace ' by \&' ans . by \&. -->
   <xsl:template match="text()">
     <xsl:variable name="startstring">
-      <xsl:value-of select="normalize-space()"/><xsl:text> </xsl:text>
+      <xsl:value-of select="normalize-space()"/>
+    </xsl:variable>
+    <!-- 'C' is just any character but whitespace -->
+    <xsl:variable name="tmp" select="normalize-space(concat('C',.,'C'))"/>
+    <xsl:variable name="space_before">
+      <xsl:choose>
+         <!-- '<p>A<marker id="swamp"/> swamp</p>' does not work; instead:
+              '<p>A <marker id="swamp"/>swamp</p>' -->
+         <xsl:when test="starts-with($tmp, 'C ')
+                and not (string(preceding-sibling::*[position()=1]) = ''
+                         and parent::p)">
+           <!-- and not (position() = 1 and parent::p)"> -->
+           <xsl:text> </xsl:text>
+         </xsl:when>
+         <xsl:otherwise>
+           <xsl:text/>
+         </xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:variable name="space_after">
+      <xsl:choose>
+         <xsl:when test="substring($tmp, string-length($tmp)-1,1) = ' '
+                         and $startstring != ''
+                         and not (position() = last() and parent::p)">
+           <xsl:text> </xsl:text>
+         </xsl:when>
+         <xsl:otherwise>
+           <xsl:text/>
+         </xsl:otherwise>
+      </xsl:choose>
     </xsl:variable>
     <xsl:variable name="rep1">
       <xsl:call-template name="replace-string">
@@ -804,11 +851,16 @@
         <xsl:with-param name="with" select="&quot;\&amp;&apos;&quot;" />
       </xsl:call-template>
     </xsl:variable>
-    <xsl:call-template name="replace-string">
-      <xsl:with-param name="text" select="$rep2" />
-      <xsl:with-param name="replace" select="&quot;.&quot;" />
-      <xsl:with-param name="with" select="&quot;\&amp;.&quot;" />
-    </xsl:call-template>
+    <xsl:variable name="reply">
+      <xsl:call-template name="replace-string">
+        <xsl:with-param name="text" select="$rep2" />
+        <xsl:with-param name="replace" select="&quot;.&quot;" />
+        <xsl:with-param name="with" select="&quot;\&amp;.&quot;" />
+      </xsl:call-template>
+    </xsl:variable>
+    <xsl:value-of select="$space_before"/>
+    <xsl:value-of select="$reply"/>
+    <xsl:value-of select="$space_after"/>
   </xsl:template>
 
   <!-- Template replace-string is borrowed at http://www.dpawson.co.uk/xsl/sect2/replace.html -->

diff --git a/lib/erl_interface/doc/src/erl_format.xml b/lib/erl_interface/doc/src/erl_format.xml
@@ -4,7 +4,7 @@
 <cref>
   <header>
     <copyright>
-      <year>1996</year><year>2009</year>
+      <year>1996</year><year>2011</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -105,7 +105,7 @@ erl_format("[{name,~a},{age,~i},{data,~w}]",
           values in <c><![CDATA[Term]]></c>. </p>
         <p>If <c><![CDATA[Term]]></c> and <c><![CDATA[Pattern]]></c> can be matched, the
           function returns a non-zero value and binds any unbound
-          variables in <c><![CDATA[Pattern]]></c>. If <c><![CDATA[Term]]></c><c><![CDATA[Pattern]]></c> do
+          variables in <c><![CDATA[Pattern]]></c>. If <c><![CDATA[Term]]></c> <c><![CDATA[Pattern]]></c> do
           not match, the function returns 0. For example:</p>
         <code type="none"><![CDATA[
 ETERM *term, *pattern, *pattern2;

diff --git a/lib/kernel/doc/src/app.xml b/lib/kernel/doc/src/app.xml
@@ -4,7 +4,7 @@
 <fileref>
   <header>
     <copyright>
-      <year>1997</year><year>2009</year>
+      <year>1997</year><year>2011</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -170,7 +170,6 @@ Phases       [{Phase,PhaseArgs}]  undefined
           start phase defined by the <c>start_phases</c> key, and only
           after this extended start procedure will
           <c>application:start(Application)</c> return.</p>
-        <p></p>
         <p>Start phases may be used to synchronize startup of an
           application and its included applications. In this case,
           the <c>mod</c> key must be specified as:</p>
@@ -182,7 +181,6 @@ Phases       [{Phase,PhaseArgs}]  undefined
           for the primary application) both for the primary application
           and for each of its included application, for which the start
           phase is defined.</p>
-        <p></p>
         <p>This implies that for an included application, the set of
           start phases must be a subset of the set of phases defined
           for the primary application. Refer to <em>OTP Design Principles</em> for more information.</p>

diff --git a/lib/kernel/doc/src/code.xml b/lib/kernel/doc/src/code.xml
@@ -177,9 +177,9 @@
      archives. But the functions in <c>erl_prim_loader</c> may also be
      used by other applications to read files from archives. For
      example, the call
-     <c>erl_prim_loader:list_dir("/otp/root/lib/mnesia-4.4.7.ez/mnesia-4.4.7/examples/bench)"</c>
+     <c>erl_prim_loader:list_dir( "/otp/root/lib/mnesia-4.4.7.ez/mnesia-4.4.7/examples/bench)"</c>
      would list the contents of a directory inside an archive.
-     See <seealso marker="erts:erl_prim_loader">erl_prim_loader(3)</seealso></p>
+     See <seealso marker="erts:erl_prim_loader">erl_prim_loader(3)</seealso></p>.
 
     <p>An application archive file and a regular application directory
      may coexist. This may be useful when there is a need of having