+++ /dev/null
-#!/usr/bin/env bash
-
-# this has never been run, but is the general idea ... ROOT_DIR needs to be changed
-
-set -e
-
-ROOT_DIR="${1:-Harmony}"
-echo "Creating Harmony project skeleton in: $ROOT_DIR"
-
-# Create top-level structure
-mkdir -p "$ROOT_DIR"/{developer,release,tester,tmp,tool_shared/{bespoke🖉,customized,document🖉,third_party}}
-
-# Create env_<role> scripts as placeholders
-for role in developer tester toolsmith; do
- touch "$ROOT_DIR/env_$role"
-done
-
-# Create LICENSE and README.md placeholders
-touch "$ROOT_DIR/LICENSE"
-touch "$ROOT_DIR/README.md"
-
-# Create git_holder in release/ and tester/
-touch "$ROOT_DIR/release/git_holder"
-touch "$ROOT_DIR/tester/git_holder"
-
-# Create .gitignore in tmp/ and third_party/
-cat > "$ROOT_DIR/tmp/.gitignore" <<EOF
-# Ignore all files
-*
-!.gitignore
-EOF
-
-cat > "$ROOT_DIR/tool_shared/third_party/.gitignore" <<EOF
-# Ignore all files
-*
-!.gitignore
-EOF
-
-# Add placeholder files in document🖉 and bespoke🖉
-touch "$ROOT_DIR/tool_shared/bespoke🖉/env"
-touch "$ROOT_DIR/tool_shared/bespoke🖉/version"
-touch "$ROOT_DIR/tool_shared/document🖉/README.org"
-
-# Feedback
-echo "✔ Project skeleton created."
-echo " Remember to edit env_<role> scripts and LICENSE as needed."
+++ /dev/null
-<!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>Pencil Suffix</title>
- <style>
- html {
- font-size: 16px;
- }
-
- 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;
- margin: 1.25rem auto;
- max-width: 46.875rem;
- background-color: hsl(0, 0%, 0%);
- box-shadow: 0 0 0.625rem hsl(42, 100%, 50%);
- }
-
- ul, li {
- font-size: 1rem;
- list-style-type: none;
- }
-
- li::before {
- content: "• ";
- margin-right: 0.3125rem;
- }
-
- li {
- margin-bottom: 0.3125rem;
- }
-
- .description {
- margin-left: 0.625rem;
- 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;
- border-radius: 0.1875rem;
- font-size: 90%;
- }
-
- h1 {
- text-align: center;
- color: hsl(42, 100%, 84%);
- text-transform: uppercase;
- margin-bottom: 1.25rem;
- }
-
- h2 {
- color: hsl(42, 100%, 84%);
- text-transform: uppercase;
- margin-top: 2.5rem;
- }
-
- p {
- color: hsl(42, 100%, 90%);
- margin-bottom: 1.25rem;
- text-align: justify;
- }
- </style>
-</head>
-<body>
- <div class="page">
-<h1>The Pencil Suffix and Authored Files</h1>
-
-<h3>How to Use the Pencil Suffix</h3>
-
- <p>The pencil suffix is a Unicode character, 🖉, that is placed as the last character of a filename or directory name. It signifies that the file, or contents of a so named directory, are uniquely authored and should not be deleted or rebuilt by clean scripts or build scripts. The pencil suffix also serves as a communication tool among team members as to where in the project edits should be inserted.</p>
-
- <strong>Two methods for marking a file as authored:</strong>
- <ul>
- <li><em>Directory with Pencil Suffix:</em> This method marks all contents within said directory sub-tree as being authored.</li>
- <li><em>File Name Last Character as Pencil:</em> This directly marks the file itself as authored.</li>
- </ul>
-</li>
-
- <p>The recommended method to mark files as authored is to place them in a directory, where the name of said directory ends with the pencil symbol. Directly marked files will then be exceptional cases.</p>
-
-<h3>Pencil suffix definition</h3>
-
-<p>By definition, the pencil suffix designates files or directories as <em>leaves in the build tree</em>. Hence, by definition pencil suffix files are not built by tools. It is a corollary that these files are the primary sources of material and serve as points of entry for edits by authors, whether human or AI. Thus we refer to these leaves as <span class='term'>authored</span>. At the time of writing, this definition is maintained by contract with the programers, along with the assistance of the <code>rm_na</code> tool.</p>
-
-<h3>Replace <code>rm</code> with <code>rm_na</code> in scripts</h3>
-
-<p>The <code>rm_na</code> command is a modified version of the standard <code>rm</code> command, and it refuses to delete files marked as being authored. This is true whether the file is marked as authored with a pencil suffix or is found in a directory tree marked as such.</p>
-
-<p>Use <code>rm_na</code> in place of <code>rm</code> in scripts that clean, build, or otherwise manipulate project files.</p>
-
-<p>While <code>rm_na</code> offers a safeguard, the pencil suffix itself does not enforce permissions. Users can still manually delete 🖉-marked files using <code>rm</code>, and roqque builds can overwrite them.</p>
-
-<h3>Pencil suffix and editablity</h3>
-
-<p>The pencil suffix does not inherently restrict or permit editing. A file without the pencil suffix that has write permissions can also be edited; however, such edits are at risk of being overwritten or lost during builds or cleans. While lack of a pencil suffix on a file, or inclusion in such a directory, does not prevent a file from being edited - it does mean that it might not be advisable to edit such a file. Conversely, it is intended that a file marked as authored can be edited without fear of the edits being overwritten. Hence pencil suffix files are the appropriate places to insert edits into a project. In this sense the pencil suffix does indicate a file is 'editable'; however, this is not the definition of the pencil suffix, rather it is a property that emerges from the definition.</p>
-
-<h3>Symbolic Links</h3>
-
-<p>Symbolic links, while facilitating access to authored files, are independent entities that merely point to targets. As such, the link itself is not an authored file, and its lifecycle is separate from the content it references. A symbolic link can be created or deleted without impacting the authored content it points to.</p>
-
-<p>Because symbolic links are not authored entities, they do not carry pencil suffixes, even when their targets do. This distinction ensures that the pencil suffix remains specific to authored files and directories, highlighting their preservation within the project.</p>
-
-<p>However, this lack of pencil suffix on links can create confusion. Users viewing symbolic links in a directory listing may overlook authored content if they rely solely on the link names. The intended edit points within the project might not be apparent unless users examine the targets of the links. </p>
-
-<p>To mitigate potential confusion, file browsers or editors that visually distinguish symbolic links from regular files are highly valuable. These tools help users identify links at a glance, preserving the clarity of authored content within the project structure. </p>
-
-
-
-
-<h3>Hard Links</h3>
-
-<p> Among multiple hard links, none is distinguished as being the primary file link. Hence, should a hard link point at an authored file, and that hardlink is not in a directory that already identifies it as an authored file, it should have the pencil suffix. It is the only option available, because in general we can not know the order of deletion of the hard links, and thus do not know which will be the last one that should not be deleted. Hard links are strange beasts that should be avoided for many other reasons as well.</p>
-
-
-<h3>Future direction</h3>
-
-<p>In the future we hope for tighter integration with the OS, perhaps through use of sub-users (see the subu project), or through a property based file system. For now it is a communication tool, one which is strengthened through use of the <code>rm_na</code> command.</p>
-
-
-</body>
-</html>
projects / RT-project-share / commitdiff