db-derby-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From j..@apache.org
Subject svn commit: r169891 - in /incubator/derby/site/trunk: build/site/manuals/dita.html src/documentation/content/xdocs/manuals/dita.xml
Date Thu, 12 May 2005 21:54:17 GMT
Author: jta
Date: Thu May 12 14:54:15 2005
New Revision: 169891

URL: http://svn.apache.org/viewcvs?rev=169891&view=rev
Log:
Applied Jeff Levitt's patch to dita.xml. From his description:
  In the "How to create a doc patch"
  procedure, it now includes steps to create a JIRA
  entry and create a zip file with the patch and
  relevant html output for reviewing.  I also updated
  the instructions for creating output to include
  creating the "monohtml" output files.

Modified:
    incubator/derby/site/trunk/build/site/manuals/dita.html
    incubator/derby/site/trunk/src/documentation/content/xdocs/manuals/dita.xml

Modified: incubator/derby/site/trunk/build/site/manuals/dita.html
URL: http://svn.apache.org/viewcvs/incubator/derby/site/trunk/build/site/manuals/dita.html?rev=169891&r1=169890&r2=169891&view=diff
==============================================================================
--- incubator/derby/site/trunk/build/site/manuals/dita.html (original)
+++ incubator/derby/site/trunk/build/site/manuals/dita.html Thu May 12 14:54:15 2005
@@ -362,10 +362,11 @@
 <li>From a command line, navigate to <span class="codefrag">%DOC_ROOT%/trunk/</span>.</li>
 
 <li>Enter the desired <span class="codefrag">ant</span> command on the
command line using the following syntax:
-<pre class="code">ant &lt;output_type&gt;.&lt;manual_id&gt;</pre>The
<span class="codefrag">&lt;output_type&gt;</span> is the format of the
output you wish to create, either HTML or PDF.  The <span class="codefrag">&lt;manual_id&gt;</span>
is the id of the manual you wish to output.  The id can be found as the name of the directory
containing that manual's DITA source files in <span class="codefrag">%DOC_ROOT%/trunk/src/</span>.
 For example, to create PDF output for the <em>Getting Started with Derby</em>
guide, enter the following command:<pre class="code">ant pdf.getstart</pre> To
create PDF or HTML output for ALL SIX manuals at once, simply enter the output type with no
manual:<pre class="code">ant pdf</pre>or<pre class="code">ant html</pre>
+<pre class="code">ant &lt;output_type&gt;.&lt;manual_id&gt;</pre>The
<span class="codefrag">&lt;output_type&gt;</span> is the format of the
output you wish to create, either HTML or PDF.  The <span class="codefrag">&lt;manual_id&gt;</span>
is the id of the manual you wish to output.  The id can be found as the name of the directory
containing that manual's DITA source files in <span class="codefrag">%DOC_ROOT%/trunk/src/</span>.
 For example, to create PDF output for the <em>Getting Started with Derby</em>
guide, enter the following command:<pre class="code">ant pdf.getstart</pre> To
create PDF or HTML output for ALL SIX manuals at once, simply enter the output type with no
manual:<pre class="code">ant pdf</pre>or<pre class="code">ant html</pre>or<pre
class="code">ant monohtml</pre>
 </li>
 
 </ol>
+<p>Note that <span class="codefrag">monohtml</span> creates a single HTML
file for each manual, while <span class="codefrag">html</span> creates multiple
HTML files with a navigation tree.</p>
 <p>The output files will be built by the ant file and placed in the <span class="codefrag">%DOC_ROOT%/out/</span>
directory.  If any of the software is not set up and configured correctly, the build will
fail.</p>
 <p>The following table lists the manual id's for each Derby manual:</p>
 <table class="ForrestTable" cellspacing="1" cellpadding="4">
@@ -425,7 +426,7 @@
 </table>
 </div>
 
-<a name="N1011D"></a><a name="DITA+file+names"></a>
+<a name="N1012A"></a><a name="DITA+file+names"></a>
 <h2 class="boxed">DITA file names</h2>
 <div class="section">
 <p>Dita files are named to provide a sense of what type of topic they contain as well
as to which manual they belong.  All DITA topics are classified as either concepts, tasks,
or reference material.  Thus, every file begins with either a "c", "t", or "r".  In addition,
the letters that appear immediately after this first one provide a shorthand id for the manual.
 For example, the <span class="codefrag">Getting Started with Derby</span> manual
uses "gs", so a reference topic DITA file in that manual will start with "rgs".  Subsequent
letters in the file name may provide hints at the topic's section within the manual, as well
as numbers distinguishing it from other DITA files.</p>
@@ -433,7 +434,7 @@
 </div>
 
 
-<a name="N1012C"></a><a name="Modifying+the+output+format"></a>
+<a name="N10139"></a><a name="Modifying+the+output+format"></a>
 <h2 class="boxed">Modifying the output format</h2>
 <div class="section">
 <p>You may wish to modify the output created by the DITA Toolkit to fix organization,
formatting, links, indexing, etc.  To do this, you will have to modify the xsl files distributed
with the DITA Toolkit.  The instructions for which files to modify and how are included within
the Toolkit documentation.  To modify the PDF output, it is recommended that you make changes
only to the <span class="codefrag">dita2fo_shell.xsl</span> file.</p>
@@ -452,7 +453,7 @@
 
 
 
-<a name="N10149"></a><a name="Submitting+documentation+patches"></a>
+<a name="N10156"></a><a name="Submitting+documentation+patches"></a>
 <h2 class="boxed">Submitting documentation patches</h2>
 <div class="section">
 <p> 
@@ -483,6 +484,8 @@
 </p>
 <ol>
 
+<li>
+<a class="external" href="http://issues.apache.org/jira/browse/DERBY">Open a Jira issue</a>
under the documentation component for Derby, if one has not already been created for this
issue.  You will be posting your patch to the entry.  You can also create a documentation
subtask to an existing JIRA entry for code changes if your change is to reflect a bug fix,
new feature, etc.</li>
 
 <li> 
 
@@ -524,7 +527,7 @@
 <li> 
 
 <p>
-Test your changes by running <span class="codefrag">ant</span> to create output
in both HTML and PDF.  Make sure no new errors or build failures result from your changes,
and check that the output looks correct.
+Test your changes by running <span class="codefrag">ant</span> to create output
in both HTML and PDF.  Make sure no new errors or build failures result from your changes,
and check that the output looks correct.  This is the documentation that users will read,
so please check your writing for spelling, grammar, and punctuation mistakes.  
 </p> 
 
 </li> 
@@ -532,7 +535,7 @@
 <li> 
 
 <p> 
-Make the patch.
+Make the patch.  Be sure to create the patch from the <span class="codefrag">trunk/</span>
directory.
 </p> 
 
 <pre class="code">
@@ -542,18 +545,19 @@
 
 </li>
 
+<li>It will be necessary for the community to review your changes, and the best way
to do that is to see the HTML output that reflects your changes.  Since you have already created
HTML output when testing your changes, simply add the relevant HTML files along with the patch
file to a zip file.
+</li>
 
 <li> 
 
 
 <p> 
-Post the patch to the <a href="../derby_mail.html">derby-dev</a> mail list
-or attach it to the Jira issue.
+Attach the zip file to the appropriate JIRA entry.
 </p> 
 
 
 <p> 
-Include the following information with your post:
+Include the following information with your attachment:
 </p> 
 
      
@@ -610,7 +614,7 @@
 
 
 <p>
-<em>Last Updated: April 7, 2005</em>
+<em>Last Updated: May 12, 2005</em>
 </p>
 
 </div>

Modified: incubator/derby/site/trunk/src/documentation/content/xdocs/manuals/dita.xml
URL: http://svn.apache.org/viewcvs/incubator/derby/site/trunk/src/documentation/content/xdocs/manuals/dita.xml?rev=169891&r1=169890&r2=169891&view=diff
==============================================================================
--- incubator/derby/site/trunk/src/documentation/content/xdocs/manuals/dita.xml (original)
+++ incubator/derby/site/trunk/src/documentation/content/xdocs/manuals/dita.xml Thu May 12
14:54:15 2005
@@ -42,8 +42,9 @@
 <ol>
 <li>From a command line, navigate to <code>%DOC_ROOT%/trunk/</code>.</li>
 <li>Enter the desired <code>ant</code> command on the command line using
the following syntax:
-<source>ant &lt;output_type&gt;.&lt;manual_id&gt;</source>The
<code>&lt;output_type&gt;</code> is the format of the output you wish
to create, either HTML or PDF.  The <code>&lt;manual_id&gt;</code> is
the id of the manual you wish to output.  The id can be found as the name of the directory
containing that manual's DITA source files in <code>%DOC_ROOT%/trunk/src/</code>.
 For example, to create PDF output for the <em>Getting Started with Derby</em>
guide, enter the following command:<source>ant pdf.getstart</source> To create
PDF or HTML output for ALL SIX manuals at once, simply enter the output type with no manual:<source>ant
pdf</source>or<source>ant html</source></li>
+<source>ant &lt;output_type&gt;.&lt;manual_id&gt;</source>The
<code>&lt;output_type&gt;</code> is the format of the output you wish
to create, either HTML or PDF.  The <code>&lt;manual_id&gt;</code> is
the id of the manual you wish to output.  The id can be found as the name of the directory
containing that manual's DITA source files in <code>%DOC_ROOT%/trunk/src/</code>.
 For example, to create PDF output for the <em>Getting Started with Derby</em>
guide, enter the following command:<source>ant pdf.getstart</source> To create
PDF or HTML output for ALL SIX manuals at once, simply enter the output type with no manual:<source>ant
pdf</source>or<source>ant html</source>or<source>ant monohtml</source></li>
 </ol>
+<p>Note that <code>monohtml</code> creates a single HTML file for each
manual, while <code>html</code> creates multiple HTML files with a navigation
tree.</p>
 <p>The output files will be built by the ant file and placed in the <code>%DOC_ROOT%/out/</code>
directory.  If any of the software is not set up and configured correctly, the build will
fail.</p> <p>The following table lists the manual id's for each Derby manual:</p>
 <table>
 
@@ -129,7 +130,7 @@
 </p> 
 
 <ol>
-
+<li><a href="http://issues.apache.org/jira/browse/DERBY">Open a Jira issue</a>
under the documentation component for Derby, if one has not already been created for this
issue.  You will be posting your patch to the entry.  You can also create a documentation
subtask to an existing JIRA entry for code changes if your change is to reflect a bug fix,
new feature, etc.</li>
 <li> 
 
 <p>
@@ -160,28 +161,28 @@
 
 <li> 
 <p>
-Test your changes by running <code>ant</code> to create output in both HTML and
PDF.  Make sure no new errors or build failures result from your changes, and check that the
output looks correct.
+Test your changes by running <code>ant</code> to create output in both HTML and
PDF.  Make sure no new errors or build failures result from your changes, and check that the
output looks correct.  This is the documentation that users will read, so please check your
writing for spelling, grammar, and punctuation mistakes.  
 </p> 
 </li> 
 <li> 
 <p> 
-Make the patch.
+Make the patch.  Be sure to create the patch from the <code>trunk/</code> directory.
 </p> 
 <source>
 svn diff &gt; xyz.diff
 </source>
 
 </li>
-
+<li>It will be necessary for the community to review your changes, and the best way
to do that is to see the HTML output that reflects your changes.  Since you have already created
HTML output when testing your changes, simply add the relevant HTML files along with the patch
file to a zip file.
+</li>
 <li> 
 
 <p> 
-Post the patch to the <a href="../derby_mail.html">derby-dev</a> mail list
-or attach it to the Jira issue.
+Attach the zip file to the appropriate JIRA entry.
 </p> 
 
 <p> 
-Include the following information with your post:
+Include the following information with your attachment:
 </p> 
 
      <ul>
@@ -235,6 +236,6 @@
 </section>
 
 
-<p><em>Last Updated: April 7, 2005</em></p>
+<p><em>Last Updated: May 12, 2005</em></p>
 </body>
 </document>



Mime
View raw message