From 80e080799c7539d58c4e3839c0e49eb07d7a39f2 Mon Sep 17 00:00:00 2001
From: David Anderson <davea@ssl.berkeley.edu>
Date: Thu, 15 Jun 2006 20:32:27 +0000
Subject: [PATCH] *** empty log message ***

svn path=/trunk/boinc/; revision=10363
---
 doc/files.php | 25 +++++++++++++++++++++----
 doc/xml.php   | 44 +++++++++++++++++++++++++-------------------
 2 files changed, 46 insertions(+), 23 deletions(-)

diff --git a/doc/files.php b/doc/files.php
index 609bbbb5bf..ef94195088 100644
--- a/doc/files.php
+++ b/doc/files.php
@@ -7,8 +7,10 @@ echo "
 The BOINC storage model is based on <b>files</b>.
 Examples of files:
 <ul>
-<li> The inputs and outputs of applications;
-<li> Application executables, libraries, etc.
+<li> The inputs and/or outputs of computation;
+<li> Components of application: executables, libraries, etc.
+<li> Data for its own sake,
+e.g. to implement a distributed storage system.
 </ul>
 <p>
 The BOINC core client transfers files to and from project-operated
@@ -16,12 +18,27 @@ The BOINC core client transfers files to and from project-operated
 <p>
 Once a file is created (on a data server or a participant host) it
 is <b>immutable</b>.
-This means that all replicas of that file are assumed to be identical.
+This means that all replicas of that file are assumed (and required) to be identical.
+
+<h3>File properties</h3>
+Files have various <b>properties</b>, including:
+<ul>
+<li> <b>Sticky</b>: don't delete file on client (see below).
+<li> <b>Report on RPC</b>: include a description of this file
+in scheduler requests.
+<li> <b>Maximum size</b>: if an output file exceeds its maximum size,
+the computation is aborted.
+</ul>
+File properties are specified in XML.
+For example, the properties of input files are described in
+the <a href=tools_work.php>workunit template</a>,
+and XML document describing the task.
+The XML format is described <a href=xml.php>here</a>.
 
 <a name=file_ref></a>
 <h3>File management</h3>
 <p>
-BOINC's default behavior is to delete files around
+BOINC's default behavior is to delete files
 when they aren't needed any more.
 Specifically:
 <ul>
diff --git a/doc/xml.php b/doc/xml.php
index b521e91888..f73d9d583c 100644
--- a/doc/xml.php
+++ b/doc/xml.php
@@ -5,11 +5,12 @@ echo "
 BOINC uses XML to describe various entities.
 These XML elements appear in:
 <ul>
-<li> The BOINC DB
-<li> Scheduler request and reply messages
-<li> The client state file
-<li> GUI RPCs
+<li> <a href=database.php>The BOINC database</a>
+<li> <a href=protocol.php>Scheduler request and reply messages</a>
+<li> <a href=client_files.php>The client state file</a>
+<li> <a href=gui_rpc.php>GUI RPCs</a>
 </ul>
+Generally, these XML elements are generated by BOINC.
 Some of these XML elements are described here
 (not all fields are present in all contexts).
 <a name=file></a>
@@ -18,23 +19,25 @@ Some of these XML elements are described here
 A file is described by an XML element of the form 
 ".html_text("
 <file_info>
-    <name>foobar</name>
+    <name>foobar</name> *
     <url>http://a.b.c/foobar</url>
     <url>http://x.y.z/foobar</url>
     ...
     <md5_cksum>123123123123</md5_cksum>
     <nbytes>134423</nbytes>
-    <max_nbytes>200000</max_nbytes>
+    <max_nbytes>200000</max_nbytes> *
     <status>1</status>
     [ <generated_locally/> ]
     [ <executable/> ]
     [ <upload_when_present/> ]
-    [ <sticky/> ]
+    [ <sticky/> * ]
     [ <signature_required/> ]
-    [ <no_delete/> ]
-    [ <report_on_rpc/> ]
+    [ <no_delete/> * ]
+    [ <report_on_rpc/> * ]
 </file_info>
 ")."
+The elements marked with an asterisk are specified by the project;
+the others are generated automatically by BOINC.
 The elements are as follows:
 ";
 list_start();
@@ -54,17 +57,19 @@ list_item("nbytes",
     "the size of the file in bytes."
 );
 list_item("max_nbytes",
-    "The maximum allowable size of the file in bytes (may be greater than 2^32).
+    "For output files,
+	the maximum allowable size of the file in bytes
+	(as a double; may be greater than 2^32).
     This is used to prevent flooding data servers with bogus data."
 );
 list_item("status",
-    "0 if the file is not present,
-    1 if the file is present, or a negative error code if there was a
+    "On the client: 0 if the file is not present;
+    1 if the file is present; a negative error code if there was a
     problem in downloading or generating the file."
 );
 list_item("generated_locally",
-    "If present, indicates that the file will be generated by an application on
-    the client, as opposed to being downloaded."
+    "If present, indicates that the file will be generated on the client,
+	rather than downloaded."
 );
 list_item("executable",
     "If present, indicates that the file protections should be set to allow
@@ -90,14 +95,15 @@ list_item("signature_required",
 );
 list_item("no_delete",
     "If present for an input (workunit) file,
-    indicates that the file should NOT be removed from the data server's
+    indicates that the file should not be removed from the data server's
     download directory when the workunit is completed.
-    Use this if a particular input file or files are used by more than one
-    workunit, or will be used by future workunits.
+    Use this if a file is used by more than one workunit,
+	or will be used by future workunits.
     <p>
     If present for an output (result) file,
-    indicates that the file should NOT be removed from the data server's upload
-    directory when the corresponding workunit is completed.
+    indicates that the file should not be removed from the data server's upload
+    directory,
+	even when the corresponding workunit is completed and assimilated.
     Use with caution - this may cause your upload directory to overflow."
 );
 list_item("report_on_rpc",