From: Kyle Bowman Date: Mon, 16 Dec 2024 03:32:22 +0000 (-0500) Subject: docs: add majority of documentation X-Git-Url: https://git.rocketbowman.com/?a=commitdiff_plain;h=9b881910baee5de6cc4cf438bb99338adff4cc17;p=jetsam.git docs: add majority of documentation --- diff --git a/README.md b/README.md index e50c9b7..53295ef 100644 --- a/README.md +++ b/README.md @@ -1,28 +1,195 @@ -# Usage +# Overview -Write markdown. Use the Makefile to build render it to HTML via pandoc. +[Pandoc](https://pandoc.org/) deserves to be mentioned before Jetsam as it's the +real workhorse of this operation. Jetsam can be described as a Pandoc-based +distribution or tool kit of writing utilities that are designed to help you write, publish, +and maintain a corpus of personal-space writings. Personal-space writings is +an *ad hoc* term intended to contrast the commercial space of the web and +instead connote your own cozy -## Adding Content -The Makefile builds all Markdown files in `src` or one of -its subdirectories. You can add files directly to `src`. Or, -if you want to keep your content separate from the functionality, -you can use symlinks. +# About the Name -From `src`, use `ln -s ../../dir src/dir` to make it appear that your -markdown files are in the directory, even if they are in a separate +The term [jetsam](https://en.wikipedia.org/wiki/Flotsam,_jetsam,_lagan_and_derelict#Jetsam) +comes from maritime law. It refers to cargo that is intentionally discarded +from a ship or wreckage. Jetsam is often the byproduct of trying to save a +sinking ship by reducing its load. Per maritime law, someone that recovers jetsam +is generally not obligated to return it to the original owner. The finder retains +the value of the recovered goods. -## Building +Jetsam is a beautiful metaphor for writing. For the writer, writing is a powerful form of +[rubber ducking](https://en.wikipedia.org/wiki/Rubber_duck_debugging) +(jetsam's mascot). Writing forces you to encounter and clarify any ambiguous or +underspecified thoughts that you may have about a topic. Once you have written +about the topic sufficiently clearly, it _feels_ resolved. You can mentally offload +it. But just because you discard it doesn't mean that your jetsam isn't valuable to +whomever stumbles upon it. -* `make all` builds all the HTML from the Markdown. -* `./scripts/index.sh > build/all.html` builds the index that is based on -content from the build directory. +Also, I chuckle at the mental image of a panicked sailor casting rubber ducks off a +sinking ship. -Note: There is some significant hardcoding in the script that assumes that -the `all.html` file is in the `build` directory. +Godspeed, little ducky. -# Common Errors +# Using Jetsam -## "pandoc: build/public/note1: withFile: does not exist (No such file or directory)" +Jetsam usage can be summed up in the following steps: -Pandoc does not build the directory by default. Check that the build/public -directory exists. \ No newline at end of file +1. You're responsible for your own prerequisites. +2. `git clone` this repository. +3. Create a link `src` that points to your content (css, images, markdown). +4. Thereafter, use the Makefile to build your content. + +To quickly get some hands on experience, [explore the demo](#explore-the-demo). + +## Prerequisites + +As mentioned in the overview, Jetsam is more of a collection of utilities than +it is a piece of distributable software in itself. Installation is basically +"go get these files". There's no smart dependency management. There's no +installer script. + +That said, basically every Unix-based operating system already has some +version of each of these tools (with the possbile exception of Pandoc). If not, +you can install them easily from your distro's package manager. Even Windows +folks can access them via MinGW, Cygwin, or these days, WSL is probably your +best bet. + +The following software is required: + +| Software | Version | +| -------- | ------- | +| [Pandoc](https://pandoc.org/) | 3.4 | +| [Make](https://www.gnu.org/software/make/manual/html_node/index.html) | GNU make 4.3 | +| [Git](https://git-scm.com/) | 2.39.1 | +| [Bash](https://www.gnu.org/software/bash/manual/bash.html) | GNU bash 5.2.14(1) | + +Jetsam uses pretty standard features. The versions should be pretty flexible. +You can probably even use versions earlier than the ones listed. The listed +versions merely indicate the ones that were used for development and testing. + +For each compoenent of the required software, you can check the version by +running `command --version` where `command` is one of `pandoc`, `make`, `git`, +or `bash`. + +## Getting Jetsam + +Use `git clone` to pull all this content into your workspace. + +``` bash +cd /home/user/notes +git clone --depth=1 https://git.rocketbowman.com:/projects/jetsam.git +``` + +When I say your *workspace*, I really do mean the directory that you intend to +work from. To be more specific, I mean the directory that you intend to run +commands from. Jetsam is driven by Make. Make uses definitions from the the +current directory's Makefile by default. Furthermore, the Makefile references +files and directories relative to where the Makefile is located. Technically, +you could use symlinks and adjust Makefile variables to get it to work, but it +gets messy and hard to maintain. Doing so is ill-advised. + +Using Git is also technically optional, but *highly* recommended. For one, it's +a convenient way to fetch all the files. But more importantly, there's no real +packaging system for Jetsam. Git gives you the ability to fetch updates, roll +back versions, and manage your own tweaks sanely. + +## Structuring Your Content + +By default, Jetsam looks in the `src` directory for content. You *could* create +a `src` directory and author your markdown files directly in that. But chances +are that you want your content to be in a separate version control repository +from Jetsam's. + +A better way than authoring directly in the `src` directory is to create a +separate repository for your content and then create a symbolic link that +points from the Jetsam `src` directory to where your content is actually +stored. From the point of view of the Jetsam buid tools, the source material +can be found at the end of that symlink. But Git doesn't track content +at the end of the symlink, so it's not tracked in the Jetsam repository. At +most, Git might recognize that there is a symlink, but not what content it +references. + +### Managing Your Assets + +One special directory is the `assets` directory, located at `src/assets`. +Everything in this directory is copied when you build your content. Copying +the directory into the build enables you to use relative references from your +written work to a given asset. If the reference works in the local build, +you can be assured that it works at deployment. + +Aside from the `assets` directory, there is nothing special about the `src` +directory. You can organize them however you want. When using the default +build rules, Jetsam searches recursively through all non-asset directories +for markdown files (via the `.md` extension) and attempts to build them. + +### Creating Modular Builds with Symlinks + +Managing your content with symlinks gives you a modular approach to building +your work. For example, suppose that you have a directory of private content +and one for public content. When you are working on your private notes, perhaps +you want to be able to link to your public notes. While you are working on your +private notes, your your `src` directory might look like this: + +``` +src/ + |---assets -> content/assets + |---public -> content/public + |---private -> content/private +``` + +Before you publish, you can run `rm src/private` to remove the link, run +`make clean` to remove private content that might be lingering from a previous +build, then build a new copy that does not contain the private content. + +**Pro tip:** If you find yourself gravitating toward complex symlink structures, +consider looking into GNU Stow or similar offerings. GNU Stow enables you to +install and uninstall a structured collection of symlinks as a single unit. + +## Building your Project with Make + +Make is a command line tool that is used to build projects. When invoked, Make +looks for a Makefile then runs the corresponding build rules found within. To +invoke Make, you run `make target` where `target` is usually some file that you +want to build. Make looks in the Makefile for a build rule for `target`, checks +that it has all the ingredients (dependencies) that it needs, and if it does, +Make runs the rule needed to build `target`. If Make does not find the +dependencies, it looks for *their* build rules and invokes them first. Thus, +running `make target` might build as many artifacts as it needs in order to +build `target`. + +Jetsam uses a Makefile to specify how the files should be built. Usually, you +only need to specify one target and Make will walk the dependency graph and +build all the files it needs for your project. In other cases, you might want +to run each step individually so that you can modify a small part of the build +process. + +### Jetsam's Make Targets + +To see the available build targets, run `make help`. + +### Building Ad hoc Targets + +There are two essential steps to Jetsam's Make process. You can intervene +before each step. The build steps are: + +1. Create the `.buildlist` file. +2. Build each thing in the `.buildlist` file. + +To intervene in the creation of the `.buildlist` file, you can override +the `BUILD_LIST` variable when you invoke Make. The `BUILD_LIST` is a +space-delimited list of files to build. The spaces are turned into newlines +to create the `.buildlist` file. You can create the list of files by whatever +means you want. An example invocation might be something like: +`make BUILD_LIST=$(find somedir -name '*.md' | sed 's/md/html/g' )`. (Although +you need to prepend `build/` to each file.) + +The easier, but more manual way is to run `make .buildlist`, then manually +edit the file to build only the files that you want. + +**Note:** Spaces in filepaths will mess the part where the `BUILD_LIST` +variable is used to create the `.buildlist` file. + +# Explore the Demo + +1. `make init-demo` +2. `make rm-src` +3. `make init-altdemo` \ No newline at end of file