# 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.
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).
| [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`,
```
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
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
## 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
# 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
projects / jetsam.git / commitdiff