Add docs for changelog

git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@277660 13f79535-47bb-0310-9956-ffa450edef68
20 years ago · 027327211a
--- a/proposal/sandbox/svn/docs/changelog.html
+++ b/proposal/sandbox/svn/docs/changelog.html
@@ -0,0 +1,217 @@
 <html>
 <head>
 <meta http-equiv="Content-Language" content="en-us">
 <title>ChangeLog Task</title>
 </head>
 <body>
 <h2><a name="changelog">ChangeLog</a></h2>
 <h3>Description</h3>
 <p>Generates an XML-formatted report file of the change logs recorded
 in a <a href="http://subversion.tigris.org/"
 target="_top">Subversion</a> repository. </p>
 <p><b>Important:</b> This task needs "svn" on the path. If it isn't,
 you will get an error (such as error 2 on windows). If
 <code>&lt;svn&gt;</code> doesn't work, try to execute svn.exe from the
 command line in the target directory in which you are working.</p>
 <h3>Parameters</h3>
 <table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td colspan="3">Attributes from parent <a href="svn.html">svn
    task</a> which are meaningful here<br/>
  </tr>
  <tr>
    <td valign="top">svnURL</td>
    <td valign="top">the URL the subcommand should apply to.</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">dest</td>
    <td valign="top">the directory where the checked out files are.</td>
    <td align="center" valign="top">No, default is project's basedir.</td>
  </tr>
  <tr>
    <td valign="top">failonerror</td>
    <td valign="top">Stop the build process if the command exits with a
      return code other than <code>0</code>. Defaults to false</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td colspan="3">Specific attributes</td>
  </tr>
  <tr>
    <td valign="top">dir</td>
    <td valign="top">The directory from which to run the CVS <em>log</em>
     command.</td>
    <td align="center" valign="top">No; defaults to ${basedir}.</td>
  </tr>
  <tr>
    <td valign="top">destfile</td>
    <td valign="top">The file in which to write the change log report.</td>
    <td align="center" valign="top">Yes</td>
  </tr>
  <tr>
    <td valign="top">usersfile</td>
    <td valign="top">Property file that contains name-value pairs mapping
     user IDs and names that should be used in the report in place of
     the user ID.</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">daysinpast</td>
    <td valign="top">Sets the number of days into the past for which the
     change log information should be retrieved.</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">start</td>
    <td valign="top">The earliest revision/date from which change logs
    are to be included in the report.</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">end</td>
    <td valign="top">The latest revision/date to which change logs are to be
     included in the report.</td>
    <td align="center" valign="top">No</td>
  </tr>
 </table>
 <h3>Parameters specified as nested elements</h3>
 <h4><a name="user">user</a></h4>
 <p>The nested <code>&lt;user&gt;</code> element allows you to specify
 a mapping between a user ID as it appears on the Subversion server and
 a name to include in the formatted report.  Anytime the specified user
 ID has made a change in the repository, the
 <code>&lt;author&gt;</code> tag in the report file will include the
 name specified in <code>displayname</code> rather than the user
 ID.</p>
 <table border="1" cellpadding="2" cellspacing="0">
  <tr>
    <td valign="top"><b>Attribute</b></td>
    <td valign="top"><b>Description</b></td>
    <td align="center" valign="top"><b>Required</b></td>
  </tr>
  <tr>
    <td valign="top">displayname</td>
    <td valign="top">The name to be used in the Subversion change log
    report.</td>
    <td valign="top" align="center">Yes</td>
  </tr>
  <tr>
    <td valign="top">userid</td>
    <td valign="top">The userid of the person as it exists on the
    Subversion server.
    </td>
    <td valign="top" align="center">Yes</td>
  </tr>
 </table>
 <h3>Examples</h3>
 <pre>  &lt;changelog dir=&quot;dve/network&quot;
                destfile=&quot;changelog.xml&quot;
  /&gt;</pre>
 <p>Generates a change log report for all the changes that have been made
 under the <code>dve/network</code> directory.
 It writes these changes into the file <code>changelog.xml</code>.</p>
 <pre>  &lt;changelog dir=&quot;dve/network&quot;
                destfile=&quot;changelog.xml&quot;
                daysinpast=&quot;10&quot;
  /&gt;</pre>
 <p>Generates a change log report for any changes that were made
 under the <code>dve/network</code> directory in the past 10 days.
 It writes these changes into the file <code>changelog.xml</code>.</p>
 <pre>  &lt;changelog dir=&quot;dve/network&quot;
                destfile=&quot;changelog.xml&quot;
                start=&quot;{2002-02-20}&quot;
                end=&quot;{2002-03-20}&quot;
  /&gt;</pre>
 <p>Generates a change log report for any changes that were made
 between February 20, 2002 and March 20, 2002
 under the <code>dve/network</code> directory.
 It writes these changes into the file <code>changelog.xml</code>.</p>
 <pre>  &lt;changelog dir=&quot;dve/network&quot;
                destfile=&quot;changelog.xml&quot;
                start=&quot;{2002-02-20}&quot;
  /&gt;</pre>
 <p>Generates a change log report for any changes that were made
 after February 20, 2002 under the <code>dve/network</code> directory.
 It writes these changes into the file <code>changelog.xml</code>.</p>
 <pre>  &lt;changelog dir=&quot;dve/network&quot;
                destfile=&quot;changelog.xml&quot;
                start=&quot;1000&quot;
                end=&quot;1500&quot;
  /&gt;</pre>
 <p>Generates a change log report for any changes that were made
 between Subversion revisions 1000 and 1500 under the
 <code>dve/network</code> directory.  It writes these changes into the
 file <code>changelog.xml</code>.</p>
 <pre>  &lt;changelog dir=&quot;dve/network&quot;
                destfile=&quot;changelog.xml&quot;&gt;
       &lt;user displayname=&quot;Esmerelda Weatherwax&quot; userid=&quot;granny&quot;/&gt;
  &lt;/changelog&gt;</pre>
 <p>Generates a change log report for all the changes that were made
 under the <code>dve/network</code> directory, substituting the name
 &quot;Esmerelda Weatherwax&quot; in the <code>&lt;author&gt;</code> tags
 anytime it encounters a change made by the user ID &quot;granny&quot;.
 It writes these changes into the file <code>changelog.xml</code>.</p>
 <h4>Generate Report</h4>
 <p>This antlib includes a basic XSLT stylesheet that you can use to
 generate a HTML report based on the xml output. The following example
 illustrates how to generate a HTML report from the XML report.</p>
 <pre>
        &lt;style in="changelog.xml" 
               out="changelog.html" 
               style="your-path-to/etc/changelog.xsl"&gt;
          &lt;param name="title" expression="Jakarta BCEL ChangeLog"/&gt;
          &lt;param name="repo" expression="http://svn.apache.org/repos/asf"/&gt;
        &lt;/style&gt;
 </pre>
 <h4>Sample Output</h4>
 <pre>
  &lt;entry&gt;
    &lt;date&gt;2005-02-14&lt;/date&gt;
    &lt;time&gt;01:55&lt;/time&gt;
    &lt;author&gt;&lt;![CDATA[dbrosius]]&gt;&lt;/author&gt;
    &lt;revision&gt;153687&lt;/revision&gt;
    &lt;path&gt;
      &lt;name&gt;&lt;![CDATA[/jakarta/bcel/trunk/src/java/org/apache/bcel/util/BCELifier.java]]&gt;&lt;/name&gt;
      &lt;action&gt;modified&lt;/action&gt;
    &lt;/path&gt;
    &lt;message&gt;&lt;![CDATA[Update BCELifier to handle the new method access flags (ACC_BRIDGE, ACC_VARARGS)]]&gt;&lt;/message&gt;
  &lt;/entry&gt;
 </pre>
 <hr><p align="center">Copyright &copy; 2005 The Apache Software Foundation. All rights
 Reserved.</p>
 </body>
 </html>