From ff72766ef04fb71edde3fe13adb6fb85a842806e Mon Sep 17 00:00:00 2001 From: Kyle Bowman Date: Wed, 18 Dec 2024 20:54:59 -0500 Subject: [PATCH] docs: finish README --- README.md | 169 ++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 132 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index 53295ef..f639850 100644 --- a/README.md +++ b/README.md @@ -1,31 +1,32 @@ # Overview -[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 +[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 corner of the +internet. # About the Name 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. +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. -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 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. +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. -Also, I chuckle at the mental image of a panicked sailor casting rubber ducks off a -sinking ship. +Also, I chuckle at the mental image of a panicked sailor casting rubber ducks +off a sinking ship. Godspeed, little ducky. @@ -35,7 +36,10 @@ Jetsam usage can be summed up in the following steps: 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). +3. Create a link called `src` that points to your content (css, images, + markdown). + 1. The `src/assets` directory is copied into your build. + 2. Otherwise, organize directories how you please. 4. Thereafter, use the Makefile to build your content. To quickly get some hands on experience, [explore the demo](#explore-the-demo). @@ -62,9 +66,9 @@ The following software is required: | [Git](https://git-scm.com/) | 2.39.1 | | [Bash](https://www.gnu.org/software/bash/manual/bash.html) | GNU bash 5.2.14(1) | +The listed versions indicate what was used for development and testing, but 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. +You can probably use versions earlier than the ones listed. For each compoenent of the required software, you can check the version by running `command --version` where `command` is one of `pandoc`, `make`, `git`, @@ -80,12 +84,12 @@ 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. +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 makes +references to 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 @@ -119,7 +123,8 @@ 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. +for markdown files (via the `.md` file extension) and attempts to build a +corresponding HTML file for each MD file that it finds. ### Creating Modular Builds with Symlinks @@ -146,21 +151,19 @@ 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 +Jetsam uses a Makefile to specify how the files should be built. 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`. +running `make target` will build all the artifacts as it needs in order to +build `target`. (Except, of course, if it is missing a dependency and there is +no rule to build that dependency.) -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. +The result is that with a few tar ### Jetsam's Make Targets @@ -190,6 +193,98 @@ 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 +In the demo below, `>>>` indicates a terminal prompt in which you enter a +command. A line following it that does not have `>>>` indicates the output. + +When you first clone this repository, the `src` directory should be +non-existent. You can populate it by running the following command: + +``` bash +>>>make init-demo +``` + +**NOTE:** If you see a message about "No rule to make target", be sure that +you are running the command from the directory that has the Makefile. + +You should now see a symbolic link `src` that points to `demo`. Exploring +its contents should yield results like these: + +``` bash +>>>ls -l src +lrwxrwxrwx 1 user user 4 Dec 18 20:18 src -> demo +>>>ls src +assets md +>>>ls src/assets/ +css images +>>>ls src/md/ +about.md acknowledgements.md demo.md +``` + +Now, build the content by running the following command: + +``` bash +>>>make all +``` + +When the command finishes, you should see the `build` dir. + +``` bash +>>>ls build/ +assets index.html md +>>>ls build/md/ +about.html acknowledgements.html demo.html +>>>ls build/assets/ +css images +``` + +The `assets` directory is copied verbatim into the `build` directory. The +`md` directory contains and HTML file corresponding to each MD file from the +`src/md` directory. (Now that I think of it, `md` was a poor choice of name.) +But what is this `build/index.html` file? + +You could open your web browser and navigate to the file. But since we've used +the command line this far, you might as well run the following command to open +it with the default app for HTML files: + +``` bash +>>>xdg-open build/index.html +``` + +Ah! The `build/index.html` file is an index file that lists all files that you +built. You can click around to see the other content like you would any other +webpage. When you are done, you can close out of your HTML app. + +Now, you could make a small change to one of the markdown files: + +``` bash +>>>echo "I added a new line to the end of the file." >> src/md/demo.md +``` + +When you run `make all` again, notice that only `demo.html` is built. Make uses +timestamps to determine which files are outdated relative to their dependencies +so that it doesn't waste cycles rebuilding things that don't need to be built. + +You can throw out your entire build by running the following command: + +``` +>>>make clean +``` + +Throwing out the build enables you to build the entire project from scratch. + +Now, how to get rid of the demo content and start making your own? You can use +your normal file system process to delete files in the `src` directory. But +that's an indiscriminate removal process. You risk throwing away things that +you don't want to throw away. I recommend using the following command: + +``` bash +>>>make rm-src +``` + +This command first checks that everything in your `src` directory is a symlink +before deleting it. By checking first, it ensures that the content is actually +saved somewhere else and you don't risk deleting your writing. + +Now, there should be no `src` directory. You can link in your own. Or, if you +want to see a more flexible way of laying out symlinks in the `src` directory, +try running `make init-altdemo` and exploring the results. \ No newline at end of file -- 2.39.5