You are viewing a plain text version of this content. The canonical link for it is here.
Posted to derby-commits@db.apache.org by jt...@apache.org on 2005/05/12 23:54:17 UTC
svn commit: r169891 - in /incubator/derby/site/trunk:
build/site/manuals/dita.html src/documentation/content/xdocs/manuals/dita.xml
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 <output_type>.<manual_id></pre>The <span class="codefrag"><output_type></span> is the format of the output you wish to create, either HTML or PDF. The <span class="codefrag"><manual_id></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 <output_type>.<manual_id></pre>The <span class="codefrag"><output_type></span> is the format of the output you wish to create, either HTML or PDF. The <span class="codefrag"><manual_id></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 <output_type>.<manual_id></source>The <code><output_type></code> is the format of the output you wish to create, either HTML or PDF. The <code><manual_id></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 <output_type>.<manual_id></source>The <code><output_type></code> is the format of the output you wish to create, either HTML or PDF. The <code><manual_id></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 > 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>