From 69cca1869b6aaa10ec4fc3e3f7e8edb5a1e3f565 Mon Sep 17 00:00:00 2001 From: Hans Fast Date: Wed, 1 Apr 2026 11:38:38 +0200 Subject: [PATCH] readme=pubfiles --- README.md | 78 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 76 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 297ca0b..8f53a64 100644 --- a/README.md +++ b/README.md @@ -5,9 +5,11 @@ trls: [ nl ] lang: en --- + + How I create web pages from selected files from this repository, with private and public editions. - + ## Quickstart @@ -61,7 +63,79 @@ Ik heb een formaat ontwikkeld voor tekst die beter bij mijn doelen past dan Mark ## Changes and Updates -This section SHALL describe the idea behind the [Changelog](/changelog). +This section describes the idea behind the [Changelog](/changelog). + +I've decoupled changes to the infrastructure from changes to the content of the site. I've inserted myself as an editor of the algorithmic file diffs. I review which files have changed between builds of the site, and write a changelog entry explaining what has changed in a way that's meaningful to readers. + +The changelog is the 'subscription' mechanism for the site. Instead of a blog section where I write time-bound articles, I write smaller release notes where I draw attention to changes to the 'evergreen' pages making up the rest of the site. This way I can notify readers easily of both new content as well as revisions and expansions to existing content. In order to keep track of these changes, I need an easy way of seeing what has + +In previous experiments, I put the build output in a separate git repository, then included the output of the `git diff` command in the source repository. It was a + +I'm concerned primarily with changes to the _output_ of the site. That means I can freely work on drafts as long as those files are not being [selected](#:~:text=only%20the%20pub%20tag%20is%20relevant), for the final public build by the `pub` tag. + +Web Origami makes it easy to see which files have changed, with the `Dev.changes` builtin. You pass it the previous build of the site, and the output of the build script, and it reports files modified, added, or removed. What's nice about this is that you can get a summary of changes without writing the new build to disk. However, the `Dev.changes` builtin can't report detailed differences within files. So when composing the changelog entries I do write the new version to disk so I can use a text diffing tool like the graphical `meld` or the command-line `diff` for detailed comparisons. + +### Example +As I'm writing this, The output of the `Dev.changes` command looks like this: + +```shell-session +$ ori 'changes build-26gb-a3/, site.ori()' +changelog.json: changed +changelog.rss: changed +changelog: changed +index.html: changed +pubfiles: changed +``` + +`index.html` might be expected to change because it gets summaries of all pages. My index.html really is an _index._ `pubfiles` is expected to change — that's this file. But why have all the `changelog` files changed, since I haven't published a new release yet? To see this, I'll build the site to a new directory, and then inspect a diff of the actual file contents. + +```shell-session +$ ori 'copy site.ori(), clear files:build-26gc-a0' + +$ diff build-26gb-a3/changelog/index.html build-26gc-a0/changelog/index.html +``` + +```diff + +14a15,16 +> +> + +17c19 +< +--- +> +``` + +Ah, I changed the format of the comments by which I select summary text for the index. That's an infrastructural change. I'll either ignore it, or describe that in a separate section. +Further inspection of the diffs shows that I have the following logical changesets to document: + +* Added: this section 'Changes and Updates' +* Infra: + * added highlight-js stylesheet (git commit [templates,css: add highlight-js stylesheet. mdHtml already adds highlight.js tags to code blocks. · be6ea7b34e](https://git.surfacemarkup.net/hans/ad_pubfiles/commit/be6ea7b34ef07363b293ddfa1f79ce5b8dae6c9b ) + * started using a pair of comments to delineate page summaries, instead of just ``, so that the summary doesn't have to the be first text in the file. + + + +### Future Work +What I want to do is create separate sub-feeds for additions, major revisions, minor edits, and infrastructural changes: + +- additions: significant new content added, like new files or a whole new section (like this one) +- major revisions: changes to existing content which alters the meaning of what is written +- minor edits: fixing typos or turns of phrase. +- infrastructure: alterations to the look or behavior of the site as a result of changes to the code. + +I'm pretty sure I'll be able to parse the changelog.md file further to create new feeds with only the relevant subheadings for each changelog entry. This way, people can subscribe to new content and major revisions without being bothered by minor edits. + +I suppose I should include, somewhere in the output, which 'infrastructure' version was used to build the site, identified by a commit hash. + +I also want to try serving the history of the site. The ingredients that are playing around in my head: + +- `rsync build-vY --link-dest=vX server:/vY` will hard link unchanged files to the previous build directory when copying to the server. This means many versions can be stored with greatly reduced disk space. +- the web server would map `/` to a directory `latest` which is a symlink to the latest build. Other builds are available under a version prefixed path, e.g. `https://hansfast.net/v26cg-a0/pubfiles`. +- a wrapper script would take care of creating the new version directories and updating which one `latest` points to. +- the [ori templates](${c.ori/gitrepo}/src/branch/main/ori-templates) would add links to the next and previous versions of the current file. +- should the next/prev links be baked into each build, or should the server keep a list and resolve generic `/next`, `/prev` requests based on a query parameter for the current version? ## Source files The scripts and templates used to build this site are available [here](https://git.surfacemarkup.net/hans/ad_pubfiles).