-# 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
projects / jetsam.git / commitdiff