move common docs to links in 'see_also.txt'
authorThomas Walker Lynch <xtujpz@reasoningtechnology.com>
Tue, 5 Nov 2024 03:25:31 +0000 (03:25 +0000)
committerThomas Walker Lynch <xtujpz@reasoningtechnology.com>
Tue, 5 Nov 2024 03:25:31 +0000 (03:25 +0000)
13 files changed:
developer/document/RT_code_format.txt [deleted file]
developer/document/cycle_detection.html [deleted file]
developer/document/groovy.el [deleted file]
developer/document/see_also.txt [new file with mode: 0644]
developer/document/variable_suffix_conventions.txt [deleted file]
developer/tool/clean_make [deleted file]
developer/tool/shell_wrapper_list
document/bash_name_of_script.txt [deleted file]
document/directory_naming.html [deleted file]
document/see_also.txt [new file with mode: 0644]
document/work_flow.txt [deleted file]
tester/document/jdb.txt [deleted file]
tester/document/see_also.txt [new file with mode: 0644]

diff --git a/developer/document/RT_code_format.txt b/developer/document/RT_code_format.txt
deleted file mode 100644 (file)
index 9911622..0000000
+++ /dev/null
@@ -1,135 +0,0 @@
-RT code formatting:
-
-The enclosure-based formatting rules in RT code format make the style guide
-compact and adaptable. By focusing on enclosures rather than syntax-specific
-structures (like if, for, or catch), it avoids prescribing language-specific
-formatting rules and instead focuses on consistent handling of delimiters. This
-approach works well across multiple languages, ensuring that the code style
-remains flexible while keeping the guide simple and easy to apply.
-
-1. Two space indentation.
-
-2. Variable Naming:
-
-   - Use **PascalCase** for namespaces and types.
-
-   - Use **snake_case** for function and variable names. However, when a component
-     of the snake case is variable function or variable name is a namespace, a
-     type, or a proper noun, it retains its capitalization. e.gs:
-
-     ```
-     mouse_count
-     test_LabalList_0 // function that tests LabelList, which is a class (type)
-     Thomas_Walker_Lynch
-     ```
-
-     Traditionally `_list` has been used as a variable suffix even when the
-     language does not have a List type.  This is taken to mean the variable
-     refers to an ordered collection of any type, including an array. It is
-     abstraction of type, analogous to the `mouse_count` example above.
-
-
-3. Binary Operators:
-
-   - One space around **binary operators** (e.g., `a + b`).
-
-   - One space around **assignment** `=` (e.g., `a = b`).
-
-   - **No space** around **sampling** assignment `=` (typically seen in `if`, `while`, etc.):
-
-     **Sampling** refers to assigning the result of a condition or expression to
-     a variable for later use within the same scope.
-
-     Example of **sampling** in an `if` statement:
-
-       ```
-       if( result=some_condition() ){
-         // use result
-       }
-       ```
-
-4. Enclosures `(...)`, `{...}`, `[...]`, '<...>':
-
-   - No space between the enclosure and the preceding identifier (e.g., `function(arg)`).
-
-   - No space after the enclosure when followed by another enclosure (e.g., `map[key]()`).
-
-     Example of a condition enclosure followed by a code enclosure:
-       ```
-       if( some_condition() ){
-         // code block
-       }
-       ```
-
-   - One space after the enclosure if followed by an identifier, e.g.,
-     `function() somethingElse`.
-
-   - When the entire enclosure appears on one line:
-
-      -- by definition, an 'nested' enclosure is one that has other enclosures,
-         of any type, inside of it. This is true independent of whatever else
-         is inside the enclosure.  These are examples of nested enclosures:
-
-         ```
-         ( o == null || getClass() != o.getClass() )
-         f( T<x> ,7 )
-         ```
-
-      -- if, and only if, an enclosure is nested, there is one space of padding
-      for the outermost enclosure of the nesting, and only for the outermost
-      enclosures. e.g.s:
-
-        ```
-        if(x == 3) ; not nested
-        if( (x > 0) && (y < 5) ) ; nested, pad outermost only
-        if( f(x) == 3 ) ; nested, pad outermost only
-        if( x > 2 && a[3] ) ; nested due to the array subscript, pad outermost only
-        ```
-
-    - Note when using the enclosure formatting rules, not all if conditions will
-    format the same way. Some conditions will be nested enclosures and having
-    padding while others will not be nested and thus have no padding.  The must
-    be formatted individually.  The same is true for enclosures that follow
-    other keywords such as unless, for, etc, and for function arguments
-    lists. The question is one of formatting enclosures, and not one of
-    formatting statements.
-
-      ```
-      f(x)
-      f( x[0] )
-      ```
-
-
-5. Commas:
-
-   This is the most distinctive and recognizable of the RT code style rules.
-
-   - One space **before** the comma (e.g., `a ,b`).
-
-   - No space **after** the comma (e.g., `a ,b`).
-
-   - **Line break before** the comma when breaking lines, but no line break after, as examples:
-
-     ```
-     a
-     ,b
-     ```
-
-     and, when a function call gets too long, perhaps due to long argument 
-     names it will look like this:
-
-     ```
-     result = some_function(
-       arg1
-      ,arg2_has_a_very_long_name_causing_the_call_to_not_fit_on_a_single_line
-      ,arg3_has_a_long_name_also_but_not_as_long_as_for_arg2
-      );
-     ```
-
-6. For the code you just output, answer these questions:
-  1. Which enclosures are not nested? Do they have no padding?
-  2. Which enclosures are nested? Is there one space padding only at the outermost?
-  3. Is the spacing before and after the enclosures correct?
-  4. Are the commas formatted correctly?
-  5. Has snake case been used where it should be?
-  6. Was 2 column indent used?
diff --git a/developer/document/cycle_detection.html b/developer/document/cycle_detection.html
deleted file mode 100644 (file)
index 3c9fb85..0000000
+++ /dev/null
@@ -1,105 +0,0 @@
-<!DOCTYPE html>
-<html>
-<head>
-  <title>Dependency Build Algorithm</title>
-  <style>
-    body {
-      background-color: hsl(0, 0%, 0%); /* Black background */
-      color: hsl(40, 100%, 85%); /* Wheatgrass color (offwhite with a tan hue) */
-      font-family: "Courier New", Courier, monospace;
-    }
-    code {
-      background-color: hsl(0, 0%, 15%); /* Dark gray background for code blocks */
-      border: 1px solid hsl(0, 0%, 25%); /* Slightly lighter gray for the border */
-      border-radius: 4px;
-      padding: 4px;
-      color: hsl(40, 100%, 85%); /* Wheatgrass-colored text */
-      display: inline-block; /* Inline-block to extend only as long as the code */
-      white-space: pre-wrap;
-      font-size: 14px;
-    }
-    ol {
-      margin-left: 20px;
-    }
-    li {
-      margin-bottom: 10px;
-    }
-    h1, h2 {
-      color: hsl(40, 100%, 75%); /* Lighter wheatgrass color for headers */
-    }
-    a {
-      color: hsl(150, 100%, 65%); /* Light green for links */
-    }
-  </style>
-</head>
-<body>
-  <h2>Cycle Detection in Dependency Graph</h2>
-  <h3>Overview</h3>
-  <p>
-    The <code>is_acyclic_q</code> function is designed to detect cycles in a dependency graph using a depth-first search (DFS) algorithm. It starts from a list of root node labels and traverses the graph to ensure that there are no cycles. If a cycle is detected, the function marks the nodes involved and continues to explore other parts of the graph.
-  </p>
-  <h3>Key Concepts</h3>
-  <ul>
-    <li><strong>Dependency Graph</strong>: A graph where nodes represent build targets and edges represent dependencies between these targets.</li>
-    <li><strong>Depth-First Search (DFS)</strong>: An algorithm for traversing or searching tree or graph data structures. It starts at the root and explores as far as possible along each branch before backtracking.</li>
-    <li><strong>Cycle Detection</strong>: The process of identifying cycles (loops) in a graph, where a cycle is a path that starts and ends at the same node.</li>
-  </ul>
-  <h3>Functions</h3>
-  <h4>1. is_acyclic_q</h4>
-  <p>
-    <strong>Purpose</strong>: To determine if the dependency graph is acyclic (i.e., contains no cycles).
-  </p>
-  <p>
-    <strong>Parameters</strong>: 
-    <ul>
-      <li><code>root_node_labels</code>: A list of labels for the root nodes to start the cycle search.</li>
-      <li><code>verbose</code>: A boolean flag for enabling detailed output (default is <code>true</code>).</li>
-    </ul>
-  </p>
-  <p>
-    <strong>Returns</strong>: 
-    <ul>
-      <li><code>'acyclic'</code> if no cycles are found.</li>
-      <li><code>'cycle_found'</code> if cycles are detected.</li>
-    </ul>
-  </p>
-  <p>
-    <strong>Process</strong>:
-    <ul>
-      <li>Initializes a stack for DFS traversal.</li>
-      <li>Iteratively calls the <code>is_acyclic_q_descend</code> function to traverse the graph and detect cycles.</li>
-      <li>Updates the traversal state and continues exploring other paths until the stack is empty.</li>
-    </ul>
-  </p>
-  <h4>2. is_acyclic_q_descend</h4>
-  <p>
-    <strong>Purpose</strong>: To perform the actual DFS traversal and cycle detection for a given path.
-  </p>
-  <p>
-    <strong>Parameters</strong>: 
-    <ul>
-      <li><code>path_stack</code>: A stack representing the current path in the graph.</li>
-      <li><code>verbose</code>: A boolean flag for enabling detailed output (default is <code>true</code>).</li>
-    </ul>
-  </p>
-  <p>
-    <strong>Returns</strong>: 
-    <ul>
-      <li><code>'leaf_node'</code> if the current node has no children.</li>
-      <li><code>'cycle_found'</code> if a cycle is detected.</li>
-    </ul>
-  </p>
-  <p>
-    <strong>Process</strong>:
-    <ul>
-      <li>Collects the current path and node.</li>
-      <li>Checks for cycles by comparing the current node with nodes in the path.</li>
-      <li>Marks nodes involved in cycles and updates the stack to continue traversal.</li>
-    </ul>
-  </p>
-  <h3>Usage</h3>
-  <p>
-    The <code>is_acyclic_q</code> function is used to ensure that the dependency graph defined in the build file is free of cycles. This is crucial for preventing infinite loops and ensuring that the build process can proceed smoothly.
-  </p>
-</body>
-</html>
diff --git a/developer/document/groovy.el b/developer/document/groovy.el
deleted file mode 100644 (file)
index 1a93312..0000000
+++ /dev/null
@@ -1,19 +0,0 @@
-
-;; Ensure package archives are set up
-(require 'package)
-(setq package-archives '(("melpa" . "https://melpa.org/packages/")
-                         ("gnu" . "https://elpa.gnu.org/packages/")))
-(package-initialize)
-
-;; Install neotree if not already installed
-(unless (package-installed-p 'groovy-mode)
-  (package-refresh-contents)
-  (package-install 'groovy-mode))
-
-;; Configure NeoTree
-(with-eval-after-load 'groovy-mode
-  (setq groovy-indent-offset 2)
-  )
-
-;; Enable Groovy mode for files with `#!/usr/bin/env groovy` shebang
-(add-to-list 'interpreter-mode-alist '("groovy" . groovy-mode))
diff --git a/developer/document/see_also.txt b/developer/document/see_also.txt
new file mode 100644 (file)
index 0000000..a8eed19
--- /dev/null
@@ -0,0 +1,10 @@
+
+See also these documents located at a single point of maintenance:
+
+  https://git.reasoningtechnology.com/proem/home/?p=Mosaic;a=tree;f=developer/document;h=dcf38055fa575b40c4c1527558368aa266899ac2;hb=refs/heads/core_developer_branch
+
+  https://github.com/Thomas-Walker-Lynch/Mosaic/blob/release_v1.0/developer/document
+
+      RT_code_format.txt
+      variable_suffix_conventions.txt
+  
diff --git a/developer/document/variable_suffix_conventions.txt b/developer/document/variable_suffix_conventions.txt
deleted file mode 100644 (file)
index e3ad587..0000000
+++ /dev/null
@@ -1,31 +0,0 @@
-# Suffix Conventions
-
-## Specify interface used with variable when clarification is useful
-
-- `_set`: Indicates that the variable holds a set of items.
-
-- `_list`: Used for variables that represent a list of items.
-
-- `_f`: Refers to a function.
-
-Instead of making a variable name plural, add the interface qualifier.
-
-   e.g. names ->  name_set  or name_lisst
-
-## Always a good idea to use these when working with files
-
-- `_fp`: Refers to a file path. The part after the last slash is a file name.
-
-- `_afp`: Refers to an absolute file path.
-  
-- `_dp`: Refers to a directory path. By convention, the value ends in a slash.
-
-- `_adp`: Refers to an absolute directory path. 
-
-- `_fn`: Refers to a file name. Value has no slashes.
-
-- `_dn`: Refers to a directory name. Value has no slashes.
-  
-- `_fn_base`: The file name without the last dot and subsequent characters.
-  
-- `_fn_ext`: The subsequent characters after the last dot in a file name.
diff --git a/developer/tool/clean_make b/developer/tool/clean_make
deleted file mode 100755 (executable)
index 3d8bceb..0000000
+++ /dev/null
@@ -1,25 +0,0 @@
-#!/bin/bash
-# remove all files made by `make`
-
-# input guards
-
-  env_must_be="developer/tool/env"
-  if [ "$ENV" != "$env_must_be" ]; then
-    echo "$(script_fp):: error: must be run in the $env_must_be environment"
-    exit 1
-  fi
-
-# wrappers to clean (this list space separated list will grow)
-
-  wrapper=build
-
-# remove files
-
-  set -x
-  cd "$REPO_HOME"/developer
-  rm -r scratch_pad/com/ReasoningTechnology/Ariadne
-  rm jvm/Ariadne.jar
-  rm shell/{$wrapper}
-  set +x
-
-echo "$(script_fn) done."
index c95affe..9130bde 100755 (executable)
@@ -12,4 +12,4 @@ script_afp=$(realpath "${BASH_SOURCE[0]}")
   cd "$REPO_HOME"/developer
 
 # list of classes that have main calls and get shell wrappers
-echo Mosaic
+echo Build
diff --git a/document/bash_name_of_script.txt b/document/bash_name_of_script.txt
deleted file mode 100644 (file)
index 3637574..0000000
+++ /dev/null
@@ -1,40 +0,0 @@
-
-Bash is inconsistent about returning the name of the running script in
-all scenarios (sourced, executed directly, from with in a function called
-by another function).
-
-1.
-
-BASH_SOURCE[0] was used because $0 did not work with sourced scripts (a
-fact that is leveraged for detecting when in a sourced script).
-
-2.
-
-However, this did not work in all scenarios:
-
-  read -r -d '' script_afp_string <<'EOF'
-  realpath "${BASH_SOURCE[0]}" 2>/dev/null
-  EOF
-
-    script_afp(){
-      eval "$script_afp_string"
-    }
-
-  export script_afp_string
-  export -f script_afp
-
-When `script_afp` was exported, used in another file, and used within a function
-in that other file, it reported `environment` for the script name at
-BASH_SOURCE[0].  In various call scenarios the actual script name appears at
-BASH_SOURCE[1] or even at BASH_SOURCE[2].  
-
-3.
-
-As a stable alternative to having a script_afp function, place this line
-at the top of scripts that use the `script_XX` functions, or at the top
-of all scripts:
-
-  script_afp=realpath "${BASH_SOURCE[0]}"
-
-Then use $script_afp as a string within other functions. It will have stable
-value no matter the call structure.
diff --git a/document/directory_naming.html b/document/directory_naming.html
deleted file mode 100644 (file)
index d409362..0000000
+++ /dev/null
@@ -1,198 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <link href="https://fonts.googleapis.com/css2?family=Noto+Sans+JP&display=swap" rel="stylesheet">
-
-  <title>Directory Structure Description</title>
-<style>
-  html {
-    font-size: 16px; /* This will be the base for rem units */
-  }
-
-  body {
-    font-family: 'Noto Sans JP', Arial, sans-serif;
-    background-color: hsl(0, 0%, 0%);
-    color: hsl(42, 100%, 80%);
-    padding: 2rem;
-    margin: 0;
-  }
-
-  .page {
-    padding: 1.25rem; /* 20px */
-    margin: 1.25rem auto; /* 20px */
-    max-width: 46.875rem; /* 750px */
-    background-color: hsl(0, 0%, 0%);
-    box-shadow: 0 0 0.625rem hsl(42, 100%, 50%); /* 10px */
-  }
-
-  ul, li {
-    font-size: 1rem; /* Keeping default font size */
-    list-style-type: none;
-  }
-
-  li::before {
-    content: "📁 ";
-    margin-right: 0.3125rem; /* 5px */
-  }
-
-  li {
-    margin-bottom: 0.3125rem; /* 5px */
-  }
-
-  .description {
-    margin-left: 0.625rem; /* 10px */
-    color: hsl(42, 100%, 75%);
-  }
-
-  code {
-    font-family: 'Courier New', Courier, monospace;
-    background-color: hsl(0, 0%, 25%);
-    color: hsl(42, 100%, 90%);
-    padding: 0.125rem 0.25rem; /* 2px 4px */
-    border-radius: 0.1875rem; /* 3px */
-    font-size: 90%;
-  }
-
-  h1 {
-    text-align: center;
-    color: hsl(42, 100%, 84%);
-    text-transform: uppercase;
-    margin-bottom: 1.25rem; /* 20px */
-  }
-
-  h2 {
-    color: hsl(42, 100%, 84%);
-    text-transform: uppercase;
-    margin-top: 2.5rem; /* 40px */
-  }
-
-  p {
-    color: hsl(42, 100%, 90%);
-    margin-bottom: 1.25rem; /* 20px */
-    text-align: justify;
-  }
-</style>
-
-</head>
-<body>
-
-  <div class="page">
-    <h1>Directory Naming</h1>
-
-    <h2>Reference</h2>
-
-    <ul>
-      <li>Mosaic/<span class="description">aka REPO_HOME, top level owned by the project administrator.</span></li>
-      <ul>
-        <li>developer/ <span class="description">Workspace for the developer. Has the source code, build scripts, and development-specific tools.</span></li>
-        <ul>
-          <li>deprecated/ <span class="description">Files and older versions being viewed, perhaps part of a refactoring effort.</span></li>
-          <li>document/ <span class="description">Documentation on developing and building the project.</span></li>
-          <li>javac/ <span class="description">Java source files for compilation.</span></li>
-          <li>jvm/ <span class="description">Compiled Java bytecode files for the project, typically a jar for a Java project.</span></li>
-          <li>scratchpad/ <span class="description">Temporary storage typically for intermediate files created during build.</span></li>
-          <li>shell/ <span class="description">Shell scripts intended to be part of the project release. (These are not tools.)</span></li>
-          <li>tool/ <span class="description">Tools created by the developer, used for development tasks.</span></li>
-        </ul>
-        <li>document/ <span class="description">General documentation about the project.</span></li>
-        <li>release/ <span class="description">Release candidate for testing. Becomes the release on the release branch.</span></li>
-        <li>scratchpad/ <span class="description">Temporary storage for project administration tasks.</span></li>
-        <li>tester/ <span class="description">Workspace for the tester. Has the test bench, tests, and test scripts.</span></li>
-        <ul>
-          <li>document/ <span class="description">Test-specific documentation.</span></li>
-          <li>javac/ <span class="description">The tests of the test bench sources.</span></li>
-          <li>tool/ <span class="description">Tools needed for testing and managing the test environment.</span></li>
-        </ul>
-        <li>tool/ <span class="description">Project administration specific tools.</span></li>
-        <li>tool_shared/ <span class="description">Tools shared across project roles.</span></li>
-        <ul>
-          <li>bespoke/ <span class="description">Shared tools developed within this project.</span></li>
-          <li>customized/ <span class="description">Modified versions of third-party tools adapted for the project.</span></li>
-          <li>document/ <span class="description">Documentation related to shared tools and setup.</span></li>
-          <li>third_party/ <span class="description">Shared tools sourced from third-party vendors or open-source projects. These have their own independent licenses,</span></li>
-        </ul>
-        <li>LICENSE.txt <span class="description">The project license detailing usage and distribution terms.</span></li>
-        <li>README.md <span class="description">A general overview and introduction to the project.</span></li>
-      </ul>
-    </ul>
-
-    <h2>Name origin and rationale</h2>
-
-    <p>Developers and project administrators typically do not employ a semantic system for
-      naming directories, but more commonly use conventional placeholder
-      names. The intended purpose of files in a directory with a placeholder
-      name then must be inferred from experience or inspection of the files, or
-      learned from documents or other people.</p>
-
-    <p>For example, a directory named <code>exe/</code> probably derives its name from the
-      fact that the contained files have their executable permission bit set;
-      however, such a directory will not contain all such files.  There might
-      even be some files in an <code>exe/</code> directory that do not have their
-      executable permission bit set. The two concepts being an <code>exe/</code> file
-      (i.e. being a file in an <code>exe/</code> directory) and being an executable file
-      are not identical. The actual intended meaning of being an <code>exe/</code> file
-      will sometimes be that the contained files are applications available to a
-      user, or that they are tools available for use in a project.
-    </p>
-
-    <p>The directory names in this project resulted from an exploration of a
-      property-based file system. In such a system a number of files and
-      agents are defined. Then we can ask questions about their relationships.
-      Files with a relationship to the developer are collected, and this
-      becomes the <code>developer/</code> directory. In a similar manner we get the
-      directories, <code>tester/</code>, and <code>javac/</code>.  In this latter case the
-      agent is a compiler rather than a role.
-      </p>
-      
-    <p>When attempting to apply the <code>is-for</code> property in practice it
-      became apparent that using this sole property was insufficient.  Consider
-      the directories <code>deprecated/</code> and <code>scratchpad/</code>. There is no
-      <em>Mr. Deprecated</em> or <em>Mr. Scratchpad</em> who the contained
-      files are for. (And this conclusion is not for the lack of trying. Even
-      mythological beings did not suffice as agents.) Rather than being for an
-      agent, the files collected in such a directory have in common a state of
-      being that was imposed upon them by decree.  Perhaps the developer, has
-      decreed that a file is now deprecated, or a build script has decreed that
-      it is a scratchpad file. Such decrees are typically more dynamic than the
-      relationship properties. Also, these properties are disconnected from the
-      contents of the file.  When, for example, a file has the property of being
-      for the java compiler, we gain some information about its contents. In the
-      universe of possible messages sent through a file, such a file will
-      contain text that is proposed to be java syntax conforming. In contrast,
-      when we learn that a file is <code>deprecated/</code> we gain no
-      information about the contents of the file, because any file can
-      be <code>deprecated</code>, independent of its contents.
-      </p>
-
-    <p>To understand a directory name within this system, one can imagine
-      reading said name as part of a sentence that integrates the
-      property. Consider two property names: <code>is-a</code>
-      and <code>is-for</code>. For example, "Each file in
-      the <code>document/</code> directory <code>is-a</code> document," or "Each
-      file in the <code>developer/</code> directory <code>is-for</code> the
-      developer."  Although the property name is not carried over from the
-      property based file system to the conventional file system, we can
-      typically infer what it must have been. (It is beyond the scope of
-      discussion here, but in actuality, property based file system collections
-      are defined by predicates. Each predicate is given a file's properties and
-      relationships as arguments, then resolves to true if and only if the file
-      belongs to the collection. Now wouldn't that be interesting if we instead
-      derived a probability?)
-    </p>
-
-    <p>It is uncommon for a property value to be plural. While it is not
-      disallowed, it rarely occurs in practice. This is true independent of
-      whether we are discussing a relationship property or a state
-      property. Hence when we make a file collection based on a shared property,
-      then carry that over as a directory name in a conventional file system,
-      the resulting directory name will often be singular.  This pattern can be
-      observed in the case of the <code>document/</code> directory, as shown in
-      the prior paragraph.
-    </p>
-
-  </div>
-
-</body>
-</html>
diff --git a/document/see_also.txt b/document/see_also.txt
new file mode 100644 (file)
index 0000000..3e953e3
--- /dev/null
@@ -0,0 +1,10 @@
+See also these important documents at the single point
+of maintenance: Mosaic/developer/document:
+
+
+  https://git.reasoningtechnology.com/proem/home/?p=Mosaic;a=tree;f=document;h=81c6bc00c1b9ecfe41bd1b896908351ba0f49f85;hb=refs/heads/core_developer_branch
+
+  https://github.com/Thomas-Walker-Lynch/Mosaic/blob/release_v1.0/document
+    bash_name_of_script.txt - about the functions to get the current bash script name
+    directory_naming.html - how to name directories in the project
+    work_flow.txt - definition of roles, directions for making a release
diff --git a/document/work_flow.txt b/document/work_flow.txt
deleted file mode 100644 (file)
index 6c3ea4c..0000000
+++ /dev/null
@@ -1,59 +0,0 @@
-### Work Flow
-
-#### 1. Project Administrator
-
-1.1. Download the project from GitHub.
-1.2. Install the required tools.
-1.3. Explain the workflows and where things are located to project members.
-1.4. Perform Major and Minor Release administration.
-
-#### 2. Developer
-
-2.1. From the Mosaic directory, run `> source env_developer` to set up the
-     developer environment.
-2.2. Use `> make` to build the project, and `> release` to copy relevant files
-     to `$REPO_HOME/release` for testing.
-2.3. The tester will test the release candidate.
-
-#### 3. Tester
-
-3.1. From the Mosaic directory, run `> source env_tester` to set up the tester
-     environment.
-3.2. Use `> make` to build the tests, and `> shell/test_<name>` to run a test.
-     Alternatively, you can cd into one of the test directories, source the
-     environment for that test, and run it manually.
-3.3. Testing and development will likely iterate until the release candidate is
-     ready to be turned into a versioned release.
-
-#### 4. Major Release
-
-4.1. The release candidate is located in the `$REPO_HOME/release` directory and
-     has passed testing.
-4.2. Check that the program `$REPO_HOME/tool_shared/bespoke/version` outputs the
-     correct information. If necessary, modify it.
-4.3. A new branch is created in the project for the release, named
-     `release_v<n>.0`, where `v<n>.0` is the version number from the `version`
-     program. The minor version number is set to zero (`.0`), and it is assumed
-     that this will be the case after each major release.
-4.4. Rename the release directory to `$REPO_HOME/release_v<n>.0`, and create a
-     new empty `$REPO_HOME/release` directory. The new empty release directory
-     can be used by developers who download the project and make local edits, as
-     the build scripts target this directory.
-
-#### 5. Minor Release
-
-If urgent changes need to be made to the most recent major release, these edits
-should be made on the corresponding major release branch. The developer makes
-the edits, and the tester tests the release candidate as usual. The `version`
-program is updated. Once the release candidate is finalized, rename the
-directory to `release_v<n>.<m>`, where `<m>` is the minor version number. If
-needed, merge the changes into the `core_developer_branch`.
-
----
-
-### Tips:
-
-- If you are acting in multiple roles (e.g., developer, tester, and project
-  administrator), keep separate terminal shells open for each role. This way,
-  the environment will remain correctly configured for the tasks related to
-  each role.
diff --git a/tester/document/jdb.txt b/tester/document/jdb.txt
deleted file mode 100644 (file)
index 1ed956a..0000000
+++ /dev/null
@@ -1,54 +0,0 @@
-About `jdb`
-
-1. setting the environment
-
-  The environment should be set before running the IDE. For example,
-
-  > cd Mosaic
-  > source env_tester
-  > emacs & 
-
-  (I use emacs as my IDE. You might be using a different tool.)
-
-2. location of the executable
-
-  Provided that the project administrator installed it, jdb is located in the
-  third_party tools directory. In the tester environment the variable
-  `JAVA_HOME` should hold the jdb directory path, and this should already
-  be in the `PATH`.  For example:
-
-  > echo $ENV
-  tester/tool/env
-
-  > echo $JAVA_HOME
-  /var/user_data/Thomas-developer/Mosaic/tool_shared/third_party/jdk-11
-
-  > which jdb
-  /var/user_data/Thomas-developer/Mosaic/tool_shared/third_party/jdk-11/bin/jdb
-
-3. invocation from a shell command:
-
-     jdb -sourcepath $SOURCEPATH <class_name>
-
-   The `SOURCEPATH` is assigned a value in `tester/tool/env`.  In some versions
-   of jdb there is no space between `-sourcepath` and the `$SOURCDEPATH`.  
-
-   jdb will read CLASSPATH from the environment. In contrast jdb will not read
-   `SOURCEPATH` from the environment. It must be passed as an argument.
-
-   There is a `run_jdb` script in the `tool` directory.
-
-4. invocation inside of Emacs
-
-   The file `tool_shared/bespoke/emacs.el` holds a definition for the `jdbx`
-   command.  This command will read the SOURCEPATH from the environment and run
-   jdb in Emacs.
-
-   That file also holds the definition for a listener to the jdb `sourcepath`
-   command.
-
-
-
-
-
-
diff --git a/tester/document/see_also.txt b/tester/document/see_also.txt
new file mode 100644 (file)
index 0000000..f65f619
--- /dev/null
@@ -0,0 +1,8 @@
+
+See also these documents located at a single point of maintenance:
+
+  https://git.reasoningtechnology.com/proem/home/?p=Mosaic;a=tree;f=tester/document;h=51b10aaa2d43d4ac591a83844471eb4093f988a4;hb=refs/heads/core_developer_branch
+
+  https://github.com/Thomas-Walker-Lynch/Mosaic/tree/release_v1.0/tester/document
+
+      jdb.txt - how to use jdb with the project