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 sc...@apache.org on 2007/03/22 03:30:23 UTC
svn commit: r521086 - in /db/derby/site/trunk: build/site/manuals/
build/site/papers/ src/documentation/content/xdocs/manuals/
src/documentation/content/xdocs/papers/
Author: scotsmatrix
Date: Wed Mar 21 19:30:21 2007
New Revision: 521086
URL: http://svn.apache.org/viewvc?view=rev&rev=521086
Log:
Derby-2454: This patch improves the procedures to create and commit doc patches, added instructions for creating cross-references, makes the API Reference easier to locate, and updates to the papers\derby_web.html file. Patch was contributed by me.
Modified:
db/derby/site/trunk/build/site/manuals/dita.html
db/derby/site/trunk/build/site/manuals/docsfaq.html
db/derby/site/trunk/build/site/manuals/guidelines.html
db/derby/site/trunk/build/site/manuals/index.html
db/derby/site/trunk/build/site/papers/derby_web.html
db/derby/site/trunk/src/documentation/content/xdocs/manuals/dita.xml
db/derby/site/trunk/src/documentation/content/xdocs/manuals/docsfaq.xml
db/derby/site/trunk/src/documentation/content/xdocs/manuals/guidelines.xml
db/derby/site/trunk/src/documentation/content/xdocs/manuals/index.xml
db/derby/site/trunk/src/documentation/content/xdocs/papers/derby_web.xml
Modified: db/derby/site/trunk/build/site/manuals/dita.html
URL: http://svn.apache.org/viewvc/db/derby/site/trunk/build/site/manuals/dita.html?view=diff&rev=521086&r1=521085&r2=521086
==============================================================================
--- db/derby/site/trunk/build/site/manuals/dita.html (original)
+++ db/derby/site/trunk/build/site/manuals/dita.html Wed Mar 21 19:30:21 2007
@@ -133,12 +133,12 @@
<p>
Starting with Derby 10.1,
-each Derby manual is sourced in an XML implementation called the Darwin Information Typing Architecture, or DITA. The original HTML source for the Derby documenation was converted to DITA to create an easy solution for requirements such as creating PDF outputs or single HTML files for each manual (See the
+each Derby manual is sourced in an XML implementation called the Darwin Information Typing Architecture, or DITA. The original HTML source for the Derby documentation was converted to DITA to create an easy solution for requirements such as creating PDF outputs or single HTML files for each manual (See the
<a class="external" href="http://mail-archives.apache.org/mod_mbox/db-derby-dev/200410.mbox/%3c200410071315.32497.Joel.Rosi-Schwartz@Etish.org%3e">Derby
documentation in PDF format</a> thread).
</p>
-<p>This page lists the software required to convert the DITA-sourced documentation into HTML or PDF, and describes how to convert the DITA source to the desired outputs. These instructions currently describe how to use an <span class="codefrag">ant</span> build file with the DITA Toolkit to create output.</p>
+<p>This page lists the software required to convert the DITA-sourced documentation into HTML or PDF, and describes how to convert the DITA source to the desired outputs. These instructions describe how to use an <span class="codefrag">ant</span> build file with the DITA Toolkit to create output.</p>
<a name="N1001A"></a><a name="Setting+up+your+environment"></a>
@@ -291,17 +291,37 @@
<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>or<pre class="code">ant monohtml</pre>
-To create PDF and HTML for just one manual, enter the manual with no type.
-For example, the command shown below builds all three
-for the <em>Getting Started with Derby</em> guide:
-<pre class="code">ant getstart</pre>
+The <span class="codefrag"><output_type></span> is the format of the output you wish to create.
+The options are HTML, PDF, or monohtml. The <span class="codefrag"><manual_id></span> is
+the id of the manual that you want to output. The id is the same as the name
+of the directory containing that manual's DITA source files in
+<span class="codefrag">%DOC_ROOT%/trunk/src/</span>. A list of the ids are shown in the table
+below. 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>
</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%/trunk/out/</span> directory. If any of the software is not set up and configured correctly, the build will fail.</p>
+<p>
+To create PDF or HTML output for ALL SIX manuals at once, specify the output
+type with no manual. For example:</p>
+<pre class="code">ant pdf</pre>
+<p>or</p>
+<pre class="code">ant html</pre>
+<p>or</p>
+<pre class="code">ant monohtml</pre>
+<p>To create all three output formats for just one manual, enter the manual
+with no type. For example, the command shown below builds PDF, HTML, and MONOHTML
+for the <em>Getting Started with Derby</em> guide:</p>
+<pre class="code">ant getstart</pre>
+<p>
+<strong>Note:</strong> <span class="codefrag">monohtml</span> creates a single HTML file for
+the manual you specify, 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%/trunk/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">
@@ -367,7 +387,7 @@
</table>
</div>
-<a name="N101DE"></a><a name="DITA+file+names"></a>
+<a name="N101EC"></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>
@@ -375,7 +395,7 @@
</div>
-<a name="N101ED"></a><a name="Modifying+the+output+format"></a>
+<a name="N101FB"></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>
@@ -385,16 +405,13 @@
</div>
-
-
<p>
Please post feedback to the
<a href="../derby_mail.html">derby-dev</a> mail list.
</p>
-
-<a name="N1020A"></a><a name="Submitting+documentation+patches"></a>
+<a name="N10218"></a><a name="Submitting+documentation+patches"></a>
<h2 class="boxed">Submitting documentation patches</h2>
<div class="section">
<p>
@@ -414,77 +431,104 @@
<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>
+<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.
+ <br>
+
+</li>
<li>
-
-
+
<p>
-Sync up your local svn copy with any changes checked into the server:
-</p>
-
-
+ Sync up your local svn copy with any changes checked into the server:
+ </p>
+
<pre class="code">
-cd <my_derby_loc>/trunk
-svn update
-</pre>
-
-
-</li>
-
+ cd <my_derby_loc>/trunk
+ svn update</pre>
+
+</li>
<li>
-
+
<p>
-Make your changes.
-</p>
-
-
+ Make your changes.
+ </p>
+
<ul>
-
+
<li>
<p>
- If you are adding a new file add a topicref for the new file to the
- ditamap where you want it to appear in the manual and add the file
+ If you are adding a new file, add a topicref for the new file to the
+ ditamap. You need to place the topicref in the ditamap exactly where you
+ want the new topic to appear in the manual. You must also add the file
using svn.
The example below shows adding a file named
- <span class="codefrag">cgsnewditafile.dita</span> to the <span class="codefrag">Getting Started Guide</span>:
+ <span class="codefrag">cgsnewditafile.dita</span> to the <span class="codefrag">Getting Started Guide</span>,
+ using the command line:
</p>
<pre class="code">
svn add src/getstart/cgsnewditafile.dita
- svn propset svn:eol-style native src/getstart/cgsnewditafile.dita
</pre>
-
+
+<p>
+ If you are using TortoiseSVN, you can add the file to svn through Windows
+ Explorer.
+ </p>
+
+<br>
+
+<p>After you add the file to the repository, it's important to set the
+ end-of-line property for the file to <span class="codefrag">native</span>. This is because
+ people making documentation contributions work on different operating systems.
+ You can set this property explicitly with the command shown below: </p>
+
+
+<pre class="code">svn propset svn:eol-style native src/getstart/cgsnewditafile.dita </pre>
+
+
+<p>However, the easiest way to manage the <span class="codefrag">svn:eol-style</span> property
+ is to automatically set end of line for common file types by adding the
+ <a class="external" href="http://www.apache.org/dev/svn-eol-style.txt">Apache dev list
+ of files to your ~/.subversion/config file</a>.</p>
+
+<br>
</li>
<li>
<p>
- If you are deleting a file,
- remove the topicref from the ditamap and
+ If you are deleting a file, remove the topicref from the ditamap and
delete the file using svn.
The example below shows deleting a file named
<span class="codefrag">rdevcsecure131.dita</span> in the
- <span class="codefrag">Developer's Guide</span>:
+ <span class="codefrag">Developer's Guide</span> using the command line:
</p>
<pre class="code">
svn del src/devguide/rdevcsecure131.dita
</pre>
+
+<p>
+ If you are using TortoiseSVN, you can delete the file through Windows
+ Explorer.
+ </p>
+
+<br>
</li>
-
</ul>
-
</li>
-
<li>
<p>
@@ -493,71 +537,111 @@
<ul>
-<li> At the very least run <span class="codefrag">ant html</span>, <span class="codefrag">ant monohtml</span> and
- <span class="codefrag">ant pdf</span> to create HTML and PDF output (running <span class="codefrag">ant all</span> is best).
- Verify that the PDF docs were actually created. If they weren't created,
- doublecheck that the <span class="codefrag">fop.jar</span>, <span class="codefrag">avalon-framework-cvs-20020806.jar</span>,
- and <span class="codefrag">batik.jar</span> files are in your <span class="codefrag">CLASSPATH</span>.</li>
+<li>At the very least run <span class="codefrag">ant html.<manual_id></span> and
+ <span class="codefrag">ant pdf.<manual_id></span>
+ to create the HTML and PDF outputs for the book that you are changing.</li>
+
+<li>Verify that the PDF docs were actually created. If they weren't created,
+ doublecheck that the <span class="codefrag">fop.jar</span>,
+ <span class="codefrag">avalon-framework-cvs-20020806.jar</span>, and <span class="codefrag">batik.jar</span>
+ files are in your <span class="codefrag">CLASSPATH</span>.</li>
+
+<li>Make sure no new errors or build failures result from your changes.</li>
-<li> Make sure no new errors or build failures result from your changes, and check that the output looks correct.</li>
+<li>Check that the output looks correct.</li>
-<li> This is the documentation that users will read, so please check your writing for spelling, grammar, and punctuation mistakes. </li>
+<li>This is the documentation that users will read, so please check your
+ writing for spelling, grammar, and punctuation mistakes. </li>
</ul>
-</li>
+<br>
-<li>
+</li>
-<p>
-Make the patch.
-Be sure to create the patch from the <span class="codefrag">trunk/</span> directory.
-The command shown below creates a patch with all the diffs in your
-working copy:
-</p>
+<li>
-<pre class="code">
-svn diff > xyz.diff
-</pre>
+<p>Make the patch.
+</p>
+<ul>
-<p>
-You can also create a patch with changes for just one book, as shown below:
-</p>
+<li>Be sure to create the patch from the <span class="codefrag">trunk/</span> directory.</li>
+<li>Run "svn stat" to see a list of the files that have been modified, added,
+or deleted.</li>
-<pre class="code">
-svn diff src/tuning > xyz.diff
-</pre>
+<li>Specify the JIRA issue in the patch name.</li>
+<li>If you think that there will be comments on your patch you should consider
+adding a number to the end of the patch name to making tracking subsequent patches
+easier.</li>
+
+</ul>
+
+<br>
+
+<p>The following command creates a patch with all the diffs in your
+ working copy. </p>
+
+<pre class="code">
+ svn diff > derby2222.diff
+ </pre>
+
+<p>The following command simply adds "ref" to the patch name, to indicate
+ that the patch contains updates to the Reference manual. </p>
+
+<pre class="code">
+ svn diff > derby2222-ref.diff
+ </pre>
+
+<p>
+ You can also create a patch with changes for just one book, as shown below:
+ </p>
+
+<pre class="code">
+ svn diff src/tuning > derby2222-tuning1.diff
+ </pre>
</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>Create a zip file of the HTML (and perhaps DITA) files
+ <p>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 to a zip file.</p>
+
+<p>If you are new to DITA, it is a good idea to include the DITA files in the
+ zip file. This will give the community the opportunity to review the tagging
+ that you used to ensure that consistent tagging is used in all Derby topics.
+ </p>
-<li>
+<br>
+</li>
+<li>
+
<p>
-Attach the zip file to the appropriate JIRA entry.
-</p>
-
-
+ Attach the zip file to the appropriate JIRA entry.
+ </p>
+
<p>
-Include the following information with your attachment:
-</p>
-
+ Include the following information with your attachment:
+ </p>
<ul>
-
-
-<li>Which manuals are affected by your changes, and whether you tested them for successful building.</li>
-
-<li> For a feature, bug fix, or large overhaul of the documentation, a description of the detailed functionality or reasons for the changes documented is essential.
- </li>
-
-
+
+<li>Which manuals are affected by your changes, and whether you tested them for
+ successful building.</li>
+
+<li>For a feature, bug fix, or large overhaul of the documentation, a
+ description of the detailed functionality or reasons for the changes documented
+ is essential.</li>
+
+<li>If you added or deleted files, post the results from "svn stat" in the
+ JIRA issue.</li>
+
</ul>
</li>
@@ -567,76 +651,99 @@
</div>
-<a name="N102B3"></a><a name="Committing+documentation+patches"></a>
+<a name="N1030B"></a><a name="Committing+documentation+patches"></a>
<h2 class="boxed">Committing documentation patches</h2>
<div class="section">
+<p>You must be a Derby committer to commit Derby patches.</p>
<ol>
-<li> Set up your environment (download required software, checkout Derby
+<li>
+
+<p>Set up your environment (download required software, checkout Derby
documentation source, set environment variables) as described in the
<a href="#Setting+up+your+environment">Setting up your environment</a>
- section.
- <ul>
+ section.</p>
+
+<ul>
<li>Don't forget to update your
<a class="external" href="http://www.apache.org/dev/version-control.html#https-svn">subversion
configuration file</a> with these entries:
-<pre class="code">*.dita = svn:eol-style=native
-*.ditamap = svn:eol-style=native
-*.out = svn:eol-style=native</pre>
-
+
+ <pre class="code">*.dita = svn:eol-style=native
+ *.ditamap = svn:eol-style=native
+ *.out = svn:eol-style=native</pre>
+
</li>
-
+
+
+<li>If you already have your environment setup, then you need to
+ check out the Derby documentation source into a new directory and prepare
+ your environment to generate output.
+ <br>
+
+</li>
+
+
+<li>If you use windows, you need to use a cygwin window to apply and commit
+ the patch. Download cygwin from the <a class="external" href="http://www.cygwin.com/">
+ cygwin Web site</a>. When you open a cygwin window, you must use a FORWARD slash to
+ change to a directory. For example:
+ <pre class="code">
+ $ cd c:/authoring/derby/commits </pre>
+
+</li>
+
</ul>
-
+
</li>
-
+
<li>The instructions in the
<a href="#Submitting+documentation+patches">Submitting documentation
- patches</a> tell contributors to create patches at the trunk
+ patches</a> section tell contributors to create patches at the trunk
level, so download the patch to the trunk of your working copy.
- </li>
+ <br>
+
+<br>
+
+</li>
-<li>Apply the patch using the GNU
+<li>
+<p>Apply the patch using the GNU
<a class="external" href="http://en.wikipedia.org/wiki/Patch_(Unix)"><span class="codefrag">patch</span></a>
- command:
+ command:</p>
+
<pre class="code">
-<a class="external" href="http://linux.about.com/od/commands/l/blcmdl1_patch.htm">patch -p0</a> < patch.diff</pre>
+<a class="external" href="http://linux.about.com/od/commands/l/blcmdl1_patch.htm">patch -p0</a> < patchname.diff</pre>
</li>
<li>Check modifications with the
<a class="external" href="http://svnbook.red-bean.com/en/1.1/re26.html"><span class="codefrag">svn status</span></a>
- command and add any files that need it:
-<pre class="code">svn add <em>filename</em>
-</pre>
+ command and add or delete any files as necessary. Follow the instuctions
+ to <a class="external" href="http://wiki.apache.org/db-derby/AddedOrDeletedFilesInDiff">
+ add or delete files</a>.
+ <br>
</li>
<li>Follow the instructions in the
<a href="#Creating+output">Creating output</a> section
to verify the doc build succeeds.
- </li>
+ <br>
+
+<br>
+
+</li>
<li>Commit the changes using the
<a class="external" href="http://svnbook.red-bean.com/en/1.1/re06.html"><span class="codefrag">svn
- commit</span></a> command. Sample commit syntax is shown below for
- changes made to the Developer's guide:
-<pre class="code">svn commit src/devguide
-svn commit --message "DERBY-1622: Add documentation for encrypting databases using encryptionKey connection attribute." src/devguide
-svn commit --file /tmp/derby-1622.txt src/devguide
-</pre>
- The first command, without the
- <span class="codefrag">--message</span> or <span class="codefrag">--file</span> arguments,
- will pull up the editor defined by the
- <a class="external" href="http://svnbook.red-bean.com/en/1.1/ch07.html">subversion
- <span class="codefrag">editor-cmd</span> property or the
- <span class="codefrag">SVN_EDITOR</span> environment variable</a>.
- The <span class="codefrag">--message</span> argument lets you enter the log message on
- the command line, and the
- <span class="codefrag">--file</span> argument lets you set the log message from a file.
- Please include the following information in the log message:
- <ul>
+ commit</span></a> command.
+ <p>
+ Please include the following information in the log message:
+ </p>
+
+<ul>
<li>DERBY Jira issue.</li>
@@ -645,15 +752,46 @@
<li>Name of the patch contributor if you didn't author this change.</li>
</ul>
+
+
+<p>
+ Sample commit syntax is shown below for
+ changes made to the Developer's guide:</p>
+
+<pre class="code">
+
+svn commit --message "DERBY-1622: Add documentation for encrypting databases
+using encryptionKey connection attribute. The patch derby1622-3.diff was
+contributed by Robin Williams." src/devguide
+
+svn commit --file /tmp/derby-1622.txt src/devguide
+</pre>
+
+ The <span class="codefrag">--message</span> argument lets you enter the log message on
+ the command line, and the
+ <span class="codefrag">--file</span> argument lets you set the log message from a file.
+ <br>
+
+<br>
</li>
+<li>Update the JIRA issue.
+<p>Copy the statement that is returned when you commit the patch
+(for example: Committed revision 513081) and paste it into a comment in the
+JIRA issue. If the patch resolves the issue, mark the issue as resolved and
+remove the check from "Patch Available".
+</p>
+
+</li>
+
</ol>
</div>
+
<p>
-<em>Last Updated: December 4, 2006</em>
+<em>Last Updated: March 19, 2007</em>
</p>
</div>
Modified: db/derby/site/trunk/build/site/manuals/docsfaq.html
URL: http://svn.apache.org/viewvc/db/derby/site/trunk/build/site/manuals/docsfaq.html?view=diff&rev=521086&r1=521085&r2=521086
==============================================================================
--- db/derby/site/trunk/build/site/manuals/docsfaq.html (original)
+++ db/derby/site/trunk/build/site/manuals/docsfaq.html Wed Mar 21 19:30:21 2007
@@ -104,6 +104,18 @@
<div id="minitoc-area">
<ul class="minitoc">
<li>
+<a href="#Cross+references%3A+To+another+DITA+topic+in+the+same+Derby+manual">Cross references: To another DITA topic in the same Derby manual</a>
+</li>
+<li>
+<a href="#Cross+references%3A+To+a+DITA+topic+in+a+different+Derby+manual">Cross references: To a DITA topic in a different Derby manual</a>
+</li>
+<li>
+<a href="#Cross+references%3A+To+a+Web+site">Cross references: To a Web site</a>
+</li>
+<li>
+<a href="#Code+Examples">Code Examples</a>
+</li>
+<li>
<a href="#Semi-colon+use+at+the+end+of+statements+and+commands">Semi-colon use at the end of statements and commands</a>
</li>
<li>
@@ -111,14 +123,111 @@
or expression?</a>
</li>
</ul>
-</div>
+</div>
+
+<a name="N1000D"></a><a name="Cross+references%3A+To+another+DITA+topic+in+the+same+Derby+manual"></a>
+<h2 class="boxed">Cross references: To another DITA topic in the same Derby manual</h2>
+<div class="section">
+<p>To create a cross reference to another DITA topic in the same Derby manual,
+use the <strong>xref</strong> tag. You must specify the filename for the DITA
+topic, followed by the pound symbol and the ID specified inside the topic.
+</p>
+<p>For example:
+<br>
+
+</p>
+<pre class="code">
+<xref href="rrefjdbc32052.dita#rrefjdbc32052"></xref>
+</pre>
+<p>
+
+</p>
+</div>
+
+<a name="N10026"></a><a name="Cross+references%3A+To+a+DITA+topic+in+a+different+Derby+manual"></a>
+<h2 class="boxed">Cross references: To a DITA topic in a different Derby manual</h2>
+<div class="section">
+<p>Currently, you cannot create a cross reference to a DITA topic in a different
+Derby manual. However, you can create a citation to the other manual.
+</p>
+<p>You specify the manual by using the <strong>cite</strong> and
+<strong>conref</strong> tags. If you mention the name of the topic,
+use quotations around the name of the topic. Here is an example:
+<br>
+
+</p>
+<pre class="code">
+For information about Derby properties, see the "derby.stream.error.logSeverityLevel property" topic
+in the <cite> <ph conref="refconrefs.dita#pub/cittuning"></ph> guide</cite>
+for instructions on how to print more information to Derby log files.
+</pre>
+<p>
+
+</p>
+</div>
+
+<a name="N10042"></a><a name="Cross+references%3A+To+a+Web+site"></a>
+<h2 class="boxed">Cross references: To a Web site</h2>
+<div class="section">
+<p>To create a cross reference to a Web site, use the
+<strong>xref</strong> tag. You must specify the type, href, and scope attributes.
+</p>
+<p>For example:
+<br>
+
+</p>
+<pre class="code">
+<xref format="html" href="http://www.w3.org/TR/xpath" scope="external">http://www.w3.org/TR/xpath</xref>
+</pre>
+<p>
+
+</p>
+</div>
+
+<a name="N1005B"></a><a name="Code+Examples"></a>
+<h2 class="boxed">Code Examples</h2>
+<div class="section">
+<p>
+When you have a long code example, it is a good idea to display the code
+over several lines. There are several reasons for this:
+</p>
+<ol>
+
+<li>The example is easier to read if it is broken up into logical sections</li>
+
+<li>In PDF output, a long code example might extend beyond the page borders and
+get truncated.</li>
+
+</ol>
+<p>
+You should always use <strong>4 spaces</strong> to indent the lines that are below the
+first line in the code example. <strong>Do not use tabs</strong> to indent. Tabs produce
+inconsistent output.
+</p>
+<p>
+Here an example of a simple SQL statement:
+</p>
+<pre class="code">
+SELECT * FROM flights
+ WHERE HOUR(departure_time) = 6 and MINUTE(departure_time) < 31
+</pre>
+<p>
+Here an example of a more complex SQL statement:
+</p>
+<pre class="code">
+CREATE TABLE x_table
+ ( id INT,
+ xcol XML CHECK (XMLEXISTS ('//student[@age < 25]' PASSING BY REF xcol))
+ )
+</pre>
+</div>
-<a name="N1000D"></a><a name="Semi-colon+use+at+the+end+of+statements+and+commands"></a>
+<a name="N10085"></a><a name="Semi-colon+use+at+the+end+of+statements+and+commands"></a>
<h2 class="boxed">Semi-colon use at the end of statements and commands</h2>
<div class="section">
<p>
-The semi-colon should only be included if the documentation is showing the
-example statement as the statement would be issued in ij. For example:
+The semi-colon should be included only when you want to document an example
+statement that will be issued in ij. For example:
</p>
<pre class="code">
ij> connect 'mydb';
@@ -132,15 +241,14 @@
<pre class="code">
select * from t1
</pre>
-<p>This issue was discussed on derby-dev in August 2006
+<p>This issue was discussed on derby-dev in August 2006:
<br>
-<a class="external" href="http://www.nabble.com/Documentation-Style-Issue---semi-colon-at-the-end-of-SQL-statement-examples-tf2141831.html#a5913071">Documentation Style Issue - semi-colon at the end of SQL statement examples</a>
-
+<a class="external" href="http://www.nabble.com/Documentation-Style-Issue---semi-colon-at-the-end-of-SQL-statement-examples-tf2141831.html#a5913071">Documentation Style Issue - semi-colon at the end of SQL statement examples</a>.
</p>
</div>
-<a name="N1002D"></a><a name="SQL+terminology%3A+When+do+I+use+the+terms+statement%2C+clause%2C+parameter%2C+%0Aor+expression%3F"></a>
+<a name="N100A5"></a><a name="SQL+terminology%3A+When+do+I+use+the+terms+statement%2C+clause%2C+parameter%2C+%0Aor+expression%3F"></a>
<h2 class="boxed">SQL terminology: When do I use the terms statement, clause, parameter,
or expression?</h2>
<div class="section">
@@ -168,7 +276,6 @@
GROUP BY
HAVING
ORDER BY
- VALUES
WHERE
</pre>
<p>
@@ -194,7 +301,7 @@
<p>
-<em>Last Updated: January 29, 2007</em>
+<em>Last Updated: March 19, 2007</em>
</p>
</div>
Modified: db/derby/site/trunk/build/site/manuals/guidelines.html
URL: http://svn.apache.org/viewvc/db/derby/site/trunk/build/site/manuals/guidelines.html?view=diff&rev=521086&r1=521085&r2=521086
==============================================================================
--- db/derby/site/trunk/build/site/manuals/guidelines.html (original)
+++ db/derby/site/trunk/build/site/manuals/guidelines.html Wed Mar 21 19:30:21 2007
@@ -277,7 +277,7 @@
<td colspan="1" rowspan="1">A new function, ROUND, is being documented in the Reference Manual
</td>
<td colspan="1" rowspan="1">rreffuncround</td>
- <td colspan="1" rowspan="1">If all functions start with <pre class="code">rreffunc</pre>, then they will be
+ <td colspan="1" rowspan="1">If all functions start with <span class="codefrag">rreffunc</span>, then they will be
grouped together alphabetically which makes the files that discuss functions
easier to find when the files need to be updated.
<br>
@@ -296,7 +296,7 @@
<td colspan="1" rowspan="1">cdevlocksshared</td>
<td colspan="1" rowspan="1">Because this is a concept topic in the
developers guide about locks, the beginning of the topic filename is
- <pre class="code">cdevlocks</pre>. The end of the filename <pre class="code">shared</pre>
+ <span class="codefrag">cdevlocks</span>. The end of the filename <span class="codefrag">shared</span>
indicates the specific type of locks that the topic describes.
<br>
@@ -332,7 +332,7 @@
</div>
-<a name="N1012E"></a><a name="Understanding+DITA+tags"></a>
+<a name="N1012B"></a><a name="Understanding+DITA+tags"></a>
<h2 class="boxed">Understanding DITA tags</h2>
<div class="section">
<p>The tags that are used in DITA topics are similar to HTML and XML tags.</p>
@@ -352,7 +352,7 @@
</div>
-<a name="N1014B"></a><a name="Tagging+examples+-+structural+tags"></a>
+<a name="N10148"></a><a name="Tagging+examples+-+structural+tags"></a>
<h2 class="boxed">Tagging examples - structural tags</h2>
<div class="section">
<p>The following table lists the proper structural tags to use for the most common
@@ -522,7 +522,7 @@
</div>
-<a name="N10260"></a><a name="Tagging+examples+-+textual+tags"></a>
+<a name="N1025D"></a><a name="Tagging+examples+-+textual+tags"></a>
<h2 class="boxed">Tagging examples - textual tags</h2>
<div class="section">
<p>The following table lists the proper textual tags to use for the most common
@@ -613,7 +613,7 @@
-<a name="N102D1"></a><a name="Indexing+guidelines"></a>
+<a name="N102CE"></a><a name="Indexing+guidelines"></a>
<h2 class="boxed">Indexing guidelines</h2>
<div class="section">
<p>
@@ -782,7 +782,7 @@
</div>
-<a name="N10377"></a><a name="Customizing+tables+in+the+Derby+documentation"></a>
+<a name="N10374"></a><a name="Customizing+tables+in+the+Derby+documentation"></a>
<h2 class="boxed">Customizing tables in the Derby documentation</h2>
<div class="section">
<p>
@@ -830,6 +830,7 @@
</p>
</div>
+
<p>
<br>
@@ -839,7 +840,7 @@
<p>
-<em>Last Updated: November 7, 2006</em>
+<em>Last Updated: March 19, 2007</em>
</p>
</div>
Modified: db/derby/site/trunk/build/site/manuals/index.html
URL: http://svn.apache.org/viewvc/db/derby/site/trunk/build/site/manuals/index.html?view=diff&rev=521086&r1=521085&r2=521086
==============================================================================
--- db/derby/site/trunk/build/site/manuals/index.html (original)
+++ db/derby/site/trunk/build/site/manuals/index.html Wed Mar 21 19:30:21 2007
@@ -139,8 +139,22 @@
<li>
<p>
+<em>Derby API Reference</em>:
+ An API Reference that is automatically generated for all public Derby
+ classes. No API Reference is provided for the JDBC API, which is part of the
+ Java 2 Platform, Standard Edition.
+ </p>
+
+</li>
+
+<li>
+<p>
<em>Getting Started with Derby</em>:
- Introduces Derby to new users.
+ Describes how to install and configure Derby. Includes a self-study
+ tutorial for users new to Derby and a quick-start guide for experienced
+ JDBC users. Introduces the sysinfo and ij tools that
+ come with Derby. Describes the libraries and scripts that are included
+ with Derby.
</p>
</li>
@@ -203,7 +217,7 @@
</div>
-<a name="N10053"></a><a name="latest"></a>
+<a name="N1005A"></a><a name="latest"></a>
<h2 class="boxed">Latest Alpha Manuals</h2>
<div class="section">
<p>The latest development version of the manuals, corresponding to the
@@ -219,7 +233,7 @@
<tr>
-<td colspan="1" rowspan="1">API</td>
+<td colspan="1" rowspan="1">API Reference</td>
<td colspan="1" rowspan="1"><a target="_blank" class="fork" href="http://db.apache.org/derby/javadoc/publishedapi/">HTML</a></td>
</tr>
@@ -349,7 +363,7 @@
</div>
-<a name="N101C2"></a><a name="docs_10.2"></a>
+<a name="N101C9"></a><a name="docs_10.2"></a>
<h2 class="boxed">10.2 Manuals</h2>
<div class="section">
<p>The 10.2 manuals are listed in this section.
@@ -364,7 +378,7 @@
<tr>
-<td colspan="1" rowspan="1">API</td>
+<td colspan="1" rowspan="1">API Reference</td>
<td colspan="1" rowspan="1"><a target="_blank" class="fork" href="http://db.apache.org/derby/docs/10.2/publishedapi/">HTML</a></td>
</tr>
@@ -479,7 +493,7 @@
</div>
-<a name="N10311"></a><a name="docs_10.1"></a>
+<a name="N10318"></a><a name="docs_10.1"></a>
<h2 class="boxed">10.1 Manuals</h2>
<div class="section">
<p>
@@ -501,7 +515,7 @@
<tr>
-<td colspan="1" rowspan="1">API</td>
+<td colspan="1" rowspan="1">API Reference</td>
<td colspan="1" rowspan="1"><a target="_blank" class="fork" href="http://db.apache.org/derby/docs/10.1/publishedapi/">HTML</a></td>
</tr>
@@ -570,7 +584,7 @@
</div>
-<a name="N103EC"></a><a name="docs_10.0"></a>
+<a name="N103F3"></a><a name="docs_10.0"></a>
<h2 class="boxed">10.0 Manuals</h2>
<div class="section">
<p>
@@ -589,7 +603,7 @@
<tr>
-<td colspan="1" rowspan="1">API</td>
+<td colspan="1" rowspan="1">API Reference</td>
<td colspan="1" rowspan="1"><a target="_blank" class="fork" href="http://db.apache.org/derby/docs/10.0/publishedapi/">HTML</a></td>
</tr>
@@ -663,7 +677,7 @@
-<a name="N10498"></a><a name="doc_issues"></a>
+<a name="N1049F"></a><a name="doc_issues"></a>
<h2 class="boxed">Reporting Documentation Issues</h2>
<div class="section">
<p>
@@ -674,7 +688,7 @@
<p>
-<em>Last Updated: December 16, 2006</em>
+<em>Last Updated: March 19, 2007</em>
</p>
</div>
Modified: db/derby/site/trunk/build/site/papers/derby_web.html
URL: http://svn.apache.org/viewvc/db/derby/site/trunk/build/site/papers/derby_web.html?view=diff&rev=521086&r1=521085&r2=521086
==============================================================================
--- db/derby/site/trunk/build/site/papers/derby_web.html (original)
+++ db/derby/site/trunk/build/site/papers/derby_web.html Wed Mar 21 19:30:21 2007
@@ -162,7 +162,7 @@
<a href="#5.+Test+the+changes">5. Test the changes </a>
</li>
<li>
-<a href="#odd_diffs">6. Odd diffs under build/site/skin and build/site/papers explained (sort of) </a>
+<a href="#odd_diffs">6. Adjust the site build - odd diffs</a>
</li>
<li>
<a href="#7.+Create+a+patch">7. Create a patch</a>
@@ -751,34 +751,32 @@
</p>
<a name="N10331"></a><a name="odd_diffs"></a>
-<h3 class="boxed">6. Odd diffs under build/site/skin and build/site/papers explained (sort of) </h3>
-<p>
-Forrest generates inconsistent line endings on Windows machines
-(see <a class="external" href="https://issues.apache.org/jira/browse/FOR-492">FOR-492</a>
-and <a class="external" href="https://issues.apache.org/jira/browse/FOR-805">FOR-805</a>).
-Also <span class="codefrag">png</span> files generated from <span class="codefrag">aart</span>
-source may get generated differently on different platforms.
-</p>
-<p>
-Derby developers build the site on a variety of platforms,
-including Windows, Mac, and Linux.
-<span class="codefrag">svn status</span> may report modifications to files under
+<h3 class="boxed">6. Adjust the site build - odd diffs</h3>
+<p>Derby developers build the site on a variety of platforms,
+including Windows, Mac, and Linux. The
+<span class="codefrag">svn status</span> command might report modifications to files under
<span class="codefrag">build/site/skin</span>
and to the <span class="codefrag">png</span> files under
<span class="codefrag">build/site/papers</span>
after you build the site,
depending on who last committed those files.
</p>
-<p>
-It's harmless to commit those files, though it does add some minor bloat
-to the Derby repository, and
-it's also harmless to <span class="codefrag">svn revert</span> them.
-And it's certainly confusing!
-Feel free to ask on
-<a href="../derby_mail.html">derby-dev@db.apache.org</a>
-if a particular file should be committed or not.
+<p>For example, when you run the <span class="codefrag">forrest site</span> command to build the
+site, Forrest generates inconsistent line endings on Windows machines
+(see <a class="external" href="https://issues.apache.org/jira/browse/FOR-492">FOR-492</a>
+and <a class="external" href="https://issues.apache.org/jira/browse/FOR-805">FOR-805</a>).
+Also <span class="codefrag">png</span> files generated from <span class="codefrag">aart</span>
+source may get generated differently on different operating systems.
</p>
-<a name="N10362"></a><a name="7.+Create+a+patch"></a>
+<p>As a result, you might get odd diffs under <span class="codefrag">build/site/skin</span> and
+the <span class="codefrag">build/site/papers</span> directories.</p>
+<p>If you are using a <strong>Windows</strong> machine to build the site, you
+should revert the changes made to the <span class="codefrag">skin</span> directory
+<strong>before</strong> you create the patch. For example:</p>
+<pre class="code">svn revert build\site\skin\*</pre>
+<p>If you are using TortoiseSVN, you can use Windows Explorer to revert the
+changes.</p>
+<a name="N10377"></a><a name="7.+Create+a+patch"></a>
<h3 class="boxed">7. Create a patch</h3>
<p>
Create a patch at the <span class="codefrag">trunk</span> level and only include the
@@ -788,7 +786,7 @@
<p>
Upload the patch to a Jira issue to make it available to a Derby committer.
</p>
-<a name="N10379"></a><a name="8.+Commit+changes+to+the+src+and+build%2Fsite+directories"></a>
+<a name="N1038E"></a><a name="8.+Commit+changes+to+the+src+and+build%2Fsite+directories"></a>
<h3 class="boxed">8. Commit changes to the src and build/site directories</h3>
<p>
Apply any patch, if one was provided, then build and test the web site
@@ -833,7 +831,7 @@
<pre class="code">
svn commit --message "here is my commit message" src build/site
</pre>
-<a name="N103C1"></a><a name="9.+Make+web+site+changes+visible"></a>
+<a name="N103D6"></a><a name="9.+Make+web+site+changes+visible"></a>
<h3 class="boxed">9. Make web site changes visible</h3>
<p>
A Derby committer can make web site changes visible as follows:
@@ -847,7 +845,7 @@
www.apache.org automatically syncs up with people.apache.org every couple hours
(the specific schedule could change).
</p>
-<a name="N103D5"></a><a name="10.+Considering+a+quick+fix+to+the+build+tree%3F"></a>
+<a name="N103EA"></a><a name="10.+Considering+a+quick+fix+to+the+build+tree%3F"></a>
<h3 class="boxed">10. Considering a quick fix to the build tree?</h3>
<p>
If you modify a file in the <span class="codefrag">build/site</span> tree,
Modified: db/derby/site/trunk/src/documentation/content/xdocs/manuals/dita.xml
URL: http://svn.apache.org/viewvc/db/derby/site/trunk/src/documentation/content/xdocs/manuals/dita.xml?view=diff&rev=521086&r1=521085&r2=521086
==============================================================================
--- db/derby/site/trunk/src/documentation/content/xdocs/manuals/dita.xml (original)
+++ db/derby/site/trunk/src/documentation/content/xdocs/manuals/dita.xml Wed Mar 21 19:30:21 2007
@@ -24,11 +24,11 @@
<p>
Starting with Derby 10.1,
-each Derby manual is sourced in an XML implementation called the Darwin Information Typing Architecture, or DITA. The original HTML source for the Derby documenation was converted to DITA to create an easy solution for requirements such as creating PDF outputs or single HTML files for each manual (See the
+each Derby manual is sourced in an XML implementation called the Darwin Information Typing Architecture, or DITA. The original HTML source for the Derby documentation was converted to DITA to create an easy solution for requirements such as creating PDF outputs or single HTML files for each manual (See the
<a href="http://mail-archives.apache.org/mod_mbox/db-derby-dev/200410.mbox/%3c200410071315.32497.Joel.Rosi-Schwartz@Etish.org%3e">Derby
documentation in PDF format</a> thread).
</p>
-<p>This page lists the software required to convert the DITA-sourced documentation into HTML or PDF, and describes how to convert the DITA source to the desired outputs. These instructions currently describe how to use an <code>ant</code> build file with the DITA Toolkit to create output.</p>
+<p>This page lists the software required to convert the DITA-sourced documentation into HTML or PDF, and describes how to convert the DITA source to the desired outputs. These instructions describe how to use an <code>ant</code> build file with the DITA Toolkit to create output.</p>
<section>
<title>Setting up your environment</title>
@@ -112,16 +112,35 @@
<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>or<source>ant monohtml</source>
-To create PDF and HTML for just one manual, enter the manual with no type.
-For example, the command shown below builds all three
-for the <em>Getting Started with Derby</em> guide:
-<source>ant getstart</source>
+The <code><output_type></code> is the format of the output you wish to create.
+The options are HTML, PDF, or monohtml. The <code><manual_id></code> is
+the id of the manual that you want to output. The id is the same as the name
+of the directory containing that manual's DITA source files in
+<code>%DOC_ROOT%/trunk/src/</code>. A list of the ids are shown in the table
+below. For example, to create PDF output for the
+<em>Getting Started with Derby</em> guide, enter the following command:
+<source>ant pdf.getstart</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%/trunk/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>
+<p>
+To create PDF or HTML output for ALL SIX manuals at once, specify the output
+type with no manual. For example:</p>
+<source>ant pdf</source>
+<p>or</p>
+<source>ant html</source>
+<p>or</p>
+<source>ant monohtml</source>
+<p>To create all three output formats for just one manual, enter the manual
+with no type. For example, the command shown below builds PDF, HTML, and MONOHTML
+for the <em>Getting Started with Derby</em> guide:</p>
+<source>ant getstart</source>
+<p><strong>Note:</strong> <code>monohtml</code> creates a single HTML file for
+the manual you specify, 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%/trunk/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>
<tr>
@@ -173,17 +192,13 @@
</section>
-
-
<p>
Please post feedback to the
<a href="../derby_mail.html">derby-dev</a> mail list.
</p>
-
<section>
<title>Submitting documentation patches</title>
-
<p>
<strong>Contribution guidelines</strong>
</p>
@@ -191,190 +206,270 @@
If you would like to participate directly in any Derby development (including documentation changes),
be sure to read the guidelines found <a href="http://db.apache.org/derby/derby_comm.html#Contribute+Code+or+Documentation">here</a>.
</p>
-
-
+
<p>
<strong>How to create a patch</strong>
</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><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.
+ <br></br>
+ </li>
<li>
-
-<p>
-Sync up your local svn copy with any changes checked into the server:
-</p>
-
-<source>
-cd <my_derby_loc>/trunk
-svn update
-</source>
-
-</li>
-
+ <p>
+ Sync up your local svn copy with any changes checked into the server:
+ </p>
+ <source>
+ cd <my_derby_loc>/trunk
+ svn update</source>
+ </li>
<li>
-<p>
-Make your changes.
-</p>
-
- <ul>
- <li>
+ <p>
+ Make your changes.
+ </p>
+ <ul>
+ <li>
<p>
- If you are adding a new file add a topicref for the new file to the
- ditamap where you want it to appear in the manual and add the file
+ If you are adding a new file, add a topicref for the new file to the
+ ditamap. You need to place the topicref in the ditamap exactly where you
+ want the new topic to appear in the manual. You must also add the file
using svn.
The example below shows adding a file named
- <code>cgsnewditafile.dita</code> to the <code>Getting Started Guide</code>:
+ <code>cgsnewditafile.dita</code> to the <code>Getting Started Guide</code>,
+ using the command line:
</p>
<source>
svn add src/getstart/cgsnewditafile.dita
- svn propset svn:eol-style native src/getstart/cgsnewditafile.dita
</source>
-
+ <p>
+ If you are using TortoiseSVN, you can add the file to svn through Windows
+ Explorer.
+ </p>
+ <br></br>
+ <p>After you add the file to the repository, it's important to set the
+ end-of-line property for the file to <code>native</code>. This is because
+ people making documentation contributions work on different operating systems.
+ You can set this property explicitly with the command shown below: </p>
+
+ <source>svn propset svn:eol-style native src/getstart/cgsnewditafile.dita </source>
+
+ <p>However, the easiest way to manage the <code>svn:eol-style</code> property
+ is to automatically set end of line for common file types by adding the
+ <a href="http://www.apache.org/dev/svn-eol-style.txt">Apache dev list
+ of files to your ~/.subversion/config file</a>.</p>
+ <br></br>
</li>
<li>
<p>
- If you are deleting a file,
- remove the topicref from the ditamap and
+ If you are deleting a file, remove the topicref from the ditamap and
delete the file using svn.
The example below shows deleting a file named
<code>rdevcsecure131.dita</code> in the
- <code>Developer's Guide</code>:
+ <code>Developer's Guide</code> using the command line:
</p>
<source>
svn del src/devguide/rdevcsecure131.dita
</source>
+ <p>
+ If you are using TortoiseSVN, you can delete the file through Windows
+ Explorer.
+ </p>
+ <br></br>
</li>
-
</ul>
-
</li>
-
<li>
<p>
Test your changes.
</p>
<ul>
- <li> At the very least run <code>ant html</code>, <code>ant monohtml</code> and
- <code>ant pdf</code> to create HTML and PDF output (running <code>ant all</code> is best).
- Verify that the PDF docs were actually created. If they weren't created,
- doublecheck that the <code>fop.jar</code>, <code>avalon-framework-cvs-20020806.jar</code>,
- and <code>batik.jar</code> files are in your <code>CLASSPATH</code>.</li>
- <li> Make sure no new errors or build failures result from your changes, and check that the output looks correct.</li>
- <li> This is the documentation that users will read, so please check your writing for spelling, grammar, and punctuation mistakes. </li>
+ <li>At the very least run <code>ant html.<manual_id></code> and
+ <code>ant pdf.<manual_id></code>
+ to create the HTML and PDF outputs for the book that you are changing.</li>
+ <li>Verify that the PDF docs were actually created. If they weren't created,
+ doublecheck that the <code>fop.jar</code>,
+ <code>avalon-framework-cvs-20020806.jar</code>, and <code>batik.jar</code>
+ files are in your <code>CLASSPATH</code>.</li>
+ <li>Make sure no new errors or build failures result from your changes.</li>
+ <li>Check that the output looks correct.</li>
+ <li>This is the documentation that users will read, so please check your
+ writing for spelling, grammar, and punctuation mistakes. </li>
</ul>
-</li>
-<li>
-<p>
-Make the patch.
-Be sure to create the patch from the <code>trunk/</code> directory.
-The command shown below creates a patch with all the diffs in your
-working copy:
-</p>
-<source>
-svn diff > xyz.diff
-</source>
-
-<p>
-You can also create a patch with changes for just one book, as shown below:
-</p>
-
-<source>
-svn diff src/tuning > xyz.diff
-</source>
-
+<br></br>
</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>
+<p>Make the patch.
+</p>
+<ul>
+<li>Be sure to create the patch from the <code>trunk/</code> directory.</li>
+<li>Run "svn stat" to see a list of the files that have been modified, added,
+or deleted.</li>
+<li>Specify the JIRA issue in the patch name.</li>
+<li>If you think that there will be comments on your patch you should consider
+adding a number to the end of the patch name to making tracking subsequent patches
+easier.</li>
+ </ul>
+ <br></br>
+ <p>The following command creates a patch with all the diffs in your
+ working copy. </p>
+ <source>
+ svn diff > derby2222.diff
+ </source>
+ <p>The following command simply adds "ref" to the patch name, to indicate
+ that the patch contains updates to the Reference manual. </p>
+ <source>
+ svn diff > derby2222-ref.diff
+ </source>
+ <p>
+ You can also create a patch with changes for just one book, as shown below:
+ </p>
+ <source>
+ svn diff src/tuning > derby2222-tuning1.diff
+ </source>
+</li>
+<li>Create a zip file of the HTML (and perhaps DITA) files
+ <p>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 to a zip file.</p>
+ <p>If you are new to DITA, it is a good idea to include the DITA files in the
+ zip file. This will give the community the opportunity to review the tagging
+ that you used to ensure that consistent tagging is used in all Derby topics.
+ </p>
+<br></br>
</li>
<li>
-
-<p>
-Attach the zip file to the appropriate JIRA entry.
-</p>
-
-<p>
-Include the following information with your attachment:
-</p>
-
+ <p>
+ Attach the zip file to the appropriate JIRA entry.
+ </p>
+ <p>
+ Include the following information with your attachment:
+ </p>
<ul>
-
- <li>Which manuals are affected by your changes, and whether you tested them for successful building.</li>
- <li> For a feature, bug fix, or large overhaul of the documentation, a description of the detailed functionality or reasons for the changes documented is essential.
- </li>
-
- </ul>
+ <li>Which manuals are affected by your changes, and whether you tested them for
+ successful building.</li>
+ <li>For a feature, bug fix, or large overhaul of the documentation, a
+ description of the detailed functionality or reasons for the changes documented
+ is essential.</li>
+ <li>If you added or deleted files, post the results from "svn stat" in the
+ JIRA issue.</li>
+ </ul>
</li>
</ol>
-
</section>
<section>
<title>Committing documentation patches</title>
+<p>You must be a Derby committer to commit Derby patches.</p>
<ol>
- <li> Set up your environment (download required software, checkout Derby
+ <li>
+ <p>Set up your environment (download required software, checkout Derby
documentation source, set environment variables) as described in the
<a href="#Setting+up+your+environment">Setting up your environment</a>
- section.
+ section.</p>
<ul>
<li>Don't forget to update your
<a href="http://www.apache.org/dev/version-control.html#https-svn">subversion
configuration file</a> with these entries:
-<source>*.dita = svn:eol-style=native
-*.ditamap = svn:eol-style=native
-*.out = svn:eol-style=native</source>
- </li>
- </ul>
- </li>
- <li>The instructions in the
+
+ <source>*.dita = svn:eol-style=native
+ *.ditamap = svn:eol-style=native
+ *.out = svn:eol-style=native</source>
+ </li>
+
+ <li>If you already have your environment setup, then you need to
+ check out the Derby documentation source into a new directory and prepare
+ your environment to generate output.
+ <br></br>
+ </li>
+
+ <li>If you use windows, you need to use a cygwin window to apply and commit
+ the patch. Download cygwin from the <a href="http://www.cygwin.com/">
+ cygwin Web site</a>. When you open a cygwin window, you must use a FORWARD slash to
+ change to a directory. For example:
+ <source>
+ $ cd c:/authoring/derby/commits </source>
+ </li>
+ </ul>
+ </li>
+<li>The instructions in the
<a href="#Submitting+documentation+patches">Submitting documentation
- patches</a> tell contributors to create patches at the trunk
+ patches</a> section tell contributors to create patches at the trunk
level, so download the patch to the trunk of your working copy.
+ <br></br>
+ <br></br>
</li>
- <li>Apply the patch using the GNU
+ <li><p>Apply the patch using the GNU
<a href="http://en.wikipedia.org/wiki/Patch_(Unix)"><code>patch</code></a>
- command:
-<source><a href="http://linux.about.com/od/commands/l/blcmdl1_patch.htm">patch -p0</a> < patch.diff</source>
+ command:</p>
+<source><a href="http://linux.about.com/od/commands/l/blcmdl1_patch.htm">patch -p0</a> < patchname.diff</source>
</li>
<li>Check modifications with the
<a href="http://svnbook.red-bean.com/en/1.1/re26.html"><code>svn status</code></a>
- command and add any files that need it:
-<source>svn add <em>filename</em></source>
+ command and add or delete any files as necessary. Follow the instuctions
+ to <a href="http://wiki.apache.org/db-derby/AddedOrDeletedFilesInDiff">
+ add or delete files</a>.
+ <br></br>
</li>
<li>Follow the instructions in the
<a href="#Creating+output">Creating output</a> section
to verify the doc build succeeds.
+ <br></br>
+ <br></br>
</li>
<li>Commit the changes using the
<a href="http://svnbook.red-bean.com/en/1.1/re06.html"><code>svn
- commit</code></a> command. Sample commit syntax is shown below for
- changes made to the Developer's guide:
-<source>svn commit src/devguide
-svn commit --message "DERBY-1622: Add documentation for encrypting databases using encryptionKey connection attribute." src/devguide
-svn commit --file /tmp/derby-1622.txt src/devguide
-</source>
- The first command, without the
- <code>--message</code> or <code>--file</code> arguments,
- will pull up the editor defined by the
- <a href="http://svnbook.red-bean.com/en/1.1/ch07.html">subversion
- <code>editor-cmd</code> property or the
- <code>SVN_EDITOR</code> environment variable</a>.
- The <code>--message</code> argument lets you enter the log message on
- the command line, and the
- <code>--file</code> argument lets you set the log message from a file.
- Please include the following information in the log message:
+ commit</code></a> command.
+ <p>
+ Please include the following information in the log message:
+ </p>
<ul>
<li>DERBY Jira issue.</li>
<li>Description of the change.</li>
<li>Name of the patch contributor if you didn't author this change.</li>
</ul>
+
+ <p>
+ Sample commit syntax is shown below for
+ changes made to the Developer's guide:</p>
+<source>
+<!--svn commit src/devguide -->
+svn commit --message "DERBY-1622: Add documentation for encrypting databases
+using encryptionKey connection attribute. The patch derby1622-3.diff was
+contributed by Robin Williams." src/devguide
+
+svn commit --file /tmp/derby-1622.txt src/devguide
+</source>
+<!-- The first command, without the
+ <code>message</code> or <code>file</code> arguments,
+ will pull up the editor defined by the
+ <a href="http://svnbook.red-bean.com/en/1.1/ch07.html">subversion
+ <code>editor-cmd</code> property or the
+ <code>SVN_EDITOR</code> environment variable</a>.-->
+ The <code>--message</code> argument lets you enter the log message on
+ the command line, and the
+ <code>--file</code> argument lets you set the log message from a file.
+ <br></br>
+ <br></br>
</li>
+<li>Update the JIRA issue.
+<p>Copy the statement that is returned when you commit the patch
+(for example: Committed revision 513081) and paste it into a comment in the
+JIRA issue. If the patch resolves the issue, mark the issue as resolved and
+remove the check from "Patch Available".
+</p>
+</li>
</ol>
-
</section>
-<p><em>Last Updated: December 4, 2006</em></p>
+
+<p><em>Last Updated: March 19, 2007</em></p>
</body>
</document>
Modified: db/derby/site/trunk/src/documentation/content/xdocs/manuals/docsfaq.xml
URL: http://svn.apache.org/viewvc/db/derby/site/trunk/src/documentation/content/xdocs/manuals/docsfaq.xml?view=diff&rev=521086&r1=521085&r2=521086
==============================================================================
--- db/derby/site/trunk/src/documentation/content/xdocs/manuals/docsfaq.xml (original)
+++ db/derby/site/trunk/src/documentation/content/xdocs/manuals/docsfaq.xml Wed Mar 21 19:30:21 2007
@@ -20,12 +20,92 @@
<header>
<title>Apache Derby: Writing FAQs</title>
</header>
- <body>
+ <body>
+<section>
+<title>Cross references: To another DITA topic in the same Derby manual</title>
+<p>To create a cross reference to another DITA topic in the same Derby manual,
+use the <strong>xref</strong> tag. You must specify the filename for the DITA
+topic, followed by the pound symbol and the ID specified inside the topic.
+</p>
+<p>For example:
+<br></br>
+</p>
+<source>
+<xref href="rrefjdbc32052.dita#rrefjdbc32052"></xref>
+</source>
+<p>
+</p>
+</section>
+<section>
+<title>Cross references: To a DITA topic in a different Derby manual</title>
+<p>Currently, you cannot create a cross reference to a DITA topic in a different
+Derby manual. However, you can create a citation to the other manual.
+</p>
+<p>You specify the manual by using the <strong>cite</strong> and
+<strong>conref</strong> tags. If you mention the name of the topic,
+use quotations around the name of the topic. Here is an example:
+<br></br>
+</p>
+<source>
+For information about Derby properties, see the "derby.stream.error.logSeverityLevel property" topic
+in the <cite> <ph conref="refconrefs.dita#pub/cittuning"></ph> guide</cite>
+for instructions on how to print more information to Derby log files.
+</source>
+<p>
+</p>
+</section>
+<section>
+<title>Cross references: To a Web site</title>
+<p>To create a cross reference to a Web site, use the
+<strong>xref</strong> tag. You must specify the type, href, and scope attributes.
+</p>
+<p>For example:
+<br></br>
+</p>
+<source>
+<xref format="html" href="http://www.w3.org/TR/xpath" scope="external">http://www.w3.org/TR/xpath</xref>
+</source>
+<p>
+</p>
+</section>
+<section>
+<title>Code Examples</title>
+<p>
+When you have a long code example, it is a good idea to display the code
+over several lines. There are several reasons for this:
+</p>
+<ol>
+<li>The example is easier to read if it is broken up into logical sections</li>
+<li>In PDF output, a long code example might extend beyond the page borders and
+get truncated.</li>
+</ol>
+<p>
+You should always use <strong>4 spaces</strong> to indent the lines that are below the
+first line in the code example. <strong>Do not use tabs</strong> to indent. Tabs produce
+inconsistent output.
+</p>
+<p>
+Here an example of a simple SQL statement:
+</p>
+<source>
+SELECT * FROM flights
+ WHERE HOUR(departure_time) = 6 and MINUTE(departure_time) < 31
+</source>
+<p>
+Here an example of a more complex SQL statement:
+</p>
+<source>
+CREATE TABLE x_table
+ ( id INT,
+ xcol XML CHECK (XMLEXISTS ('//student[@age < 25]' PASSING BY REF xcol))
+ )
+</source>
+</section>
<section>
<title>Semi-colon use at the end of statements and commands</title>
<p>
-The semi-colon should only be included if the documentation is showing the
-example statement as the statement would be issued in ij. For example:
+The semi-colon should be included only when you want to document an example
+statement that will be issued in ij. For example:
</p>
<source>
ij> connect 'mydb';
@@ -38,9 +118,9 @@
<source>
select * from t1
</source>
-<p>This issue was discussed on derby-dev in August 2006
+<p>This issue was discussed on derby-dev in August 2006:
<br></br>
-<a href="http://www.nabble.com/Documentation-Style-Issue---semi-colon-at-the-end-of-SQL-statement-examples-tf2141831.html#a5913071">Documentation Style Issue - semi-colon at the end of SQL statement examples</a>
+<a href="http://www.nabble.com/Documentation-Style-Issue---semi-colon-at-the-end-of-SQL-statement-examples-tf2141831.html#a5913071">Documentation Style Issue - semi-colon at the end of SQL statement examples</a>.
</p>
</section>
<section>
@@ -68,7 +148,6 @@
GROUP BY
HAVING
ORDER BY
- VALUES
WHERE
</source>
<p>
@@ -87,6 +166,6 @@
<a href="../derby_mail.html">derby-dev</a> mail list.
</p>
-<p><em>Last Updated: January 29, 2007</em></p>
+<p><em>Last Updated: March 19, 2007</em></p>
</body>
</document>
Modified: db/derby/site/trunk/src/documentation/content/xdocs/manuals/guidelines.xml
URL: http://svn.apache.org/viewvc/db/derby/site/trunk/src/documentation/content/xdocs/manuals/guidelines.xml?view=diff&rev=521086&r1=521085&r2=521086
==============================================================================
--- db/derby/site/trunk/src/documentation/content/xdocs/manuals/guidelines.xml (original)
+++ db/derby/site/trunk/src/documentation/content/xdocs/manuals/guidelines.xml Wed Mar 21 19:30:21 2007
@@ -123,7 +123,7 @@
<td>A new function, ROUND, is being documented in the Reference Manual
</td>
<td>rreffuncround</td>
- <td>If all functions start with <source>rreffunc</source>, then they will be
+ <td>If all functions start with <code>rreffunc</code>, then they will be
grouped together alphabetically which makes the files that discuss functions
easier to find when the files need to be updated.
<br></br>
@@ -137,7 +137,7 @@
<td>cdevlocksshared</td>
<td>Because this is a concept topic in the
developers guide about locks, the beginning of the topic filename is
- <source>cdevlocks</source>. The end of the filename <source>shared</source>
+ <code>cdevlocks</code>. The end of the filename <code>shared</code>
indicates the specific type of locks that the topic describes.
<br></br>
<br></br>
@@ -562,12 +562,13 @@
Valid settings for the valign attribute are: top, middle, bottom.
</p>
</section>
+
<p>
<br></br>
Please post feedback to the
<a href="../derby_mail.html">derby-dev</a> mail list.
</p>
-<p><em>Last Updated: November 7, 2006</em></p>
+<p><em>Last Updated: March 19, 2007</em></p>
</body>
</document>
Modified: db/derby/site/trunk/src/documentation/content/xdocs/manuals/index.xml
URL: http://svn.apache.org/viewvc/db/derby/site/trunk/src/documentation/content/xdocs/manuals/index.xml?view=diff&rev=521086&r1=521085&r2=521086
==============================================================================
--- db/derby/site/trunk/src/documentation/content/xdocs/manuals/index.xml (original)
+++ db/derby/site/trunk/src/documentation/content/xdocs/manuals/index.xml Wed Mar 21 19:30:21 2007
@@ -31,8 +31,18 @@
</p>
<ul>
+ <li><p><em>Derby API Reference</em>:
+ An API Reference that is automatically generated for all public Derby
+ classes. No API Reference is provided for the JDBC API, which is part of the
+ Java 2 Platform, Standard Edition.
+ </p>
+ </li>
<li><p><em>Getting Started with Derby</em>:
- Introduces Derby to new users.
+ Describes how to install and configure Derby. Includes a self-study
+ tutorial for users new to Derby and a quick-start guide for experienced
+ JDBC users. Introduces the sysinfo and ij tools that
+ come with Derby. Describes the libraries and scripts that are included
+ with Derby.
</p>
</li>
<li><p><em>Working with Derby</em>:
@@ -79,7 +89,7 @@
<th colspan="2">English</th>
</tr>
<tr>
- <td>API</td>
+ <td>API Reference</td>
<td><a class="fork" href="http://db.apache.org/derby/javadoc/publishedapi/">HTML</a></td>
</tr>
<tr>
@@ -159,9 +169,9 @@
<th colspan="2">Japanese</th>
</tr>
<tr>
- <td><em>初めての Apache Derby</em></td>
- <td> [<a class="fork" href="http://db.apache.org/derby/docs/dev/ja_JP/getstart/getstart-single.html">HTML:書籍の体裁</a>]
- [<a class="fork" href="http://db.apache.org/derby/docs/dev/ja_JP/getstart/">HTML:サイトの体裁</a>]
+ <td><em>åãã¦ã® Apache Derby</em></td>
+ <td> [<a class="fork" href="http://db.apache.org/derby/docs/dev/ja_JP/getstart/getstart-single.html">HTML:æ¸ç±ã®ä½è£</a>]
+ [<a class="fork" href="http://db.apache.org/derby/docs/dev/ja_JP/getstart/">HTML:ãµã¤ãã®ä½è£</a>]
</td>
</tr>
</table>
@@ -178,7 +188,7 @@
<th colspan="2">English</th>
</tr>
<tr>
- <td>API</td>
+ <td>API Reference</td>
<td><a class="fork" href="http://db.apache.org/derby/docs/10.2/publishedapi/">HTML</a></td>
</tr>
<tr>
@@ -275,7 +285,7 @@
<th colspan="2">English</th>
</tr>
<tr>
- <td>API</td>
+ <td>API Reference</td>
<td><a class="fork" href="http://db.apache.org/derby/docs/10.1/publishedapi/">HTML</a></td>
</tr>
<tr>
@@ -339,7 +349,7 @@
<th colspan="2">English</th>
</tr>
<tr>
- <td>API</td>
+ <td>API Reference</td>
<td><a class="fork" href="http://db.apache.org/derby/docs/10.0/publishedapi/">HTML</a></td>
</tr>
<tr>
@@ -399,6 +409,6 @@
</section>
-<p><em>Last Updated: December 16, 2006</em></p>
+<p><em>Last Updated: March 19, 2007</em></p>
</body>
</document>
Modified: db/derby/site/trunk/src/documentation/content/xdocs/papers/derby_web.xml
URL: http://svn.apache.org/viewvc/db/derby/site/trunk/src/documentation/content/xdocs/papers/derby_web.xml?view=diff&rev=521086&r1=521085&r2=521086
==============================================================================
--- db/derby/site/trunk/src/documentation/content/xdocs/papers/derby_web.xml (original)
+++ db/derby/site/trunk/src/documentation/content/xdocs/papers/derby_web.xml Wed Mar 21 19:30:21 2007
@@ -15,8 +15,7 @@
See the License for the specific language governing permissions and
limitations under the License.
-->
-<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
-
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd" >
<document>
<header>
<title>Apache Derby Web Site</title>
@@ -238,9 +237,9 @@
<body>
- <p>An introductory blurb for your document.</p>
+ <p>An introductory blurb for your document.</p>
- <source><![CDATA[
+ <source><![CDATA[
<em>Put the contents of your text file here</em> ]]></source>
</body>
@@ -572,20 +571,11 @@
</section>
<section id="odd_diffs">
-<title>6. Odd diffs under build/site/skin and build/site/papers explained (sort of) </title>
-
-<p>
-Forrest generates inconsistent line endings on Windows machines
-(see <a href="https://issues.apache.org/jira/browse/FOR-492">FOR-492</a>
-and <a href="https://issues.apache.org/jira/browse/FOR-805">FOR-805</a>).
-Also <code>png</code> files generated from <code>aart</code>
-source may get generated differently on different platforms.
-</p>
+<title>6. Adjust the site build - odd diffs</title>
-<p>
-Derby developers build the site on a variety of platforms,
-including Windows, Mac, and Linux.
-<code>svn status</code> may report modifications to files under
+<p>Derby developers build the site on a variety of platforms,
+including Windows, Mac, and Linux. The
+<code>svn status</code> command might report modifications to files under
<code>build/site/skin</code>
and to the <code>png</code> files under
<code>build/site/papers</code>
@@ -593,15 +583,23 @@
depending on who last committed those files.
</p>
-<p>
-It's harmless to commit those files, though it does add some minor bloat
-to the Derby repository, and
-it's also harmless to <code>svn revert</code> them.
-And it's certainly confusing!
-Feel free to ask on
-<a href="../derby_mail.html">derby-dev@db.apache.org</a>
-if a particular file should be committed or not.
+<p>For example, when you run the <code>forrest site</code> command to build the
+site, Forrest generates inconsistent line endings on Windows machines
+(see <a href="https://issues.apache.org/jira/browse/FOR-492">FOR-492</a>
+and <a href="https://issues.apache.org/jira/browse/FOR-805">FOR-805</a>).
+Also <code>png</code> files generated from <code>aart</code>
+source may get generated differently on different operating systems.
</p>
+
+<p>As a result, you might get odd diffs under <code>build/site/skin</code> and
+the <code>build/site/papers</code> directories.</p>
+
+<p>If you are using a <strong>Windows</strong> machine to build the site, you
+should revert the changes made to the <code>skin</code> directory
+<strong>before</strong> you create the patch. For example:</p>
+<source>svn revert build\site\skin\*</source>
+<p>If you are using TortoiseSVN, you can use Windows Explorer to revert the
+changes.</p>
</section>