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 2006/10/30 21:04:59 UTC
svn commit: r469254 - in /db/derby/site/trunk: build/site/
build/site/manuals/ src/documentation/content/xdocs/
src/documentation/content/xdocs/manuals/
Author: jta
Date: Mon Oct 30 12:04:56 2006
New Revision: 469254
URL: http://svn.apache.org/viewvc?view=rev&rev=469254
Log:
DERBY-1980 Add new doc to derby web site on writing guidelines.
Patch contributed by Laura Stewart <sc...@gmail.com>.
Added:
db/derby/site/trunk/build/site/manuals/guidelines.html (with props)
db/derby/site/trunk/src/documentation/content/xdocs/manuals/guidelines.xml (with props)
Modified:
db/derby/site/trunk/build/site/linkmap.html
db/derby/site/trunk/build/site/manuals/dita.html
db/derby/site/trunk/build/site/manuals/index.html
db/derby/site/trunk/src/documentation/content/xdocs/manuals/dita.xml
db/derby/site/trunk/src/documentation/content/xdocs/site.xml
Modified: db/derby/site/trunk/build/site/linkmap.html
URL: http://svn.apache.org/viewvc/db/derby/site/trunk/build/site/linkmap.html?view=diff&rev=469254&r1=469253&r2=469254
==============================================================================
--- db/derby/site/trunk/build/site/linkmap.html (original)
+++ db/derby/site/trunk/build/site/linkmap.html Mon Oct 30 12:04:56 2006
@@ -119,6 +119,9 @@
<div class="menuitem">
<a href="manuals/dita.html">DITA Source</a>
</div>
+<div class="menuitem">
+<a href="manuals/guidelines.html">Writing Guidelines</a>
+</div>
</div>
<div onclick="SwitchMenu('menu_1.6', 'skin/')" id="menu_1.6Title" class="menutitle">Other Products</div>
<div id="menu_1.6" class="menuitemgroup">
@@ -473,6 +476,12 @@
<ul>
<li>
<a href="manuals/dita.html">DITA Source</a> _________________________ <em>ditafile</em>
+</li>
+</ul>
+
+<ul>
+<li>
+<a href="manuals/guidelines.html">Writing Guidelines</a> _________________________ <em>ditaguid</em>
</li>
</ul>
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=469254&r1=469253&r2=469254
==============================================================================
--- db/derby/site/trunk/build/site/manuals/dita.html (original)
+++ db/derby/site/trunk/build/site/manuals/dita.html Mon Oct 30 12:04:56 2006
@@ -68,6 +68,9 @@
<div class="menupage">
<div class="menupagetitle">DITA Source</div>
</div>
+<div class="menuitem">
+<a href="../manuals/guidelines.html">Writing Guidelines</a>
+</div>
</div>
<div class="searchbox">
<hr>
@@ -95,6 +98,9 @@
<a href="#Setting+up+your+environment">Setting up your environment</a>
</li>
<li>
+<a href="#Locating+the+correct+DITA+file">Locating the correct DITA file</a>
+</li>
+<li>
<a href="#Editing+DITA+files">Editing DITA files</a>
</li>
<li>
@@ -183,11 +189,45 @@
<p>For PDF output: Make sure to include the <span class="codefrag">fop.jar</span>, <span class="codefrag">avalon-framework-cvs-20020806.jar</span>, and <span class="codefrag">batik.jar</span> files located in <span class="codefrag">%DOC_ROOT%/trunk/lib/</span> in your <span class="codefrag">CLASSPATH</span> environment variable.</p>
</li>
-
</ol>
</div>
-<a name="N1009C"></a><a name="Editing+DITA+files"></a>
+
+<a name="N1009C"></a><a name="Locating+the+correct+DITA+file"></a>
+<h2 class="boxed">Locating the correct DITA file</h2>
+<div class="section">
+<p>The simpliest way to determine the name of the file that contains the information that you want to update is to:</p>
+<ol>
+
+<li>
+<p>Go to the Derby Documentation <a href="http://db.apache.org/derby/manuals/index.html">Overiew</a> page.</p>
+</li>
+
+<li>
+<p>Under the section <strong>Latest Alpha Manuals</strong>, click the link for the HTML Pages for the manual that contains the information that you want to update.</p>
+</li>
+
+<li>
+<p>An outline of the manual topics appears on the left side of the screen. Use the outline to find the topic that you want to update.</p>
+</li>
+
+<li>
+<p>In the outline, right-click on the topic name and choose <strong>properties</strong>. The name of the file is at the top of the dialog. The address (URL) contains the path and name of the file. For example, if the address contains <span class="codefrag">http://db.apache.org/derby/docs/dev/getstart/cgsquck19524.html</span>, the fliename for the topic that you want to update is <strong>cgsquck19524.dita</strong>
+</p>
+</li>
+
+</ol>
+<p>
+Guidelines for writing Derby information using DITA is on the Derby Documentation
+<a href="http://db.apache.org/derby/manuals/guidelines.html">Writing Guidelines</a> page.</p>
+<p>To learn more about DITA, how to create or edit DITA files, and find more XML editors that support DITA, go to:</p>
+<pre class="code">
+<a class="external" href="http://dita.xml.org/">http://dita.xml.org/</a>
+</pre>
+</div>
+
+
+<a name="N100D7"></a><a name="Editing+DITA+files"></a>
<h2 class="boxed">Editing DITA files</h2>
<div class="section">
<p>DITA is an XML specification. You can edit DITA files in any text editor, but XML editors allow you to insert and modifiy tags easily while conforming to the DITA DTD and schemas. It is HIGHLY recommended that you use an XML editor to avoid errors in tagging.</p>
@@ -210,14 +250,15 @@
</li>
</ul>
-<p>
-To learn more about DITA, how to create or edit DITA files, and find more XML editors that support DITA, go to:</p>
+<p>Guidelines for writing Derby information using DITA is on the Derby Documentation <a href="http://db.apache.org/derby/manuals/guidelines.html">Writing Guidelines</a> page.</p>
+<p>To learn more about DITA, how to create or edit DITA files, and find more XML editors that support DITA, go to:</p>
<pre class="code">
-<a class="external" href="http://dita.xml.org/">http://dita.xml.org/</a>
+<a class="external" href="http://dita.xml.org/">http://dita.xml.org/></a>
</pre>
</div>
-<a name="N100CD"></a><a name="Creating+output"></a>
+
+<a name="N1010F"></a><a name="Creating+output"></a>
<h2 class="boxed">Creating output</h2>
<div class="section">
<p>To create output from the DITA source files:</p>
@@ -296,7 +337,7 @@
</table>
</div>
-<a name="N1017D"></a><a name="DITA+file+names"></a>
+<a name="N101BF"></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>
@@ -304,7 +345,7 @@
</div>
-<a name="N1018C"></a><a name="Modifying+the+output+format"></a>
+<a name="N101CE"></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>
@@ -323,12 +364,12 @@
-<a name="N101A9"></a><a name="Submitting+documentation+patches"></a>
+<a name="N101EB"></a><a name="Submitting+documentation+patches"></a>
<h2 class="boxed">Submitting documentation patches</h2>
<div class="section">
<p>
-<strong>Guidelines</strong>
+<strong>Contribution guidelines</strong>
</p>
<p>
@@ -496,7 +537,7 @@
</div>
-<a name="N10252"></a><a name="Committing+documentation+patches"></a>
+<a name="N10294"></a><a name="Committing+documentation+patches"></a>
<h2 class="boxed">Committing documentation patches</h2>
<div class="section">
<ol>
@@ -565,7 +606,7 @@
<p>
-<em>Last Updated: September 7, 2006</em>
+<em>Last Updated: October 27, 2006</em>
</p>
</div>
Added: 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=auto&rev=469254
==============================================================================
--- db/derby/site/trunk/build/site/manuals/guidelines.html (added)
+++ db/derby/site/trunk/build/site/manuals/guidelines.html Mon Oct 30 12:04:56 2006
@@ -0,0 +1,390 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<meta content="Apache Forrest" name="Generator">
+<meta name="Forrest-version" content="0.7">
+<meta name="Forrest-skin-name" content="pelt">
+<title>Apache Derby: Writing guidelines</title>
+<link type="text/css" href="../skin/basic.css" rel="stylesheet">
+<link media="screen" type="text/css" href="../skin/screen.css" rel="stylesheet">
+<link media="print" type="text/css" href="../skin/print.css" rel="stylesheet">
+<link type="text/css" href="../skin/profile.css" rel="stylesheet">
+<script src="../skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="../skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="../skin/fontsize.js" language="javascript" type="text/javascript"></script>
+<link rel="shortcut icon" href="../">
+</head>
+<body onload="init()">
+<script type="text/javascript">ndeSetTextSize();</script>
+<div id="top">
+<div class="breadtrail">
+<a href="http://www.apache.org/">apache</a> > <a href="http://db.apache.org/">db</a><script src="../skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
+</div>
+<div class="header">
+<div class="grouplogo">
+<a href="http://db.apache.org/derby"><img class="logoImage" alt="Apache Derby" src="../images/derby-logo-web.png" title="Derby is a zero-admin Java RDBMS"></a>
+</div>
+<div class="projectlogoA1">
+<a href="http://db.apache.org"><img class="logoImage" alt="Apache DB Project" src="../images/db-logo-white.png" title="Apache DB creates and maintains database solutions."></a>
+</div>
+<ul id="tabs">
+<li>
+<a class="base-not-selected" href="../index.html">Home</a>
+</li>
+<li>
+<a class="base-not-selected" href="../quick_start.html">Quick Start</a>
+</li>
+<li>
+<a class="base-not-selected" href="../derby_downloads.html">Download</a>
+</li>
+<li>
+<a class="base-not-selected" href="../derby_comm.html">Community</a>
+</li>
+<li class="current">
+<a class="base-selected" href="../manuals/index.html">Documentation</a>
+</li>
+<li>
+<a class="base-not-selected" href="../integrate/index.html">Resources</a>
+</li>
+</ul>
+</div>
+</div>
+<div id="main">
+<div id="publishedStrip">
+<div id="level2tabs"></div>
+<script type="text/javascript"><!--
+document.write("<text>Last Published:</text> " + document.lastModified);
+// --></script>
+</div>
+<div class="breadtrail">
+
+
+ </div>
+<div id="menu">
+<div onclick="SwitchMenu('menu_selected_1.1', '../skin/')" id="menu_selected_1.1Title" class="menutitle" style="background-image: url('../skin/images/chapter_open.gif');">Documentation</div>
+<div id="menu_selected_1.1" class="selectedmenuitemgroup" style="display: block;">
+<div class="menuitem">
+<a href="../manuals/index.html">Overview</a>
+</div>
+<div class="menuitem">
+<a href="../manuals/dita.html">DITA Source</a>
+</div>
+<div class="menupage">
+<div class="menupagetitle">Writing Guidelines</div>
+</div>
+</div>
+<div class="searchbox">
+<hr>
+<form action="http://www.google.com/search" method="get">
+<input value="db.apache.org" name="sitesearch" type="hidden"><input onFocus="getBlank (this, 'Search the site with google');" size="18" name="q" id="query" type="text" value="Search the site with google">
+ <input attr="value" name="Search" value="Search" type="submit">
+</form>
+</div>
+<div id="credit"></div>
+<div id="roundbottom">
+<img style="display: none" class="corner" height="15" width="15" alt="" src="../skin/images/rc-b-l-15-1body-2menu-3menu.png"></div>
+<div id="credit2"></div>
+</div>
+<div id="content">
+<div class="trail">
+<text>Font size:</text>
+ <input value="Reset" class="resetfont" title="Reset text" onclick="ndeSetTextSize('reset'); return false;" type="button">
+ <input value="-a" class="smallerfont" title="Shrink text" onclick="ndeSetTextSize('decr'); return false;" type="button">
+ <input value="+a" class="biggerfont" title="Enlarge text" onclick="ndeSetTextSize('incr'); return false;" type="button">
+</div>
+<h1>Apache Derby: Writing guidelines</h1>
+<div id="minitoc-area">
+<ul class="minitoc">
+<li>
+<a href="#New+topics%3A+Choosing+the+correct+topic+type">New topics: Choosing the correct topic type</a>
+</li>
+<li>
+<a href="#New+topics%3A+Using+a+template+to+create+a+new+topic">New topics: Using a template to create a new topic</a>
+</li>
+<li>
+<a href="#Tagging+guidelines">Tagging guidelines</a>
+</li>
+<li>
+<a href="#Indexing+guidelines">Indexing guidelines</a>
+</li>
+</ul>
+</div>
+
+
+<p>
+The Derby documentation is sourced in DITA. The tagging used with DITA is
+similar to HTML tagging. This page contains guidelines
+for working with DITA topics and tagging.
+</p>
+
+
+<a name="N10010"></a><a name="New+topics%3A+Choosing+the+correct+topic+type"></a>
+<h2 class="boxed">New topics: Choosing the correct topic type</h2>
+<div class="section">
+<p>
+There are three types of topics used in the Derby documentation:
+concepts, reference, and tasks.
+</p>
+<p>
+
+<strong>Concept topics</strong> are overview information that answer the
+question "What is...?". They explain "why" something is important or behaves
+the way it does. Concepts provide the background information users must
+understand before they can complete the tasks successfully.
+</p>
+<p>
+
+<strong>Reference topics</strong> provide detailed information about product
+capabilities for quick reference and for completeness. Reference
+information provides quick access to facts, but no explanation of
+concepts or procedures. Examples of reference topics are the syntax
+for commands, and SQL statements, class descriptions, detailed
+examples, and troubleshooting information.
+</p>
+<p>
+
+<strong>Task topics</strong> answer the question "How do I?". Tasks typically
+include step-by-step instructions. Task topics often list (or link to)
+prerequisites that need to be completed before the user can perform
+the task. Tasks also list (or link to) any restrictions on performing
+the task.
+</p>
+</div>
+
+
+<a name="N1002C"></a><a name="New+topics%3A+Using+a+template+to+create+a+new+topic"></a>
+<h2 class="boxed">New topics: Using a template to create a new topic</h2>
+<div class="section">
+<p>When you need to create a new topic, use one of the templates that are
+included with the Derby source files. The templates are located in the
+\trunk\templates directory.
+</p>
+</div>
+
+
+<a name="N10036"></a><a name="Tagging+guidelines"></a>
+<h2 class="boxed">Tagging guidelines</h2>
+<div class="section">
+<p>The following table lists the proper tags to use for the most common
+features within the Derby topics. If you are not certain which tags to use,
+ask on the <a href="../derby_mail.html">derby-dev</a> mail list.
+</p>
+<table class="ForrestTable" cellspacing="1" cellpadding="4">
+
+
+<tr>
+
+<td colspan="1" rowspan="1"><strong>Feature</strong></td>
+ <td colspan="1" rowspan="1"><strong>Tag to use</strong></td>
+ <td colspan="1" rowspan="1"><strong>Comments</strong></td>
+
+</tr>
+
+
+<tr>
+
+<td colspan="1" rowspan="1">Index entries</td>
+ <td colspan="1" rowspan="1"><indexterm></td>
+ <td colspan="1" rowspan="1">See the section below for Indexing guidelines.</td>
+
+</tr>
+
+
+</table>
+</div>
+
+
+<a name="N1006E"></a><a name="Indexing+guidelines"></a>
+<h2 class="boxed">Indexing guidelines</h2>
+<div class="section">
+<p>
+<strong>What to index? </strong>You should index general and specific terms.
+You should look at the index entries in other topics to see what valid entries
+look like. Nesting index terms can be very useful.
+</p>
+<p>
+<strong>What tags do I use to index terms? </strong>In Derby, the index
+entries are inserted
+inside the <prolog> tag. The <prolog> tag is
+immediately after the <title> and <shortdesc> tags.
+Index entries use the <indexterm> tag, but that tag must be nested
+inside serveral other tags. For example, if the index term is CREATE TABLE and
+the topic currently does not have any index entries, the tags that you would
+need are:
+
+<prolog>
+ <metadata>
+ <keywords>
+ <indexterm>CREATE TABLE</indexterm>
+ </keywords>
+ </metadata>
+</prolog>
+
+</p>
+<p>
+If the topic already has at least one index term, then you only need to add
+the new term inside the keywords tag. For example:
+
+<indexterm>CREATE TABLE</indexterm>
+
+</p>
+<p>
+<strong>How do I add an index term? </strong> Add the <indexterm>
+tag and enter the term that you want to use. Typically you specify a general
+category of information followed by a specify term. For example, if you have
+added a new parameter called "abc", you would use "parameters" as the general
+catagory and "abc" as the specific term. The tagging for this entry is:
+</p>
+<pre class="code">
+<indexterm>parameters<indexterm>abc</indexterm></indexterm>>
+</pre>
+<p>The output appears like this:
+</p>
+<pre class="code">
+parameters
+ abc
+</pre>
+<p>
+The specific term "abc" is nested under the general term "properties". Nesting
+index terms can be very useful, when done properly. You should never nest terms
+more than 3 levels.
+</p>
+<p>
+The following examples show how to index properly.
+</p>
+<table class="ForrestTable" cellspacing="1" cellpadding="4">
+
+
+<tr>
+
+<td colspan="1" rowspan="1"><strong>Bad Indexing</strong></td>
+<td colspan="1" rowspan="1"><strong>Good Indexing</strong></td>
+<td colspan="1" rowspan="1"><strong>Explanation</strong></td>
+
+</tr>
+
+
+<tr>
+
+<td colspan="1" rowspan="1">
+
+<pre class="code">tables, constraints 16
+tables, locking 18
+tables, altering 17
+tables, temporary 16
+</pre>
+</td>
+
+<td colspan="1" rowspan="1">
+
+<pre class="code">tables
+ constraints 16
+ locking 18
+ altering 17
+ temporary 16
+</pre>
+</td>
+
+<td colspan="1" rowspan="1">The primary entry is repeated unnecessarily.
+Combine all of the secondary entries under one primary entry.</td>
+
+</tr>
+
+
+<tr>
+
+<td colspan="1" rowspan="1">
+
+<pre class="code">XML operators 21, 22, 24, 30, 32, 33
+</pre>
+
+</td>
+
+<td colspan="1" rowspan="1">
+
+<pre class="code">XML operators
+ XMLEXISTS 21, 30
+ XMLPARSE 22, 32
+ XMLQUERY 24, 33
+ XMLSERIALIZE 24, 33
+</pre>
+
+</td>
+
+<td colspan="1" rowspan="1">An entry should have no more than two page references.
+Split the entry into logical secondary entries.</td>
+
+</tr>
+
+
+<tr>
+
+<td colspan="1" rowspan="1">
+
+<pre class="code">functions
+ ACOS 70
+ ASIN 70
+ ATAN 71
+ DEGREES 81
+ FLOOR 82
+Function
+ CEIL 75
+ CEILING 75
+ LOG 86
+</pre>
+
+</td>
+
+<td colspan="1" rowspan="1">
+
+<pre class="code">functions
+ ACOS 70
+ ASIN 70
+ ATAN 71
+ CEIL 75
+ CEILING 75
+ DEGREES 81
+ FLOOR 82
+ LOG 86
+</pre>
+
+</td>
+
+<td colspan="1" rowspan="1">Entries that are capitalized and worded inconsistently
+appear as separate entries, even though they are related. Make the primary
+entries consistent (in this case, plural, non-capitalized) so that all
+of the secondary entries appear under one primary entry. </td>
+</tr>
+
+</table>
+</div>
+
+
+<p>
+Please post feedback to the
+<a href="../derby_mail.html">derby-dev</a> mail list.
+</p>
+
+
+<p>
+<em>Last Updated: October 27, 2006</em>
+</p>
+
+</div>
+<div class="clearboth"> </div>
+</div>
+<div id="footer">
+<div class="lastmodified">
+<script type="text/javascript"><!--
+document.write("<text>Last Published:</text> " + document.lastModified);
+// --></script>
+</div>
+<div class="copyright">
+ Copyright ©
+ 2004-2006 Apache Software Foundation</div>
+<div id="feedback">
+ Send feedback about the website to:
+ <a id="feedbackto" href="mailto:derby-user@db.apache.org?subject=Feedback%C2%A0manuals/guidelines.html">derby-user@db.apache.org</a>
+</div>
+</div>
+</body>
+</html>
Propchange: db/derby/site/trunk/build/site/manuals/guidelines.html
------------------------------------------------------------------------------
svn:eol-style = native
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=469254&r1=469253&r2=469254
==============================================================================
--- db/derby/site/trunk/build/site/manuals/index.html (original)
+++ db/derby/site/trunk/build/site/manuals/index.html Mon Oct 30 12:04:56 2006
@@ -68,6 +68,9 @@
<div class="menuitem">
<a href="../manuals/dita.html">DITA Source</a>
</div>
+<div class="menuitem">
+<a href="../manuals/guidelines.html">Writing Guidelines</a>
+</div>
</div>
<div class="searchbox">
<hr>
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=469254&r1=469253&r2=469254
==============================================================================
--- db/derby/site/trunk/src/documentation/content/xdocs/manuals/dita.xml (original)
+++ db/derby/site/trunk/src/documentation/content/xdocs/manuals/dita.xml Mon Oct 30 12:04:56 2006
@@ -15,7 +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: DITA-sourced documentation</title>
@@ -58,9 +58,24 @@
<code>ANT_OPTS</code> environment variable to <code>"-Xms100m -Xmx200m"</code>.
</li>
<li><p>For PDF output: Make sure to include the <code>fop.jar</code>, <code>avalon-framework-cvs-20020806.jar</code>, and <code>batik.jar</code> files located in <code>%DOC_ROOT%/trunk/lib/</code> in your <code>CLASSPATH</code> environment variable.</p></li>
-
</ol>
</section>
+
+<section>
+<title>Locating the correct DITA file</title>
+<p>The simpliest way to determine the name of the file that contains the information that you want to update is to:</p>
+<ol>
+<li><p>Go to the Derby Documentation <a href="http://db.apache.org/derby/manuals/index.html">Overiew</a> page.</p></li>
+<li><p>Under the section <strong>Latest Alpha Manuals</strong>, click the link for the HTML Pages for the manual that contains the information that you want to update.</p></li>
+<li><p>An outline of the manual topics appears on the left side of the screen. Use the outline to find the topic that you want to update.</p></li>
+<li><p>In the outline, right-click on the topic name and choose <strong>properties</strong>. The name of the file is at the top of the dialog. The address (URL) contains the path and name of the file. For example, if the address contains <code>http://db.apache.org/derby/docs/dev/getstart/cgsquck19524.html</code>, the fliename for the topic that you want to update is <strong>cgsquck19524.dita</strong></p></li>
+</ol>
+<p>
+Guidelines for writing Derby information using DITA is on the Derby Documentation
+<a href="http://db.apache.org/derby/manuals/guidelines.html">Writing Guidelines</a> page.</p>
+<p>To learn more about DITA, how to create or edit DITA files, and find more XML editors that support DITA, go to:</p><source><a href="http://dita.xml.org/">http://dita.xml.org/</a></source>
+</section>
+
<section>
<title>Editing DITA files</title>
<p>DITA is an XML specification. You can edit DITA files in any text editor, but XML editors allow you to insert and modifiy tags easily while conforming to the DITA DTD and schemas. It is HIGHLY recommended that you use an XML editor to avoid errors in tagging.</p>
@@ -71,9 +86,11 @@
<li><a href="http://xmlbuddy.com/">XML Buddy</a> (an <a href="http://www.eclipse.org/">Eclipse</a> plugin)</li>
<li><a href="http://www.altova.com">Altova XML Spy</a></li>
</ul>
-<p>
-To learn more about DITA, how to create or edit DITA files, and find more XML editors that support DITA, go to:</p><source><a href="http://dita.xml.org/">http://dita.xml.org/</a></source>
+<p>Guidelines for writing Derby information using DITA is on the Derby Documentation <a href="http://db.apache.org/derby/manuals/guidelines.html">Writing Guidelines</a> page.</p>
+
+<p>To learn more about DITA, how to create or edit DITA files, and find more XML editors that support DITA, go to:</p><source><a href="http://dita.xml.org/">http://dita.xml.org/></a></source>
</section>
+
<section>
<title>Creating output</title>
<p>To create output from the DITA source files:</p>
@@ -150,7 +167,7 @@
<title>Submitting documentation patches</title>
<p>
-<strong>Guidelines</strong>
+<strong>Contribution guidelines</strong>
</p>
<p>
If you would like to participate directly in any Derby development (including documentation changes),
@@ -322,6 +339,6 @@
</section>
-<p><em>Last Updated: September 7, 2006</em></p>
+<p><em>Last Updated: October 27, 2006</em></p>
</body>
</document>
Added: 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=auto&rev=469254
==============================================================================
--- db/derby/site/trunk/src/documentation/content/xdocs/manuals/guidelines.xml (added)
+++ db/derby/site/trunk/src/documentation/content/xdocs/manuals/guidelines.xml Mon Oct 30 12:04:56 2006
@@ -0,0 +1,237 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to you under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ 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" >
+<document>
+ <header>
+ <title>Apache Derby: Writing guidelines</title>
+ </header>
+ <body>
+
+<p>
+The Derby documentation is sourced in DITA. The tagging used with DITA is
+similar to HTML tagging. This page contains guidelines
+for working with DITA topics and tagging.
+</p>
+
+<section>
+ <title>New topics: Choosing the correct topic type</title>
+<p>
+There are three types of topics used in the Derby documentation:
+concepts, reference, and tasks.
+</p>
+<p>
+<strong>Concept topics</strong> are overview information that answer the
+question "What is...?". They explain "why" something is important or behaves
+the way it does. Concepts provide the background information users must
+understand before they can complete the tasks successfully.
+</p>
+<p>
+<strong>Reference topics</strong> provide detailed information about product
+capabilities for quick reference and for completeness. Reference
+information provides quick access to facts, but no explanation of
+concepts or procedures. Examples of reference topics are the syntax
+for commands, and SQL statements, class descriptions, detailed
+examples, and troubleshooting information.
+</p>
+<p>
+<strong>Task topics</strong> answer the question "How do I?". Tasks typically
+include step-by-step instructions. Task topics often list (or link to)
+prerequisites that need to be completed before the user can perform
+the task. Tasks also list (or link to) any restrictions on performing
+the task.
+</p>
+</section>
+
+<section>
+<title>New topics: Using a template to create a new topic</title>
+<p>When you need to create a new topic, use one of the templates that are
+included with the Derby source files. The templates are located in the
+\trunk\templates directory.
+</p>
+</section>
+
+<section>
+<title>Tagging guidelines</title>
+<p>The following table lists the proper tags to use for the most common
+features within the Derby topics. If you are not certain which tags to use,
+ask on the <a href="../derby_mail.html">derby-dev</a> mail list.
+</p>
+<table>
+
+ <tr>
+ <td><strong>Feature</strong></td>
+ <td><strong>Tag to use</strong></td>
+ <td><strong>Comments</strong></td>
+ </tr>
+
+ <tr>
+ <td>Index entries</td>
+ <td><![CDATA[<indexterm>]]></td>
+ <td>See the section below for Indexing guidelines.</td>
+ </tr>
+
+</table>
+</section>
+
+<section>
+<title>Indexing guidelines</title>
+<p><strong>What to index? </strong>You should index general and specific terms.
+You should look at the index entries in other topics to see what valid entries
+look like. Nesting index terms can be very useful.
+</p>
+
+<p><strong>What tags do I use to index terms? </strong>In Derby, the index
+entries are inserted
+inside the <![CDATA[<prolog>]]> tag. The <![CDATA[<prolog>]]> tag is
+immediately after the <![CDATA[<title>]]> and <![CDATA[<shortdesc>]]> tags.
+Index entries use the <![CDATA[<indexterm>]]> tag, but that tag must be nested
+inside serveral other tags. For example, if the index term is CREATE TABLE and
+the topic currently does not have any index entries, the tags that you would
+need are:
+<![CDATA[
+<prolog>
+ <metadata>
+ <keywords>
+ <indexterm>CREATE TABLE</indexterm>
+ </keywords>
+ </metadata>
+</prolog>
+]]>
+</p>
+<p>
+If the topic already has at least one index term, then you only need to add
+the new term inside the keywords tag. For example:
+<![CDATA[
+<indexterm>CREATE TABLE</indexterm>
+]]>
+</p>
+
+<p><strong>How do I add an index term? </strong> Add the <![CDATA[<indexterm>]]>
+tag and enter the term that you want to use. Typically you specify a general
+category of information followed by a specify term. For example, if you have
+added a new parameter called "abc", you would use "parameters" as the general
+catagory and "abc" as the specific term. The tagging for this entry is:
+</p>
+<source>
+<![CDATA[<indexterm>]]>parameters<![CDATA[<indexterm>]]>abc<![CDATA[</indexterm>]]><![CDATA[</indexterm>]]>>
+</source>
+<p>The output appears like this:
+</p>
+<source>
+parameters
+ abc
+</source>
+<p>
+The specific term "abc" is nested under the general term "properties". Nesting
+index terms can be very useful, when done properly. You should never nest terms
+more than 3 levels.
+</p>
+<p>
+The following examples show how to index properly.
+</p>
+
+<table>
+
+<tr>
+<td><strong>Bad Indexing</strong></td>
+<td><strong>Good Indexing</strong></td>
+<td><strong>Explanation</strong></td>
+</tr>
+
+<tr>
+<td>
+<source>tables, constraints 16
+tables, locking 18
+tables, altering 17
+tables, temporary 16
+</source></td>
+
+<td>
+<source>tables
+ constraints 16
+ locking 18
+ altering 17
+ temporary 16
+</source> </td>
+
+<td>The primary entry is repeated unnecessarily.
+Combine all of the secondary entries under one primary entry.</td>
+</tr>
+
+<tr>
+<td>
+<source>XML operators 21, 22, 24, 30, 32, 33
+</source>
+</td>
+
+<td>
+<source>XML operators
+ XMLEXISTS 21, 30
+ XMLPARSE 22, 32
+ XMLQUERY 24, 33
+ XMLSERIALIZE 24, 33
+</source>
+</td>
+
+<td>An entry should have no more than two page references.
+Split the entry into logical secondary entries.</td>
+</tr>
+
+<tr>
+<td>
+<source>functions
+ ACOS 70
+ ASIN 70
+ ATAN 71
+ DEGREES 81
+ FLOOR 82
+Function
+ CEIL 75
+ CEILING 75
+ LOG 86
+</source>
+</td>
+
+<td>
+<source>functions
+ ACOS 70
+ ASIN 70
+ ATAN 71
+ CEIL 75
+ CEILING 75
+ DEGREES 81
+ FLOOR 82
+ LOG 86
+</source>
+</td>
+
+<td>Entries that are capitalized and worded inconsistently
+appear as separate entries, even though they are related. Make the primary
+entries consistent (in this case, plural, non-capitalized) so that all
+of the secondary entries appear under one primary entry. </td></tr>
+</table>
+</section>
+
+<p>
+Please post feedback to the
+<a href="../derby_mail.html">derby-dev</a> mail list.
+</p>
+
+<p><em>Last Updated: October 27, 2006</em></p>
+</body>
+</document>
Propchange: db/derby/site/trunk/src/documentation/content/xdocs/manuals/guidelines.xml
------------------------------------------------------------------------------
svn:eol-style = native
Modified: db/derby/site/trunk/src/documentation/content/xdocs/site.xml
URL: http://svn.apache.org/viewvc/db/derby/site/trunk/src/documentation/content/xdocs/site.xml?view=diff&rev=469254&r1=469253&r2=469254
==============================================================================
--- db/derby/site/trunk/src/documentation/content/xdocs/site.xml (original)
+++ db/derby/site/trunk/src/documentation/content/xdocs/site.xml Mon Oct 30 12:04:56 2006
@@ -54,6 +54,7 @@
<manuals label="Documentation" href="manuals/" tab="docs">
<index label="Overview" href="index.html"/>
<ditafile label="DITA Source" href="dita.html" />
+ <ditaguid label="Writing Guidelines" href="guidelines.html" />
</manuals>
<integrate label="Other Products" href="integrate/" tab="resources">