You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by ml...@apache.org on 2010/10/23 19:44:14 UTC
svn commit: r1026654 - /trafficserver/site/trunk/docs/v2/README.html
Author: mlibbey
Date: Sat Oct 23 17:44:14 2010
New Revision: 1026654
URL: http://svn.apache.org/viewvc?rev=1026654&view=rev
Log:
Some instructions about how to edit the documenation
Added:
trafficserver/site/trunk/docs/v2/README.html
Added: trafficserver/site/trunk/docs/v2/README.html
URL: http://svn.apache.org/viewvc/trafficserver/site/trunk/docs/v2/README.html?rev=1026654&view=auto
==============================================================================
--- trafficserver/site/trunk/docs/v2/README.html (added)
+++ trafficserver/site/trunk/docs/v2/README.html Sat Oct 23 17:44:14 2010
@@ -0,0 +1,58 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
+ "http://www.w3.org/TR/html4/loose.dtd">
+
+<html lang="en">
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+ <title>Administering the Apache Traffic Server Documentation and Site</title>
+</head>
+<body>
+
+
+The Apache Traffic Server Administration and SDK Guide documentation are located in
+<br><a href="http://svn.apache.org/viewvc/trafficserver/site/trunk/docs/v2/">/trafficserver/site/trunk/docs/v2/</a>(<a href="http://svn.apache.org/viewvc/trafficserver/site/trunk/docs/v2/admin/">admin</a>|<a href="http://svn.apache.org/viewvc/trafficserver/site/trunk/docs/v2/sdk/">sdk</a>)/.<br>
+The site pages are located in <a href="http://svn.apache.org/viewvc/trafficserver/site/">/trafficserver/site/</a>. These sections are in HTML, thus, it's recommended to use a WSYIWYG html editor to edit the pages. All pages use svn pubsub. A few seconds after committing, the pages should be live on the site.
+
+<ul>
+<li><a href="#Admin_guide">The Admin Guide</a></li>
+<li><a href="#SDK_guide">The SDK Guide</a></li>
+<li><a href="#Search">Search</a></li>
+<li><a href="#Site">Site</a></li>
+</ul>
+
+<h1 id="Admin_guide">The Admin Guide</h1>
+ <ul>
+ <li>The files use SSI to include 2 files: <a href="http://svn.apache.org/viewvc/trafficserver/site/trunk/docs/v2/admin/top.html">top.html</a>, which has the logo, search box, css links, and a <a href="http://svn.apache.org/viewvc/trafficserver/site/trunk/docs/v2/admin/bottom.html">bottom.html</a>, which has the left navigation and footer. Thus, if you change those files, all the other files will get the changes automatically.</li>
+ <li>There is a <a href="http://svn.apache.org/viewvc/trafficserver/site/trunk/docs/v2/admin/template.html">template file</a> for new files. After a new file is added, add he appropriate link to the <a href="http://svn.apache.org/viewvc/trafficserver/site/trunk/docs/v2/admin/bottom.html">bottom.html</a> navigation list.</li>
+ <li>Because the files use SSI, they need to be committed as executable. This can be achieved with the <code>svn propset svn:executable ON $filename</code> command.</li>
+ <li>Generally, the markup is semantic. Section titles use header tags (h1, h2, h3, etc, depending on the level). Paragraphs are surrounded by "p" tags. Whenever commands or code is shown, they are surrounded by "code" tags.</li>
+ <li>Generally, each file has a list of sections at the top. Thus, when creating high level sections, it's preferable to give the header tag a unique id, and add a link in the list at the top of the file. By linking to the id, prefaced by a hash (for instance, <code>#Admin_guide</code>), users can click down to the section.</li>
+ <li>The page layout is done via CSS, using <a href="http://developer.yahoo.com/yui/grids/builder/">YUI grids</a>. Using the grid builder, the body is set to 100%, with a left 300px side column. </li>
+ </ul>
+
+
+<h1 id="SDK_guide">The SDK Guide</h1>
+ <ul>
+ <li>The SDK guide was originally generated by a script converting a Adobe FrameMaker file, and thus has rather verbose and odd html code. Feel free to remove extraneous markup.</li>
+ <li>The files use SSI to include a <a href="http://svn.apache.org/viewvc/trafficserver/site/trunk/docs/v2/sdk/top.html">top.html</a>, which has the logo, search box, css links, and javascript links. Thus, if you change those files, all the other files will get the changes automatically.</li>
+ <li>Because the files use SSI, they need to be committed as executable. This can be achieved with the <code>svn propset svn:executable ON $filename</code> command.</li>
+ <li>The left navigation is created by the javascript <a href="http://svn.apache.org/viewvc/trafficserver/site/trunk/docs/v2/sdk/js/tocnodes.js">tocnodes.js</a> and is placed in the "<div id="toc"></div>". To add a new left navigation item, edit this file, and add a new line:<br>
+ <code>var $newnumber = new YAHOO.widget.TextNode({ label: "Title to display", href: "$filename.html" }, $variable_name_of_parent, false);</code>.<br>To date, the $newnumber has ben in a format of n+number, for instance, n23. The numbers do no need to be in order -- n502 could be listed in between n23 and n24. As of this writing, they are listed in order because we have not added new files to any section. The <code>$variable_name_of_parent</code> is the variable name of the node you'd like the new file to appear under. If the new file should be a top level node, use "root". Thus<br><code>var n488 = new YAHOO.widget.TextNode({ label: "C. Troubleshooting Tips", href: "App_Troubleshooting.html" }, root, false);</code><br>will appear as a top level node, will be labeled as "C. Troubleshooting Tips", and will link to App_Troubleshooting.html. While, <br><code>var n169 = new YAHOO.widget.TextNode({ label: "INKThreadDestroy", href: "INKThreadDestroy.html" }, n167, false)
;</code><br> will appear under n167 ("Thread Functions"). Several nodes are commented out as they appear to no longer be useful.</li>
+ <li>The code is littered with odd, unique ids (for instance, <code><a name="id306665"></a></code>) as a result of the conversion. To clean these, search and replace the other documentation files for the unique string ("id306665" in this example). </li>
+
+ </ul>
+<h1 id="Search">Search</h1>
+ <ul>
+ <li>Search is done via a <a href="http://www.google.com/cse/">custom Google search</a>. Its set to search http://www.mail-archive.com/users@trafficserver.apache.org/, http://www.mail-archive.com/trafficserver-user@incubator.apache.org/, https://cwiki.apache.org/confluence/display/TS/, and http://trafficserver.apache.org/docs/v2/. </li>
+ <li>Search results are served on <a href="http://svn.apache.org/viewvc/trafficserver/site/trunk/docs/search.html">/trafficserver/site/trunk/docs/search.html</a></li>
+
+ </ul>
+<h1 id="Site">Site</h1>
+ <ul>
+ <li>The site pages use SSI to include the <a href="http://svn.apache.org/viewvc/trafficserver/site/trunk/top.html">top.html</a> and <a href="http://svn.apache.org/viewvc/trafficserver/site/trunk/footer.html">footer.html</a> files, which have the css, navigation bar, and copyright/trademark sections. </li>
+ <li>There is a <a href="http://svn.apache.org/viewvc/trafficserver/site/trunk/template.html">template file</a> for new files. The template file has some examples of different section layouts (2 column, 3 columns).</li>
+ <li>If you want to create a different column layout, use <a href="http://developer.yahoo.com/yui/grids/builder/">YUI grid builder</a>. Choose body size=974; 1 body column; then go nuts adding rows, and splitting them into different columns sizes. Just copy over the rows you create. </li>
+
+ </ul>
+</body>
+</html>