c4 - literate command-and-control

Table of Contents

"Restate the problem in terms of the solution." -variously attributed

C4 is Continuous Creation, Command & Control, a literate technology control framework built atop OrgVM.

1. TODO Capabilities

Documentation Centric Development

  • [ ] document browser (for web)
  • [ ] CRUD API (over http/s)
  • [ ] in-line editor (for web)
  • [ ] instrumentation (as svg)
  • [ ] controls (as html)
  • [ ] whole-network CI (via TLS)

2. INPROGRESS Documentation

design.png

C4 builds atop OrgVM, which provides a framework for scheduled and on demand interaction with "literate documents". Literate documents are plain text files which represent all of the source and reference materials required for a given solution.

C4 adds a framework for encapsulation as well as system automation ("glue") functionality to provide continuous integration of and via web and document based user interfaces.

  1. a c4 document created or changed
  2. build and package
  3. perform universal changes, e.g. to DNS
  4. configure (virtualized) infrastructure
  5. update hosted packages
  6. HTTP server is ready, accept:
    1. POST,DELETE - entire document (requires authorization)
    2. PATCH - incremental (requires approval)
    3. PUT - approve (requires authorization)

https://c4.ghostwheel.cloud

3. INPROGRESS Application

Application c4
Design README.org
Contexts DNS network
  UNIVERSE DNS vendor
  system network host
  project program
  instance service job

4. INPROGRESS State

4.1. TODO Feature Checklist

  • [-] edit the notebook from a browser (webux)
  • [ ] rebuild when the notebook changes
    • [ ] push to revision control
    • [ ] rebuild universe
      • [ ] update DNS
      • [ ] do packaging
    • [ ] update hosts
    • [ ] update packages
    • [ ] restart instances
    • [ ] notifications, monitoring, and statistics

4.2. TODO Capability Checklist

Web

  • [ ] process a document, generate index and fragments
  • [ ] process an incremental change, write the change
  • [ ] display incremental change list (diffs)
  • [ ] save incremental change disposition (diffs)

System

  • [-] build from document
  • [ ] rebuild after change approval

5. INPROGRESS Development

Programs to run within Emacs.

5.1. HTML rendering

To render HTML from this document place your cursor (point, in Emacs terms) into the code below and press C-c C-c (control+c, twice). 

(org-html-export-to-html)

5.2. Performing Text Edits

5.2.1. our/insert-point

Insert the position in the document at point. 

(defun our/insert-point ()
  "Insert the position in the document at point"
  (interactive)
  (kbd "C-c M-p")
  (insert (format "%s" (point))))
  1. Key Binding: C-c M-p

    Setup Control + C followed by Control + P to insert the position in the document at point. 

    (global-set-key
 (kbd "C-c M-p")
 #'our/insert-point)

5.2.2. ndk/tangle-dir

Insert the position in the document at point.

#https://emacs.stackexchange.com/questions/61359/how-to-specify-a-directory-to-tangle-all-code-blocks-into 

(setq our/tangle-dir (org-entry-get nil "dest" t))

(defun our/org-babel-tangle-rename ()
  (when our/tangle-dir
    (let ((tangledir our/tangle-dir)
          (tanglefile (buffer-file-name)))
      (rename-file tanglefile tangledir t))))

;; (add-hook 'org-babel-post-tangle-hook #'our/org-babel-tangle-rename)

5.3. Project source rendering

To render source files from this document place your cursor (point, in Emacs terms) into the code below and press C-c C-c (control+c, twice). 

(org-babel-tangle)

5.4. Extracting document data

These functions are used when rendering files from the document.

5.4.1. autogenerate File Name

Return the current section name for use as a filename. 

(save-excursion
  (goto-char p)
  (nth 4 (org-heading-components)))

5.4.2. autogenerate Header Commentary

Extract heading summary commentary. 

(save-excursion
  (goto-char p)
  (let ((s (progn
             (while (not (or (bobp)
                             (looking-at "^$")))
               (forward-line -1))
             (point))))
    (org-back-to-heading t)
    (narrow-to-region s (point))
    (prog1 (buffer-string) (widen))))

6. Integration (in shell)

These programs run from the command line and shell-scripts.

6.1. make.sh

c4 build:MAIN (sh) - bootstraping procedure

Section body. 

# 
build.sh \
    && ( mv *.{txt,md,html} doc; \
         mv *.{el,sh} src )

6.2. build.sh

To render program sources and HTML, move to the directory where you cloned the project (or that you installed it to), then run: 

# 
emacs --batch -l build.el

6.3. install.sh

To install programs and configuration thus instantiate something, by default C4, itself. 

# 

## install to..
# instance name, default: c4
C4NAME=${C4NAME:="c4"}

# path to ln
C4SH_ln=${C4SH_ln:=/usr/bin/env ln}

# options to ln
C4SHOPT_ln=${C4SHOPT_ln:=""}

# install basepath
C4IB=${C4IB:=/var}
C4IF=${C4IF:=/sbin}

# install from..
# target name
C4TN=${C4TN:=$C4IN}
# repository path
C4RP=${C4RP:=./}

# what to install..
# file basename
C4FB=${C4FB:=README}
# source extention
C4SE=${C4SE:=org}
# target extention
C4TE=${C4TE:=html}

# final extention
C4FN=${C4FN:=$C4FB.$C4TE}

# source, default: ./README.org
input=${input:=$C4RP$C4FB.$C4SE}

# target, default: ./README.html
output=${output:=$C4RP$C4FN}

# install prefix
#C4IP=${C4IP:=$C4IB$C4IF/$C4NAME}
prefix=${prefix:=$C4IB/$C4NAME$C4IF}

# install, default: /var/c4/sbin/
install=${install:=$prefix/$C4FN}

if test $input -nt $output; then
    echo "$( basename $0 .sh ): ERROR $input is NEWER than $output"
    exit 1;
fi


if test -e $install; then
    echo "$( basename $0 .sh ): STOP $install exists"
    exit 0;
fi

if test ! -e $prefix ; then
    mkdir -p $prefix;
fi

$C4SH_ln $C4SHOPT_ln $output $install \
    && echo "$( basename $0 .sh ): $input -> $output -> $install (OK)" \
    && exit;
RV=$?;
echo "$( basename $0 .sh ): FAILED: $input -> $output -> $install ($RV)";
exit 3

6.4. tangle-README.sh

emacs --batch -eval '(progn (setopt org-safe-remote-resources '"'"'("\\`https://fniessen\\.github\\.io/org-html-themes/org/theme-readtheorg\\.setup\\'"'"'" "\\`https://fniessen\\.github\\.io/org-html-themes/org/theme-bigblow\\.setup\\'"'"'") org-todo-keywords '"'"'((sequence "TODO" "INPROGRESS" "DONE"))) (find-file "README.org") (org-babel-tangle))'

6.5. build.el

;;; build.el --- build README.md from README.org     -*- lexical-binding: t; -*-
;; Author: Corwin Brust <corwin@bru.st>
;; 
;;; Commentary:

;; tangle sources then build README.{md,html,txt} from README.org

;;; Code:

(require 'ox-md)  ;; maybe something to install ox-md from MELPA?
(require 'htmlize "/var/c2e2/orgvm/site-lisp/htmlize/htmlize.el" t)

(setopt org-safe-remote-resources
          '("\\`https://fniessen\\.github\\.io/org-html-themes/org/theme-readtheorg\\.setup\\'"
          "\\`https://fniessen\\.github\\.io/org-html-themes/org/theme-bigblow\\.setup\\'")
          org-todo-keywords
          '((sequence "TODO" "INPROGRESS" "DONE")))
(org-babel-do-load-languages
 'org-babel-load-languages
 '((C     . t)
   (ditaa . t)
   (dot   . t)
   ;; (http  . t) ; local source
   (emacs-lisp . t)
   (latex . t)
   ;(ruby . t)
   (js    . t)
   (perl  . t)
   (plantuml . t)
   (shell . t)
   ;; (typescript . t) ; not always loaded
   ))
(save-excursion
  (find-file "README.org")
  (org-babel-tangle)
  (org-md-export-to-markdown)
  (org-html-export-to-html)
  ;;(org-latex-export-to-pdf) ;; ugly, omit for now
  (org-ascii-export-to-ascii))

(provide 'build)
;;; build.el ends here

7. Boilerplate

7.1. About OrgVM

This is an orgvm workbook. The sections provide summary, status, and technical detail in (increasingly, gradually) more "technical" terms. You can replace this section with a description of your solution or leave (or move) it to plug OrgVM.

7.2. Interpreter Selection

The "Sh-bang" line helps the operation system launch the right interpreter.

7.2.1. Starting Perl

#!/usr/bin/env perl
#

7.2.2. Starting Shell

#!/usr/bin/sh
#

7.3. Copyright and License

  1. C4 Design Diagram (CC-BY-4)

    The SVG and PNG graphics (c4.svg and c4.png) are provided under the terms of the Creative Commons Attribution 4.0 International (CC-BY-4) or, at your option, any later international version of that license. Please see the linked reference for details. In summary:

    You may use this (or derived work, including for commercial purposes) however you must link here as well as share only under these same terms.

    1. Reference links for attribution and hot-linking
      https://c4.ghostwheel.cloud/design.png
https://c4.ghostwheel.cloud/design.svg

7.3.1. The Rest of the Work (GPLv3+)

This additional "boilerplate" (or "standard text") identifies the author and designates the program and materials, except as otherwise stated above regarding C4 Design Diagram as free software by specifying a free software license (the GNU Public License, version three or any later). 

Copyright 2025 Corwin Brust <corwin@bru.st>

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program. If not, see https://www.gnu.org/licenses/.

Author: Corwin Brust

Created: 2025-08-17 Sun 00:46

Validate