1006 lines
80 KiB
TeX
1006 lines
80 KiB
TeX
\documentclass[twoside]{report}
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%% Packages %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
\usepackage[utf8]{inputenc}
|
|
\usepackage[T1]{fontenc}
|
|
\usepackage{amsmath}
|
|
\usepackage{amssymb}
|
|
\usepackage{makeidx}
|
|
\usepackage{graphicx}
|
|
\usepackage[nott]{kpfonts}
|
|
\usepackage{float}
|
|
\raggedbottom
|
|
\usepackage{array}
|
|
\usepackage{multirow}
|
|
\usepackage{gensymb} % Just for the degree symbol
|
|
\usepackage{ccicons} % Creative Commons icons; now we can delete an image
|
|
\usepackage{lettrine} % Drop caps
|
|
\usepackage{wrapfig} % Let's wrap some images
|
|
\usepackage{hanging} % For hanging indents in a script
|
|
\usepackage{fancyvrb} % Use line numbers with code samples
|
|
\usepackage{fvextra} % Break lines inside Verbatim environment:
|
|
\usepackage{enumitem} % Control spacing in lists
|
|
\usepackage{setspace} % Better control over line-spacing
|
|
\usepackage{nicefrac} % Use nice fractions
|
|
\usepackage[bottom]{footmisc} % Keep the footnotes at the bottom of the page
|
|
\usepackage{tabto} % Use tab stops when we need to (especially in footnotes)
|
|
\usepackage{microtype} % Make things neater. Thanks /u/-LeopardShark-
|
|
\usepackage{tabularray} % Easy tables
|
|
\usepackage[]{FiraSans} % sans-serif font; https://tug.org/FontCatalogue/firasansregular
|
|
\usepackage[]{footmisc}
|
|
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%% Commands %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
\graphicspath{{images/}} % Where are our images?
|
|
\usepackage{multicol} % Include two- or three-column sections
|
|
\counterwithout{footnote}{chapter} % Stop resetting the footnote count after each chapter
|
|
\NumTabs{18} % Define 18 tab stops (at 1/4" intervals) [tabto package]
|
|
\raggedbottom % Don't force text to fill page
|
|
\setlength{\belowcaptionskip}{4pt} % Adjust space between caption and figure
|
|
\renewcommand*\contentsname{In This Issue…} % Change the name of the TOC
|
|
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%% Document Setup%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
\usepackage{geometry}
|
|
\geometry{
|
|
paperheight=8.5in,
|
|
paperwidth=5.5in,
|
|
% heightrounded,
|
|
margin=0.5in
|
|
}
|
|
|
|
\addtolength{\topmargin}{0.4in} % Adjust and bottom margin
|
|
\addtolength{\textheight}{-0.75in} % Adjust the bottom margin
|
|
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%% Page Headers%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
\usepackage{fancyhdr}
|
|
\pagestyle{fancy}
|
|
\fancyhf{}
|
|
\fancyhead[LE,RO]{\textit{the codex}}
|
|
\fancyhead[RE,LO]{Issue \#005}
|
|
\cfoot{Page \thepage}
|
|
\renewcommand{\footrulewidth}{0.5pt}
|
|
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%% Chapter Title Spacing %%%%%%%%%%%%%%%%%%%%
|
|
\usepackage{titlesec}
|
|
\titleformat{\chapter}[display]
|
|
{\normalfont\huge\bfseries}
|
|
{\chaptertitlename\ \thechapter}
|
|
{20pt}
|
|
{\Huge}
|
|
\titlespacing*{\chapter}{0pt}{0pt}{40pt}
|
|
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%% Custom Macros %%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
|
|
% Make a nice border and box for the tops of our examples
|
|
\newcommand\klab[3]{\vspace{#1}\noindent{}\hrulefill\fbox{\texttt{~#2~}}\hrulefill\vspace{#3}}
|
|
|
|
% Add an \hrule with space above and below
|
|
\newcommand\krule[2]{\vspace{#1}\hrule\vspace{#2}}
|
|
|
|
% Make hrefs easier (must load package hyperref}
|
|
\newcommand\kref[2]{\href{#1}{{\texttt{#2}}}}
|
|
|
|
% Rotate text in tables easier
|
|
% https://tex.stackexchange.com/questions/89115/how-to-rotate-text-in-multirow-table
|
|
\newcommand\krot[3]{\parbox[t]{#1}{\multirow{#2}{*}{\rotatebox[origin=c]{90}{#3}}}}
|
|
|
|
% Make diversions easier (and uniform!)
|
|
\newcommand\kdivb[2]{
|
|
\medskip
|
|
\hrule
|
|
\medskip
|
|
\noindent{}\textbf{#1}
|
|
\vspace{#2mm}
|
|
\begin{multicols}{2}
|
|
}
|
|
|
|
\newcommand\kdive[1]{
|
|
\end{multicols}
|
|
\vspace{#1mm}
|
|
\hrule
|
|
\medskip
|
|
}
|
|
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%% Just for Issue #005 %%%%%%%%%%%%%%%%%%%%%%
|
|
\usepackage{outlines}
|
|
\usepackage{tikz}
|
|
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%% Include URLS %%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
% Be sure to load this package last
|
|
% [hidelinks option to hide big red box. Thanks /u/0b0101011001001011
|
|
\usepackage[hidelinks]{hyperref} % Inlcude URLs, but load this package last
|
|
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%% Document Information %%%%%%%%%%%%%%%%%%%%%
|
|
\author{Kenneth John Odle}
|
|
\title{
|
|
{\Huge the codex} \\
|
|
{\footnotesize Life with Linux — A Zine \\
|
|
\bigskip
|
|
Typeset in \LaTeX{} \\
|
|
Issue \#005}
|
|
}
|
|
\date{\begin{small}\today{}\end{small}}
|
|
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%% Let's get it started %%%%%%%%%%%%%%%%%%%%%
|
|
|
|
\begin{document}
|
|
\maketitle
|
|
|
|
\section*{Impressum}
|
|
All contents \copyright2024 Kenneth John Odle
|
|
|
|
Although this is now in your hands, and it's also on the web, so if you really wanted to steal this, I've made it pretty darn easy. I can't imagine why anyone would want to, but if you do, you don't need to, because this is licensed under a CC BY-NA-SA 4.0 Creative Commons license. More information is at
|
|
|
|
\kref{https://creativecommons.org/licenses/by-nc-sa/4.0/}{https://creativecommons.org/licenses/by-nc-sa/4.0/} \ccbyncnd
|
|
|
|
This zine is composed in \LaTeX \,using the report document class. It then gets exported to a letterhalf (5.5 in x 8.5 in) pdf, which then gets made into a booklet using PDF Booklet, which you can find at
|
|
|
|
\kref{https://pdfbooklet.sourceforge.io/wordpress/}{https://pdfbooklet.sourceforge.io/wordpress/}
|
|
|
|
The image of Linus Torvalds on the front cover is courtesy JericoDelayah from the WikiMedia Commons and is at \kref{https://commons.wikimedia.org/wiki/File:4_RETAT_04_Linus_Torvalds.jpg}{https://commons.wikimedia.org\\/wiki/File:4\_RETAT\_04\_Linus\_Torvalds.jpg} where you can also find a link to the Creative Commons CC BY-SA 3.0 license there, as well.
|
|
|
|
I'm pushing this to my own git server as I write this. You can find it \href{https://git.kjodle.net/kjodle/the-codex}{here}: \kref{https://git.kjodle.net/kjodle/the-codex}{https://git.kjodle.net/kjodle/the-codex}. New issues will be pushed after they are complete. A list of topics I may cover in the future can be found at \kref{https://git.kjodle.net/kjodle/the-codex/wiki/List-of-Future-Topics}{https://git.kjodle.net/kjodle/the-codex/wiki/List-of-Fu\\ture-Topics}.
|
|
|
|
You can just skip over all the diversions in here if you want. It's just how my mind works. (And yes, there will be politics in this. \textit{You have been warned.}) Also, I use a lot of em-dashes, parentheses, and footnotes because that is also how my mind works. It's just one big long stream of consciousness up in here most days.
|
|
|
|
If you want to donate financial support for the creation of this zine (and all the hours of research that go into it), you can do so at
|
|
|
|
\kref{https://paypal.me/kjodle}{https://paypal.me/kjodle} (Thanks!)
|
|
|
|
\medskip
|
|
|
|
\noindent \textbf{Errata:} To err is human, to document those errors is divine. A list of errata can be found at
|
|
|
|
\kref{https://git.kjodle.net/kjodle/the-codex/wiki/Errata}{https://git.kjodle.net/kjodle/the-codex/wiki/Errata}.
|
|
|
|
\medskip
|
|
|
|
\noindent \textbf{Credit where credit is due:} A lot of people have come forth (mostly from Reddit) to help me out in various ways. See the preamble to this document in the source code to see them. One aspect of our society is that nobody \textit{has} to help you. It is wonderful when it happens, and I am grateful for their help.
|
|
|
|
|
|
\tableofcontents
|
|
|
|
|
|
\chapter{The Salad Days Are Over}
|
|
|
|
\section{Yesterday}
|
|
|
|
A long time ago my stepdad had created a successful business screen-printing t-shirts. He had been in the music business (there is a long story here, but it doesn't fit in with this zine) and he realized he could make more money if he printed and sold his own band shirts.
|
|
|
|
At some point, my parents decided to try to replicate this success. As the sure key to success at the time was to have a website, I got roped in because a long time ago in a galaxy far, far away I had uploaded some HTML files to a free web server and told them "look, I made a web page!" They immediately assumed I was an expert and knew everything about putting a business online, and that I could build a web page that would have us making millions of dollars in mere weeks.
|
|
|
|
This was not the case, of course. What I learned was this:
|
|
|
|
\begin{itemize}[noitemsep]
|
|
\item Dial-up internet sucks.
|
|
\item Clarke's Third Law normally applies, but in the case of parents, even doubly so. (Or squared, or even cubed.)
|
|
\item Never go into business with your family, especially your parents.
|
|
\end{itemize}
|
|
|
|
The useful things I learned from that experience were how to be really good at HTML (and without CSS, you had to be really good at copy and paste), how an FTP client works, and that cPanel really sucks. (If your webhost uses cPanel, \textit{you} can do better, and your webhost \textit{should} do better.)
|
|
|
|
That business died after three or four orders, which was probably a good thing, but it did set me up with some usable skills when I went back to college. I started substitute teaching once I had enough credits to qualify for that, and so decided to create a website as soon as I could as a marketing tool. And thus, \texttt{mrodle.net} was born.
|
|
|
|
Unfortunately, that site did not live long. I had seriously underestimated how much money was required just to exist and when it came to putting gas in the tank \textit{or} paying webhosting fees, it was an easy decision. One of those things was helping me make money and the other was not, and so the website went. (Fortunately, it was so short-lived that \texttt{archive.org} never caught wind of it.)
|
|
|
|
I kept trying. The educational-industrial complex was pushing ``Web 2.0''\footnote{Which was basically social media, but also included blogs.} really hard. I made another website (\kref{https://kjodle.net/}{kjodle.net}, which survives to this day) and my webhost at the time offered a one-click install of WordPress which at that time was pretty much a blogging platform and little else. I clicked on the ``install'' button, wondered for a moment what I had done, and suddenly, \textit{The Big Bad Book Blog} was born.\footnote{\kref{https://bookblog.kjodle.net/}{bookblog.kjodle.net}}
|
|
|
|
As a newly minted English teacher, I enjoyed having a place where I could talk about all the books I'd been reading. But as a nerdy computer person, having a WordPress blog made me really itch. It offered…\textit{possibilities}.
|
|
|
|
It wasn't just HTML and CSS, for a start, which were the only two technologies I knew how to use to create a website. Rather, it was PHP and JavaScript, with a MySQL database attached. And while I was happy with the theme I had chosen, I was not 100\% happy with its appearance. I began tinkering under the hood, which WordPress requires that you do in a rather particular way. I had to level up, so that is what I did. I threw myself into the world of PHP, JavaScript, and WordPress child themes.
|
|
|
|
It was tough work, but I enjoyed it. At this point, I was pretty much substitute teaching full time (and being good at it meant my calendar was full), and while it filled my days, it left my nights free to work on figuring out all these technologies that were new to me.
|
|
|
|
I eventually got to a point where I could create not just a child theme, but also fully blown themes for WordPress, and plugins to boot. Again, tough work,\footnote{I had not yet learned about Git, which would have made all of this \textit{so} much easier. Hence my enthusiasm for Git and the inclusion of a Git primer in this issue.} but very, very satisfying.
|
|
|
|
I was having problems finding an actual teaching job (so many other people decided to get into teaching at the same time, so the market was saturated) and I thought that maybe I could become a developer. Why not? After all, I knew that I could learn whatever I needed to, as long as I set my mind to it.
|
|
|
|
It was a happier, sunnier time, after all, despite the recession—at least if you knew something about ``coding''. I put that in quotation marks because it is at best a fuzzy word with fairly nebulous meaning. After all, I learned ``coding'' at the age of twelve by programming a TRS-80 in BASIC. I doubt that anybody now or in 2010 or even in 1980 would hire me on the basis of \textit{that} particular skillset though.
|
|
|
|
But I tried. I did some freelance development work for WordPress. I had learned how to make child themes fairly easily, and got a fair amount of work from people who wanted to customize their blogs, but had neither the time nor the skill required nor the inclination to learn. Was I making enough money to pay the bills? No. Was I making enough money for a cheap, greasy pizza and a six-pack on the odd weekend? Yep!
|
|
|
|
I was happy with that level of success and wanted more, but there are only so many hours in a day. I didn't have the time to learn everything I needed to know (I admit that JavaScript still eludes me) and I certainly didn't have any more money for coursework or marketing at that point.
|
|
|
|
Plus, I had just graduated with an English degree with the goal of being a teacher. I was still substituting in the hopes of landing a teaching job, though, so I taught myself how to use Moodle and MediaWiki and a few other ``Web 2.0'' technologies.
|
|
|
|
And…it got me nowhere. Summer came, and I was out of substituting work, so I signed up with a temp agency, specifying that I was looking for second-shift work \textit{only}. My thought was that if I could finagle a teaching interview, it would be during the day and so I wouldn't need to take time off from work. Also, assuming that I \textit{couldn't} find a teaching job, I could sub during the day and keep the second shift gig as a way to ensure I wouldn't starve.
|
|
|
|
That was the plan anyway, but it wasn't exactly how things worked out. The agency sent me to interview for a position at a small local manufacturing company that needed someone to operate equipment and keep an eye on inventory during the second shift. I was elated! I can operate machinery! I'm great at managing inventory! Woot!
|
|
|
|
What I didn't know (and what the agency also didn't know) was that this company also needed someone to completely rewrite all of their technical documentation\footnote{Work instructions and processes, mainly, and also the odd business email.}, and to create a training program out of whole cloth and then implement and manage that program. They also needed someone to handle their domestic and MRO\footnote{Maintenance, Repairs, Operations—that is, paint, duct tape, toilet paper.} purchasing, as the part-time person they had doing this currently spent most of her time buying furniture on eBay for her rental properties.
|
|
|
|
I've never had a job interview take such a dramatic turn before (which was the first of many red flags—in retrospect this place looked like a May Day parade in Leningrad) but the things they laid out—paid time off, a retirement plan, health insurance (including vision and dental)—were too much to resist. I pushed my tongue against a sore tooth and agreed to take the job. We all shook hands and I left, wondering what on earth I had gotten myself into.
|
|
|
|
Quite a bit, actually, as it turned out. I thought I might stay a year to get caught up on some things, and then try to get a teaching job again, but the educational-industrial complex is a jealous god who does not trust people who walk away, so the longer I stayed away, the lower my chances of returning would become.
|
|
|
|
I ended up staying with that company for almost six years, despite the fact that I gave notice on three separate occasions. In retrospect, it was a terrible experience (and the subject of an entirely different zine) but I learned a lot. (The main thing I learned was to never work for a small company with no HR department where the boss is also the owner.)
|
|
|
|
The biggest thing I learned is to never underestimate \textit{yourself}. When a former student told me that his current employer had openings and that I should apply, I did. Six weeks later, I was sitting in the training room of my current employer, which brings us to today.
|
|
|
|
\section{Today}
|
|
|
|
I am in a very different place now than I ever thought I would be. I'm not on Plan A or Plan B. In fact, I've pretty much run out of alphabet to describe exactly where I am now.
|
|
|
|
So where am I?
|
|
|
|
I work as a data reviewer for a contract research organization in the pharmaceutical industry. Drug companies send us samples of their products, and we test them for things like assay, impurities, appearance, disintegration, etc. People who majored in chemistry run the tests and I sit there and look at their procedures and results and make sure that everything was performed correctly, that the math is correct, and that the results are, indeed, valid.
|
|
|
|
In theory, I'm an analytical chemist. In practice, I'm a botany/English major with a fondness for computers who spends the day with his nose buried in Excel spreadsheets. \textit{Lots} of Excel spreadsheets.
|
|
|
|
Except that I also used to design websites, so my spreadsheets are easy on the eyes, color-coded, and logically oriented—that is, they take you through the analytical method in a step-wise, chronological manner. In other words, we look at standard concentrations first, and then our system suitability tests, and then the actual tests. Every cell is also labeled, so it's clear what goes where.\footnote{For a visual depiction, see \kref{https://www.youtube.com/watch?v=4IFUYg9IUgI}{https://www.youtube.com/watch?v=4IFUYg9IUgI}.} My boss admires them and I am justifiably proud of them. After all, these aren't just your ordinary, run-of-the-mill spreadsheets we're talking about here.
|
|
|
|
My spreadsheets are so beautiful that when my boss got a glimpse of them he immediately placed me in charge of mentoring new data reviewers, mostly so that they could see what my spreadsheets look like. And I get it. I worked really hard to make spreadsheets that are understandable not just to me but to everybody because we may have a corrective action come up at some point and we need to be able to see how we arrived at the results that we have. I strive to make all my spreadsheets consistent and understandable to someone who has no familiarity with them.
|
|
|
|
\texttt{tl;dr:} I'm \textit{really} good with Microsoft Excel.
|
|
|
|
But it's not satisfying work. It pays the bills.\footnote{Well, barely (and by the time you're reading this, probably not actually), after the recent fit of massive corporate price gouging—I mean, er…inflation.} It's not exactly the hind end of science, but it's close. (I once worked in a lab that did non-clinical testing\footnote{That is, rats and mice. Lots and \textit{lots} of rats and mice.} and believe me, \textit{that} is the hind end of science.\footnote{Science actually has many hind-ends. This is but one of them.}) I'm not really doing science; if anything I'm just a nerdy science accountant, making sure the books balance. It's boring—\textit{really }boring—and more than a bit mind-numbing.
|
|
|
|
Considering that my entire job exists to help keep the drug supply safe\footnote{Well, the \textit{legal} drug supply anyway.} that statement may sound frightening or even disturbing. But it's not really. When it's not boring, it's generally because something has gone wrong, and and this is one of those industries (like nuclear energy or air traffic control) where you really don't want things to get interesting. You \textit{want} this job to be boring.
|
|
|
|
The irony is that I took this job because I \textit{knew} it would be boring. My last job had been so nerve wracking that mentally I was completely spent by the time I got home and creating anything at that point was damn near difficult if not impossible. I figured that if I had a boring job where creativity was not encouraged (that is, we have a procedure, so just stick to the procedure) I could store my creative juices during the day the and use them during the evening to create things.
|
|
|
|
As it turns out creativity doesn't exactly work this way. One of the things that attracted me to teaching was that I got to be creative all day. What I forgot about teaching is that when I got home I was still charged up creatively. I hadn't used up all my creativity. Quite the opposite, in fact.
|
|
|
|
I have spent too much time thinking that creativity is like a bag of candy: you can have a piece of candy every day this week, or you can wait and have it all on the weekend. Unfortunately, that's not how creativity works. If you don't spend time each day being creative, you probably won't feel very creative during the weekend. You can't just store up creativity and then spend it when you have the time.
|
|
|
|
Ages ago I saw an interview you with the father of a very large family (which had grown mostly through adoption) and the reporter asked him how he divided his love among so many kids. His answer was brief and to the point: love is not something you divide—it's something you multiply. Creativity is the same way—you don't divide it, you multiply it, and the only way to multiply it is to use it.
|
|
|
|
It's taken me too long to realize that this is what I've been doing with my creativity. I can't store it up during the day and then use it in the evening. That's not how it works. Creativity is not something that gets used up; it is something that grows when you use it. Creativity just leads to more creativity. It's not a zero-sum game.\footnote{I wish people would realize that our economy—which is not a natural thing, but a thing completely invented by humans—does not have to be a zero-sum game. Just because somebody else gets something they need does not automatically means that I get less of what I need.}
|
|
|
|
That means it's definitely time for a different job.
|
|
|
|
\section{Tomorrow}
|
|
|
|
Given all that, I need to find myself in a place I was back when I was a kid—as a writer and a teacher.
|
|
|
|
Those are the two things I have always been. I don't mean those two trajectories revealed themselves to me when I was in college. I mean that I knew these thing when I was eight or nine years old.
|
|
|
|
I have always scribbled. I found a manual typewriter at the age of eight or nine and never looked back.\footnote{I am fairly certain it was an old K-Mart model—I know for sure that it was blue and that I found it in our attic, and I'm pretty sure it looked like this one: \kref{https://gallery.kjodle.net/picture.php?/628/category/76}{https://gallery.kjodle.net/picture.php?/628/category/76}.}
|
|
|
|
As for the teaching thing, I'm not quite sure. I've always enjoyed learning things and knowing how to do things and sharing that knowlege with other people in the hopes that that might change their life for the better.
|
|
|
|
Long ago, I realized that information is just data—which you can get from encyclopedias and dictionaries (and these these days from the internet if you know how to look). But knowledge is information \textit{in context}, where it's part of a whole that helps you understand how the universe is put together and how it works. Most people think that teaching is just about providing information, which is no doubt a result of our over-reliance on worksheets and scantron sheets and Bush II's policy of ``no child left untested''. That is unfortunately what a lot of teachers do—they force feed kids information, which most kids retain just long enough to regurgitate on a test and then promptly forget.\footnote{Although some of it sticks with us—My high school social studies teacher Mr. Rex insisted that we would need to know the definition the ``mercantilism'' to succeed in college. Oddly, the last placed I was asked for that definition was on his final exam. (I've written about this in a different zine. See \textit{just13} \#2 at \kref{https://just13.click/just13/002.php}{https://just13.click/just13/002.php}.)}
|
|
|
|
Good teachers provide that context along with the information and then guide their students through the process of building knowledge from them. If you can figure out the information and figure out the context and know how to weave those two things into actual knowledge you'll always be able to figure out any task, any role, any job. You'll be able to do anything you set your mind to.\footnote{I haven't even talked about wisdom yet, which is knowledge tempered by experience. And I don't want to discuss it, perhaps mostly because I lack it. In essence, information is about the \textit{what}, knowledge is about the \textit{how}, and wisdom is about the \textit{when} and the \textit{should}.}
|
|
|
|
That was what I loved about teaching—that if I were allowed to do it right I could empower people not just now but for the rest of their lives. I've always taken the long view when it comes to teaching: the kid I'm teaching today might be working on my brakes in ten years. The kid I'm teaching today might be doing heart surgery on me in twenty years. This is not selfishness. The kid who is working on my brakes is also working on lots of other people's brakes and the kid doing open heart surgery on me is obviously not doing this as a one-off.
|
|
|
|
The point is that human existence is a tapestry. We're all connected, like it or not, to other people. That tapestry has a lot of holes in it (thanks to war, disease, capitalism, etc.) so of course most of the time we can't see a direct connection to certain other people simply because it isn't apparent. But we are all connected nevertheless, directly or indirectly. Our choices and our actions have effects that we cannot predict on people we cannot even see, sometimes because they don't exist yet.
|
|
|
|
That is what teaching was about for me—showing kids that they are part of a rich tapestry and that it's okay if they can't see the entire thing because \textit{none} of us can.That was my mission as a teacher. I suppose now it's my mission with this zine.
|
|
|
|
It's also why I am not a teacher now and never will be again—because there is no fucking way that any part of that philosophy can ever be converted to a multiple choice question that can be graded by running a scantron sheet through some 1970s-style technology.
|
|
|
|
Fortunately there's a sweet spot in all of this that is small but doable. That sweet spot is technical writing. I actually did a lot of technical writing in my last job. I took my current job because I was led to believe that it would include a lot of technical writing. The amount of technical writing I've done so far is pretty much zero.
|
|
|
|
Technical writing—that is, writing instruction manuals and work instructions and translating what the chemists and engineers wrote into something that regular people can understand—is what I need to do because it lands smack dab in the middle of this Venn diagram:
|
|
|
|
\begin{center}
|
|
\scalebox{0.8}{ % begin scalebox
|
|
\begin{tikzpicture}
|
|
\draw (0,0) ellipse (60mm and 15mm);
|
|
\draw (0,0) ellipse (15mm and 60mm);
|
|
\draw[rotate around={45:(0,0)}] (0,0) ellipse (15mm and 60mm);
|
|
\draw[rotate around={45:(0,0)}] (0,0) ellipse (60mm and 15mm);
|
|
\node[align=center, text width=2cm, scale=1.4] at (0,0) {Technical Writing};
|
|
\node[align=center, text width=2cm, scale=0.9] at (0,4) {Things I'm Good At};
|
|
\node[align=center, text width=2cm, scale=0.9] at (0,-4) {Things People Will Pay For};
|
|
\node[align=center, text width=2cm, scale=0.9] at (4,0) {Things That Don't Bore Me};
|
|
\node[align=center, text width=2cm, scale=0.9] at (-4,0) {Things That Don't Make Me Sell my Soul};
|
|
\node[align=center, text width=2cm, scale=0.9] at (2.7, 2.7) {Teaching};
|
|
\node[align=center, text width=2cm, scale=0.9] at (-2.7, 2.7) {Something I Like Doing};
|
|
\node[align=center, text width=2cm, scale=0.9] at (2.7,-2.7) {Something I Can do All Day};
|
|
\node[align=center, text width=2cm, scale=0.9] at (-2.7,-2.7) {Improving People's Live};
|
|
\end{tikzpicture}
|
|
} % end scalebox
|
|
\end{center}
|
|
|
|
That's what I'm shooting for. I'm a good writer and I'm a good teacher, so it makes sense to try to put these things together. It reminds me that part of my job is to remind all of us that we are part of the tapestry—that we are part of something larger than ourselves and to know how to reach out to others when we need help and to know how to respond to others reaching out to us when \textit{they} need help.
|
|
|
|
The problem is that while I've pretty much spent my life doing technical writing, my resume doesn't reflect that. Like I said, I did a lot of technical writing in my last job\footnote{One of the best compliments I've ever received is that a former colleague who also left that company and eventually went back to it told me that she could ``see my hand in everything we do'' which is a great compliment, but after all, I \textit{literally} wrote the book on that place. She wanted me to come back, but nope, there were reasons that I left, and they haven't changed.} but I also did so many other things my resume is a bit of a mish-mash. I have always been a jack-of-all-trades/master-of-none so I need to make sure my cover letter reflects that. We shall see how it goes. (I have a lot to say about this, but I'll save it for later.)
|
|
|
|
If issue \#6 comes out within three months of this issue and has an orange cover you'll know I've been successful. The future awaits us, at least for now.
|
|
|
|
|
|
\chapter{Dependency Heck}\label{dephell}
|
|
|
|
\section{Multiple Paths to \textit{Almost} the Same Destination}
|
|
|
|
I use Okular as a pdf viewer. Even though Ubuntu has a default pdf viewer (Evince), it doesn't have a lot of features and is unreliable in some ways. Okular has always been a better choice for me.
|
|
|
|
The problem is that there is no perfect way to install things in Linux. There are many different ways, and some ways are better than others. I had originally installed Okular from the GNOME Software store. The version it installed was an older one though, and it would not update to a newer version that had a feature I wanted.\footnote{Specifically, the option to view bookmarks from a single pdf document, rather than all of them. I get why you \textit{sometimes} might want to view all the bookmarks in every document, but it doesn't make sense to me to have that on all the time.}
|
|
|
|
I decided to uninstall that one and then install it from Flatpak. This gave me the latest version (24.05.1) which \textbf{did} have this feature. The problem then became that Okular would not open new documents in tabs—it opened each one in a separate window, which I just find annoying. This works if you use \texttt{File $\rightarrow$ Open} to open your pdfs, but who does that? That's the point of a GUI—you can just double-click on files to open them.\footnote{As it turns out this is not so much an Okular issue as it is an ``Okular in Flatpak'' issue. See \kref{https://github.com/flathub/org.kde.okular/issues/36}{https://github.com/flathub/org.kde.okular/issues/36} and \kref{https://bugs.kde.org/show_bug.cgi?id=427653}{https://bugs.kde.org/show\_bug.cgi?id=427653} for more information.} So I uninstalled the Flatpak version until they get that bug fixed (although a bug report was filed for this issue in 2020, so it doesn't look like a priority).
|
|
|
|
I tried installing it directly through snap using this command:
|
|
|
|
\input{include/snapinstallokular}
|
|
|
|
\noindent{}and this \textit{did} give me the latest version. But it wouldn't open. I tried opening it from the command line and got this:
|
|
|
|
\begin{Verbatim}[breaklines=true]
|
|
/snap/okular/155/usr/bin/okular: error while loading shared libraries: libKF6Parts.so.6: cannot open shared object file: No such file or directory
|
|
\end{Verbatim}
|
|
|
|
This is, believe it or not, progress. What this is telling us is that Snap (or possible Ubuntu—I am not entirely sure here) did not install all of the required dependencies, which in this case is \texttt{libKF6Pars.so.6}. So the issue now is: where can we can get that dependency from?
|
|
|
|
Time for some more command-line magic:
|
|
|
|
\input{include/sudofindsnap}
|
|
|
|
That gave me this information:
|
|
|
|
\begin{Verbatim}[]
|
|
/snap/kf6-core22/30/usr/lib/x86_64-linux-gnu/libKF6Parts.so.6
|
|
\end{Verbatim}
|
|
|
|
which tells us that this particular dependency is contained in \texttt{kf6-core22}. To install that, we use:
|
|
|
|
\input{include/sudoinstallkf6}
|
|
|
|
Unfortunately that told me that this dependency was already installed. But it's probably an older version of it that will run with this newer, improved version of Okular. That's okay, we can fix that with
|
|
|
|
\input{include/snaprefresh}
|
|
|
|
That updates the dependencies and also means that Okular will run. A quick check of \texttt{Help $\rightarrow$ About Okular} confirmed that I am on version 24.05.1 and that new documents are opening in tabs when I double click on them in the file manager.
|
|
|
|
\section{What Are Dependencies?}
|
|
|
|
This naturally leads us to the question—\textit{what is a dependency?}
|
|
|
|
I'm so glad you asked.
|
|
|
|
The short answer is that a dependency is a collection of code that another piece of software relies on to do something. Which leads us to another question—why doesn't the software in question contain all the code that it needs to have in order to operate? Why do we bother with dependencies?
|
|
|
|
The reason is that a lot of different software packages all need to do the same thing. So rather than include that other thing in each software package, we can bundle it into a \textit{library}—a bit of software that other software packages can rely upon if they need to. When they do that, this library is now a dependency. The software package in question can't run without it.
|
|
|
|
To make things even less clear, a dependency doesn't necessarily have to be a library. It could be something like a configuration file, a device driver, or even a database.
|
|
|
|
This is where things get confusing when it comes to computers. Not all dependencies are libraries (some are other things, like I mentioned), but not all libraries are dependencies. They are only dependencies for a particular bit of software. You can have a library on your computer which isn't used by any particular software package, and thus it is not a dependency. You can also have a library which is used by software package Foo, and so it's a dependency of Foo, but it's not used by software package Bar, so it's not a dependency of Bar.\footnote{If you are not familiar with the ``Foo'' and ``Bar'' terminology, they are simply words that computer people use to substitute for anything else, be it a software package, a function, etc.}
|
|
|
|
For what it's worth, it's not just Linux that does this. Windows also makes use of \texttt{.dll} files—Dynamic Link Libraries. These contain code and data that can be used by multiple programs. For example, there is a \texttt{.dll} file that just handles ``Open'' dialogue boxes. If you are writing a program for Windows, you don't need to worry about creating your own ``Open'' dialogue boxes. You can just call up this \texttt{.dll} file instead.
|
|
|
|
That's the real reason for using libraries. If you are writing software, chances are it's going to do a lot of things that other software packages do, like throwing up an ``Open'' dialogue, or printing a document, or displaying something on a monitor. There is no point in creating everything from scratch when so many of the basic things (and a lot of the advanced things) have already been built.
|
|
|
|
Using shared libraries also reduces the number of resources your computer is using. If you have ten different applications running, they can use these shared libraries which are probably already loaded into memory, rather than loading their own. As a result, you use less memory and things run faster.
|
|
|
|
Another advantage of using shared libraries is that they are well-written and usually perform without issues, because they are written by people who really know what they're doing. I may not have the foggiest idea of how to create an ``Open'' dialogue box, but I could figure it out if I had unlimited time and resources. The problem is that my time and resources are finite, so it's a better use of my time to rely on a library that already does this thing and does it well.
|
|
|
|
The biggest advantage of using shared libraries (at least these days) is \textit{security}. If a security flaw is found in a shared library, it only has to be fixed once. And because many, many people are using those shared libraries, security vulnerabilities have a better chance of being found—and fixed—quickly.
|
|
|
|
\section{Dependency Hell}
|
|
|
|
Once you start to get into Linux, you inevitably hear about ``Dependency Hell''. This used to be a huge problem, but it has largely gone away.
|
|
|
|
Note that I said ``largely'' and not ``completely''. Hence, dependency \textit{heck}.
|
|
|
|
Dependency hell is what happens when you try to install new software on your computer, but some of the dependencies are missing, conflict with one another, or have been deprecated.\footnote{Because this is no longer much of a problem, I don't want to get into it too much. If you are interested, Wikipedia has an excellent article on dependency hell at \kref{https://en.wikipedia.org/wiki/Dependency\_hell}{https://en.wikipedia.org/wiki/Dependency\_hell}.} This problem has largely gone away due to the use of package managers, which handle the actual compiling and installation of software, because they handle issues with dependencies for you.
|
|
|
|
For example, on Debian/Ubuntu systems, the default package manager is \texttt{apt}. Red Hat/Fedora uses \texttt{dnf}, openSUSE uses \texttt{zypper}, Gentoo uses \texttt{emerge}, and ArchLinux uses \texttt{pacman}. In fact, the ArchLinux wiki has a page which extensively documents the difference between these different package managers.\footnote{See \kref{https://wiki.archlinux.org/title/Pacman/Rosetta}{https://wiki.archlinux.org/title/Pacman/Rosetta}.} If you've never gotten further than \texttt{sudo apt install foo}, you will find a lot of useful information there.
|
|
|
|
I know I did. For example, I usually install software using \texttt{sudo apt install foo}, but there is a parameter which will just do a dry run of the install: \texttt{sudo apt install -{}-dry-run}.\footnote{Which I would know about if I had read the \texttt{man} file for \texttt{apt}, which I obviously have not—in general when working in \texttt{sudo} I just want to do my business and get out.}
|
|
|
|
For example, if I'm thinking about install \texttt{meld} (which is a great tool for visually comparing files and directories, and which will help you merge them), but I'm not sure what all is going to be installed, I can just run
|
|
|
|
\input{include/installmeld}
|
|
|
|
which then gives me this output:
|
|
|
|
\begin{Verbatim}[frame=lines, numbers=left, xleftmargin=5mm, framesep=3mm, breaklines=true, label=\fbox{apt install Dry Run Output}]
|
|
NOTE: This is only a simulation!
|
|
apt needs root privileges for real execution.
|
|
Keep also in mind that locking is deactivated,
|
|
so don't depend on the relevance to the real current situation!
|
|
Reading package lists... Done
|
|
Building dependency tree... Done
|
|
Reading state information... Done
|
|
The following packages were automatically installed and are no longer required:
|
|
libwmf0.2-7 php8.2-common php8.2-mysql
|
|
Use 'apt autoremove' to remove them.
|
|
The following NEW packages will be installed:
|
|
meld
|
|
0 upgraded, 1 newly installed, 0 to remove and 0 not upgraded.
|
|
Inst meld (3.20.4-2 Ubuntu:22.04/jammy [all])
|
|
Conf meld (3.20.4-2 Ubuntu:22.04/jammy [all])
|
|
\end{Verbatim}
|
|
|
|
This is highly useful information, so let's break this down a bit.
|
|
|
|
\begin{enumerate}
|
|
\item First, \texttt{apt} is telling me that this is only a simulation, so I don't have to go into Karen mode when I try to run this application later and can't find it.
|
|
\item It's also reminding me that \texttt{apt} needs root privileges to actually do anything. I didn't use \texttt{sudo} here because I don't want to get in the habit of using it all the time.\footnote{Which is the same reason I don't use the ATM at a casino. If I'm out of money, it's time to go home. There's no point in training your brain with bad habits.}
|
|
\item It also tells me that I have a few packages that I don't really need, and it provides the command I need to remove them.
|
|
\item It then tells me which packages it will install. In this case, it's only going to install the \texttt{meld} package, which means either that \texttt{meld} doesn't need any dependencies, or that all the ones that it needs to function are already on my system.
|
|
\end{enumerate}
|
|
|
|
This is the kind of information I need to think about before I install something. How many new packages will I have to install? How much space will it need? What am I even doing with my life? (Okay, there's no option for that, but it sure would be nice if there were one, wouldn't it?)
|
|
|
|
\section{Containers}
|
|
|
|
As a way around any risk of dependency hell (or dependency heck), software developers have also started putting their software into containers. A container is basically an entire runtime environment: it's your application, all of its required libraries and binaries, along with any configuration files, all bundled into a single package.
|
|
|
|
And yes, if it seems like we are moving backward, we are, in a way. I'm not going to say too much about these because I am not terribly familiar with them, although I've used a few of them. This is going to be a very brief rundown, because if I go into too much detail, I am likely to be wrong.\footnote{To be honest, I'm not even sure that the word ``container'' is the right word here because a lot of people on the internet cannot agree. Just be aware that if you research any of this on the web, you will find a lot of people who agree with my characterization (yay! I'm right!) and you will also find a lot of people who disagree with my characterization (poop! I'm wrong!). Such is life.}
|
|
|
|
\paragraph{Snap} First developed by Canonical (which is the for-profit company behind Ubuntu) this creates a new directory in your \texttt{\$HOME} directory to install snaps. (I did not like this at first, but okay, whatever.) One of the ideas behind snaps is that you can run different versions of the same program. Which would be handy, except that the people responsible for maintaining the snap packages do a pretty crap job of it, and most snaps are a version or two (or more) behind the current release version.
|
|
|
|
\paragraph{Flatpak} A quick look at the Flatpak home page\footnote{\kref{https://flatpak.org/}{https://flatpak.org/}} shows that they consider themselves ``The future of apps on Linux''. That's pretty confident. But the idea is pretty much the same as a snap. You first have to install \texttt{flathub}, then you download the relevant file from \kref{https://flathub.org/}{https://flathub.org/} and install it. It's not perfect, but for the one app\footnote{Paper Clip, which allows you to quickly and easily edit a pdf file's metadata. If you need to do that, I highly recommend it. See \kref{https://flathub.org/apps/io.github.diegoivan.pdf_metadata_editor}{https://flathub.org/apps/io.github.diegoivan.\\pdf\_metadata\_editor} for details.} I need that is only available as a Flatpak, I suppose it works well enough. But I would hate to have to install \textit{all} of my software this way.
|
|
|
|
\paragraph{AppImage} This is perhaps the simplest one I've used—you just download a file, make it executable,\footnote{You do this by updating the execute bit with \texttt{chmod +x file.AppImage}.} and then run it. I don't have too much of an issue with this one, but I only have a couple of apps that run from an AppImage. (Among them is the Cool Retro Terminal,\footnote{\hspace*{-1mm}\kref{
|
|
https://github.com/Swordfish90/cool-retro-term}{
|
|
https://github.com/Swordfish90/cool-retro-term}} which takes me right back to my days in seventh grade. It's pretty cool, but depending on the day it either makes me sad or happy, so I don't use it often.)
|
|
|
|
\section{What Probably Happened Here}
|
|
|
|
Dependency hell is suppposed to be a thing of the past, so I'm not quite sure why I ran into an issue with dependencies when trying to install a different version of Okular.
|
|
|
|
It's possible that the snap was configured wrong. It's also possible that I borked\footnote{I.e., I misconfigured or broke something.} something without realizing it when I was doing something else. (I do have a tendency to tinker with things under the hood.) Unlike the days of old I did not have to spend hours or days trying to figure this out. A couple of quick web searches got me up and running again.
|
|
|
|
|
|
\chapter{A \texttt{git} Primer}
|
|
|
|
\lettrine[lines=2, loversize=0.2, findent=2mm, nindent=1mm, image=true]{git-icon}{} Git is version control software. That is, it allows you to record and track changes to a set of files over time. You can then compare different revisions or even revert some files or the entire project back to a previous version.
|
|
|
|
What I'm going to do here is describe how I understand Git. I am far from a power-user or expert in Git, so I may get some things wrong. This is \textit{not} intended to be comprehensive, but more just a way for you to get your feet wet. My goal is to encourage you to think about how you might benefit from using Git.
|
|
|
|
\section{What Git Can Do For You}
|
|
|
|
Git is great if you are a software developer, because as you work you make a \textit{lot} of changes to your code. It's also great if you are a writer, because you can experiment as much as you want and not have to worry about losing or overwriting something. You can just revert to an earlier version, or \textit{branch} in order to experiment. But more about that later.
|
|
|
|
Git works best with text-based files—basically, anything that has a \texttt{.txt}, \texttt{.html}, \texttt{.css}, \texttt{.php}, etc. extension will work. There's no reason that you can't add binaries, such as images, pdfs, Microsoft Word files, or LibreOffice files. (I'm writing this zine in \LaTeX{}, and do include a few images in most issues, for example.) The issue is that because they are binaries, Git won't be able to tell you the difference between versions. (I would add, though, that if you are writing, you really should separate out the content and the styling from the beginning, so that you can focus on the story you want to tell. Plain text files are your friends.)
|
|
|
|
\section{Git Concepts}
|
|
|
|
If this is your first exposure to version control software you'll make faster progress if you understand some of the basic concepts. If you are coming to Git from a different version control software, then some or all of these concepts will be familiar to you, although they will probably have different names and probably different functions. Keep in mind that all of these technologies work differently, so you may have to retrain your brain to follow a different workflow.
|
|
|
|
\paragraph{Concept One: Git exists in both time and space.} This is true of just about all version control software, or at least all the different types I am aware of.
|
|
|
|
\paragraph{Concept Two: The basic time unit of Git is a \textit{commit}.} A commit is simply a snapshot of where your project stands at any given moment. When you make a commit, it's like taking a picture of your project at that particular moment.
|
|
|
|
\paragraph{Concept Three: The basic space unit of Git is a \textit{repository}.} All those commmits have to live somewhere, and a repository is just a place where all those commits exist. Repositories (or ``repos'' for short) can be \textit{local}—that is, they exist on your computer only—or they can be \textit{remote}—meaning that can live on other computers somewhere else. That ``somewhere else'' is usually a publicly available server. You can create your own\footnote{You can see mine at \kref{https://git.kjodle.net/}{https://git.kjodle.net/} for example.} or you can get an account at someplace like Gitlab\footnote{\kref{https://gitlab.com/}{https://gitlab.com/}} which is for-profit and wants your money, or Github\footnote{\kref{https://github.com/}{https://github.com/}} which is now owned by Microsoft and wants your soul.
|
|
|
|
You can work with a local repository only, or you can decide to work with one or more remote repositories. The choice is up to you.
|
|
|
|
\paragraph{Concept Four: Repositories are multi-dimensional.} If you make a series of commits to a repository, it will be linear in nature. This is perfectly ordinary. But you may get to a point where you want to experiment with something and you're not sure whether you'll like the new version or the old version better. Rather than commit that new version, which overrides the original version, you can \textit{branch} and have both versions existing at the same time. A branch is basically a copy of a repository at this point in time (i.e., from the last commit). You can then switch between branches and test things out. You can treat it like a sandbox—but more about that later.
|
|
|
|
\section{Git Clients}
|
|
|
|
Git is a command line based technology. Yes, there are GUIs out there for Git, and if you are on Windows or macOS, you may find them useful. You can see a fairly comprehensive list at \kref{https://git-scm.com/book/en/v2/Getting-Started-Installing-Git}{https://git-scm.com/book/en/v2/G\\etting-Started-Installing-Git}.
|
|
|
|
In general, I advise against using any type of GUI with Git. For one thing, Git is fairly easy to manage from the command line, so using a GUI just adds a level of abstraction that we don't really need. For another, the command line is forever, but GUIs come and go. If your GUI gets to a point where it's development is discontinued, or it decides to adopt a subscription model that you can't afford, you're screwed.
|
|
|
|
A GUI can also obscure what Git is actually doing, meaning that you might end up with less understanding of Git than you would by working on the command line.
|
|
|
|
\section{Local Repositories}
|
|
|
|
Let's start with local repositories. Assuming you have a folder full of files you want to track using Git, open a terminal window in that location (which is now called your ``working directory'') and type \texttt{git init}. Congratulations! You now have a local Git repo!
|
|
|
|
What has happened is that Git has created an invisible directory (\texttt{.git}) that it will use to store the metadata and database for your project. Do \textbf{not} delete this folder!
|
|
|
|
Technically, the \texttt{.git} directory is the actual repository. But most people think of the folder that contains your working files along with the \texttt{.git} directory as a repo. As far as I can tell, it doesn't really matter. Just be aware that a) this distinction exists, and b) some people on the internet can be incredibly pedantic about it (sometimes with reason, and often without).
|
|
|
|
We haven't made any commits yet, though. All we have are files in our working directory. To make a commit, we need to \textit{stage} our files by using the \texttt{git add} command. You can do this a couple of different ways: we can either list each file one by one (i.e., \texttt{git add file1.txt file2.txt}) or we can just add them all in a single go by using the \texttt{*} wildcard (\texttt{git add *} which will \textit{not} add invisible files, or \texttt{git add -A} which \textit{will} add invisible files).
|
|
|
|
Now that you've added your files, they are considered to be \textit{staged}, which means that they are ready to commit. You can make a commit now, or you can modify or create new files, and then add them as well. The choice is yours—Git doesn't penalize you either way. Personally, I prefer to make many smaller commits to avoid losing data (and metadata).
|
|
|
|
If you're happy with the files you've staged, we can now commit them by using \texttt{git commit -m "<commit message>"}. Note that you have to add a commit message. This can be anything you like, but it helps to make it something that will be useful down the road like ``updated chapter three''. You'll get some miscellaneous messages about what Git is doing and then it is done. You've created your first commit, and all of your staged files are now \texttt{committed}.\footnote{You can also make this process even more efficient by creating some bash alias for the various Git commands. See ``More Fun with bash'' in issue \#4.}
|
|
|
|
\section{Branches}
|
|
|
|
If you want to experiment, the best way to do that is to create a \textit{branch}. To do that, just use \texttt{git branch <name>}. To move to that branch, you check it out\footnote{For a visual depiction, see, \kref{https://www.youtube.com/watch?v=8qxDBiiVjlQ}{https://www.youtube.com/watch?v=8qxDBiiVjlQ}.} using \texttt{git branch checkout <branchname>}.
|
|
|
|
Of course, there's a shortcut to this. You can use
|
|
|
|
\input{include/checkout}
|
|
|
|
\noindent{}which creates a branch called ``branchname'' and moves you to it automatically.
|
|
|
|
This is the point where you can experiment and have fun on this branch without worrying about messing up your main branch. Wouldn't it be nice if life were like this?\footnote{Gosh, I've mentioned this twice. There are lots of science fiction stories about this possibility. I guess it's time to go read one. Or write one.} If you like the changes that you made on this branch, you can then go back to your main branch (\texttt{git checkout main}) and \textit{merge} those changes.
|
|
|
|
\input{include/merge}
|
|
|
|
It's always a good idea to clean up after ourselves. If we don't need that experimental branch any more, we can delete it with \texttt{git branch -d <branchname>}.
|
|
|
|
In reality, things are rarely going to be this simple, unless you are only making very basic changes to a branch. You'll likely get all sorts of error messages or warning messages, and will get confused or even scared. Never fear! The nice thing about Git is that most of the solutions you need are easily found at the other end of a web search.
|
|
|
|
\section{Remote Repositories}
|
|
|
|
Remote repositories make it possible to share your work and to collaborate with others. You can do all sorts of things locally, but at some point, you're probably going to want to put your work out there, or just to show off.
|
|
|
|
\subsection{Getting a Remote Repository}
|
|
|
|
If you set up a remote repo on some place like GitHub, or you find a repo somewhere that you would like to work with on your own, you can \textit{clone} that remote repo like this:
|
|
|
|
\input{include/clone}
|
|
|
|
For example, if you wanted to get a copy of the Apollo 11 Guidance Computer source code because you happen to be planning a trip to the moon of your own,\footnote{I was delighted to find out that this was available on GitHub. I first learned about this in the Volume Thirty-Eight, Number Four issue of \textit{2600} in an article called ``Supply and Demand, Apollo 11, and GitHub'', which is something I will probably talk about in the future.} you would just type \texttt{git clone https://github.com/chrisl\\garry/Apollo-11}. Git would create a directory called ``Apollo-11'' and clone a local version of that entire repository into it.
|
|
|
|
If you want to see the remotes attached to this repo, you can just type \texttt{git remote -v}. In this case, it would show you something like this:
|
|
|
|
\begin{Verbatim}[]
|
|
origin https://github.com/chrislgarry/Apollo-11 (fetch)
|
|
origin https://github.com/chrislgarry/Apollo-11 (push)
|
|
\end{Verbatim}
|
|
|
|
Of course, those remote repositories don't belong to you, so you can't push any changes you make to them. What you can do is create your own remote repo on a Git-hosting system. I'll do that on my Git site at \kref{https://git.kjodle.net/kjodle/Apollo-11}{https://git.kjodle.net/kjodle/Apollo-11}. To add that remote to my local repo, I will use this:
|
|
|
|
\input{include/remoteadd}
|
|
|
|
And running the \texttt{git remote -v} command again shows that I have two different remotes:
|
|
|
|
\begin{Verbatim}[]
|
|
ogit https://git.kjodle.net/kjodle/Apollo-11 (fetch)
|
|
ogit https://git.kjodle.net/kjodle/Apollo-11 (push)
|
|
origin https://github.com/chrislgarry/Apollo-11 (fetch)
|
|
origin https://github.com/chrislgarry/Apollo-11 (push)
|
|
\end{Verbatim}
|
|
|
|
I named my remote ``ogit'', which is the first letter of my last name combined with ``git''. I need to get rid of those remotes on GitHub, since I can't push any changes to them anyway. To do that I'll use this command:
|
|
|
|
\input{include/remoteremove}
|
|
|
|
Running \texttt{git remote -v} again shows that I now just have the remote on my own website:
|
|
|
|
\begin{Verbatim}[]
|
|
ogit https://git.kjodle.net/kjodle/Apollo-11 (fetch)
|
|
ogit https://git.kjodle.net/kjodle/Apollo-11 (push)
|
|
\end{Verbatim}
|
|
|
|
Are we ready to upload this code from my local repository to my remote repo? Not yet. Let's see what our local branches are by running \texttt{git branch}, which gives us this:
|
|
|
|
\begin{Verbatim}[]
|
|
* master
|
|
\end{Verbatim}
|
|
|
|
In this case, I only have a single branch, which is named ``master''. It also has an asterisk because it's the current branch. The problem here is that my Git website always names branches ``main''. So I need to change that branch name by running
|
|
|
|
\input{include/branchrename}
|
|
|
|
Running \texttt{git branch} again confirms that our branch has been renamed:
|
|
|
|
\begin{Verbatim}[]
|
|
* main
|
|
\end{Verbatim}
|
|
|
|
\subsection{Pushing Changes to a Remote Repository}
|
|
|
|
Okay, I have a local repository, I have a remote repository attached to that local repository, and the current branch on both repos have the same name. It's time to move that code from the local repository to the remote one. For that I'll use \texttt{git push} <name of remote repo> <name of current branch>. Since the remote is named ``ogit'' and the branch is named ``main'', the full command looks like this:
|
|
|
|
\input{include/push}
|
|
|
|
I did that, and Git thought for a moment, and produced this output:
|
|
|
|
\begin{Verbatim}[breaklines=true]
|
|
Enumerating objects: 3414, done.
|
|
Counting objects: 100% (3414/3414), done.
|
|
Delta compression using up to 4 threads
|
|
Compressing objects: 100% (1077/1077), done.
|
|
Writing objects: 100% (3414/3414), 3.01 MiB | 1.69 MiB/s, done.
|
|
Total 3414 (delta 2327), reused 3414 (delta 2327), pack-reused 0
|
|
remote: . Processing 1 references
|
|
remote: Processed 1 references in total
|
|
To https://git.kjodle.net/kjodle/Apollo-11
|
|
* [new branch] main -> main
|
|
\end{Verbatim}
|
|
|
|
That really did take only about 1 second to push 3.1 MiB\footnote{That's not a typo. MiB stands for a \texttt{mebibyte}. See ``The Later Salad Days'' in issue \#2 for more information.} of data. One of the nice things about Git is that it is remarkably fast.
|
|
|
|
If you visit that original repository that I cloned on GitHub, you'll see that it has 547 commits. If you then visit the repository I created at \kref{https://git.kjodle.net/kjodle/Apollo-11}{https://git.kjodle.net/kjodle/Apollo-11}, you'll see that it also has 547 commits. This is one of the nice things about Git: when you clone that remote repository, you are getting \textit{everything} associated with that repo. Other version control applications just checkout the most recent version. Hence the term ``clone'' rather than ``checkout''.
|
|
|
|
For what it's worth, you can have multiple remotes. I can create a remote repository on GitHub, clone it to my local machine, then create a remote somewhere else and add that remote to my local repo. To keep both remotes up to date with local changes, you'll need to push twice, once with \texttt{git push remote1 main} and again with \texttt{git push remote2 main}.
|
|
|
|
There is a lot more to it than this (I haven't even talked about \texttt{git status} yet!), so I guess I will leave that for part 2 of this primer.
|
|
|
|
\subsection{Collaborating With Yourself}
|
|
|
|
I mentioned earlier that you could use Git if you're a writer to keep track of changes to projects, provided you were willing to work with text files. My goal here is to provide at least one workflow for doing that. I'm going to assume a few things:
|
|
|
|
\begin{enumerate}[noitemsep]
|
|
\item You have a remote somewhere on a repository host (like GitHub or your own website).
|
|
\item You write all your stories in plain text files in a local repo.
|
|
\item Your repository host allows you to edit files on their website. (I can do this on my own site with Gitea\footnote{\kref{https://gitea.com/}{https://gitea.com/}} but I'm not sure about other sites.
|
|
\end{enumerate}
|
|
|
|
The advantage to the workflow I'm describing here is that you can work on your files even if you are not working from your normal machine. Thanks to family medical issues, I sometimes spend a lot of time in hospital waiting rooms and I bring my Chromebook with me. I can edit my files on the web, and then pull down changes to my main laptop (which never leaves my house) when I get home. This is how I do it.
|
|
|
|
I'll physically go to wherever we are for the day (library, caf\'e, hospital waiting room, etc.) and login to my repository host. I can edit files online using this button:
|
|
|
|
\begin{center}
|
|
\noindent{}\frame{\includegraphics[scale=0.75]{gitea-online-edit}}
|
|
\end{center}
|
|
|
|
At the end of the day, I'll home and go into my local repo, open a terminal in that directory and use the \texttt{git pull} command:
|
|
|
|
\input{include/pull}
|
|
|
|
What does \texttt{git pull} do? It's a combination of two Git commands: \texttt{fetch} and \texttt{merge}.
|
|
|
|
\texttt{git fetch} gets the change history of the tracked remote and branch, whereas \texttt{git merge} combines the current branch with the specified branch. My local repository will now look like My remote repository. I can write to my heart's content, push those changes, and call it a day. If I'm back at the hospital waiting room again some time later, I can just repeat the process.\footnote{Again, for a visual depiction of this, please visit \kref{https://www.youtube.com/watch?v=FG1NrQYXjLU}{https://www.youtube.com/watch?v=\\FG1NrQYXjLU}.}
|
|
|
|
\section{Extra Files}
|
|
|
|
If you pull or clone a remote repository, you may notice files like \texttt{.gitignore} and \texttt{README.md}. The first tells Git which files to \textit{not} track. (And yes, you will want to make use of this at some point.) The second is a text document written in Markdown (hence the \texttt{.md} file extension) which appears on the front page of the online repo.
|
|
|
|
\section{Forks and Pull Requests}
|
|
|
|
These things aren't a part of Git, but they are something that is offered by GitHub and other repository hosts, so I just want to give the briefest of descriptions here for clarity and completion.
|
|
|
|
To \textit{fork} a remote repository is to make a copy of it so that you can contribute to this project. You fork somebody else's project, clone it locally, make your changes, push those changes to your remote repo, and then make a \textit{pull request}, which alerts the owner of the original repository that you have changes you'd like them to incorporate into their project. They can then pull those changes in, or they can ignore them.
|
|
|
|
\section{Summary of Git Commands}
|
|
|
|
One of my favorite aspects of Git is that it's fairly intuitive to understand and start using right out of the box, but it's also robust enough to meet the needs of large teams and organizations. What I've done in the following table is to summarize the commands I've used in this primer, along with examples where appropriate.
|
|
|
|
\begin{longtblr}
|
|
[
|
|
caption = {Summary of Git Commands},
|
|
label = {tb:gitcommsum},
|
|
% theme = {custom1}
|
|
]{
|
|
width = {\textwidth},
|
|
colspec = { X[20,l] X[80,l] },
|
|
hlines = {0.5pt,solid},
|
|
vline{1,3} = {0.5pt,solid},
|
|
rows = {5mm, m, rowsep=1.5pt},
|
|
rowhead = 1,
|
|
cells = {font=\sffamily\fontsize{8pt}{11pt}\selectfont},
|
|
row{1} = {font=\bfseries},
|
|
}
|
|
Command & Purpose {\& Example, if applicable} \\
|
|
\texttt{git init} & {Creates a local git repository \\ \texttt{git init} } \\
|
|
\texttt{git clone} & {Clones a remote repository locally \\ \texttt{git clone} <URL of remote reposistory> } \\
|
|
\texttt{git -{}-version} & Displays the version of git installed on your system \\
|
|
\texttt{git add} & {Stages (i.e., adds) files to a commit \\ \texttt{git add file1 file2} } \\
|
|
\texttt{git add *} & Stages (i.e., adds) all visible files to a commit \\
|
|
{\texttt{git add -A} \\ \texttt{git add --all}} & Stages (i.e., adds) all files (including invisible ones) to a commit \\
|
|
\texttt{git branch} & Show all branches (the current branch is labeled with an asterisk) \\
|
|
\texttt{git branch -{}-show-current} & Show only the current branch \\
|
|
\texttt{git commit} & {Commits stages files \\ \texttt{git commit -m} ``<commit message>'' } \\
|
|
\texttt{git fetch} & Get the change history of a specific tracked remote and branch \\
|
|
\texttt{git merge} & Incorporate changes from the named commits into the current branch \\
|
|
\texttt{git pull} & A combination of \texttt{fetch} and \texttt{merge} \\
|
|
\texttt{git push} & {Pushes a commit from a local repo to a remote repo \\ \texttt{git push} <name of remote repo> <name of remote branch> } \\
|
|
\texttt{git remote} & {Show only the names of remote repos \\ \texttt{git remote} } \\
|
|
\texttt{git remote -v} & {Show both the names and URLs of remote repos \\ \texttt{git remote -v} } \\
|
|
\texttt{git status} & Show which files have been staged and which files are waiting to be staged \\
|
|
\texttt{git status -s} & As above, but in short form \\
|
|
\texttt{git status -u} & As above, but only show untracked files \\
|
|
\end{longtblr}
|
|
|
|
|
|
\chapter{Easy Outlines in \LaTeX{}}
|
|
|
|
Ever since I first learned about outlining in high school (or was it earlier?) I've always loved being able to organize information hierarchically. The irony is that I also love biology and the natural world does not necessarily organize itself in a hierarchical way. Cross-pollination and inter-species breeding is a thing, after all.
|
|
|
|
You can use the built-in \texttt{enumerate} environment to create outlines, but it requires lots and lots of nested \texttt{enumerate} environments. (\texttt{html} is the same way—an occupational hazard, I suppose, of liking both outlines and computers.) I grew up using a typewriter where outlines are pretty much just tab stops, so I've always been looking for something simpler on a computer.
|
|
|
|
Fortunately, \LaTeX{} does have something simpler—the \texttt{outlines} package.
|
|
|
|
\section{The \texttt{outlines} Package}
|
|
|
|
Loading it is pretty easy, as it has no options. You just add this to your preamble:
|
|
|
|
\begin{Verbatim}[]
|
|
\usepackage{outlines}
|
|
\end{Verbatim}
|
|
|
|
and then you use the \texttt{outline} environment like this:
|
|
|
|
\begin{Verbatim}[frame=lines, numbers=left, xleftmargin=5mm, framesep=3mm, breaklines=true, label=\fbox{outlines Example}]
|
|
\begin{outline}
|
|
\1 First Item
|
|
\2 First sub-item
|
|
\2 Second sub-item
|
|
\1 Second Item
|
|
\2 Another sub-item
|
|
\2 A fourth sub-item
|
|
\3 A sub-sub-item
|
|
\3 Yet another sub-sub-item
|
|
\4 A fourth-level item, all by itself just to annoy your English teacher
|
|
\end{outline}
|
|
\end{Verbatim}
|
|
|
|
which gives us this beautiful outline:
|
|
|
|
\begin{outline}
|
|
\1 First Item
|
|
\2 First sub-item
|
|
\2 Second sub-item
|
|
\1 Second Item
|
|
\2 Another sub-item
|
|
\2 A fourth sub-item
|
|
\3 A sub-sub-item
|
|
\3 Yet another sub-sub-item
|
|
\4 A fourth-level item, all by itself just to annoy your English teacher
|
|
\end{outline}
|
|
|
|
The indents in your source code are absolutely not necessary, but indenting with tabs or spaces can help you keep visual track of things. The actual levels are controlled by the number after the backslash.
|
|
|
|
\section{Caveats}
|
|
|
|
You are limited to four levels of indentation. (This is a part of \LaTeX{}.\footnote{It is possible to build list environments with more than four levels, but I don't think they would automatically work with the \texttt{outlines} package. However, its code is fairly straightforward and simple, so if I get time, I may play around with making my own package.}) You can always introduce a normal, non-itemized paragraph into your list by using \verb|\0| as a list item, which prevents you from having to end a previous environment and then create a new one.
|
|
|
|
\begin{Verbatim}[frame=lines, numbers=left, xleftmargin=5mm, framesep=3mm, breaklines=true, label=\fbox{outlines Example with Normal Paragraph}]
|
|
\begin{outline}[enumerate]
|
|
\1 First Item
|
|
\2 First sub-item
|
|
\2 Second sub-item
|
|
\0 This is a non-itemized, non-indented paragraph
|
|
\1 Second Item
|
|
\2 Another sub-item
|
|
\3 A sub-sub-item
|
|
\3 Yet another sub-sub-item
|
|
\4 A fourth-level item, all by itself just to annoy your English teacher
|
|
\end{outline}
|
|
\end{Verbatim}
|
|
|
|
gives us this:
|
|
|
|
\begin{outline}[enumerate]
|
|
\1 First Item
|
|
\2 First sub-item
|
|
\2 Second sub-item
|
|
\0 This is a non-itemized, non-indented paragraph
|
|
\1 Second Item
|
|
\2 Another sub-item
|
|
\3 A sub-sub-item
|
|
\3 Yet another sub-sub-item
|
|
\4 A fourth-level item, all by itself just to annoy your English teacher
|
|
\end{outline}
|
|
|
|
This also resets all the counters after that normal paragraph. I think this is fairly typical behavior for outlines, however, so I am okay with this.
|
|
|
|
I also passed the \texttt{[enumerate]} option to the environment, so that instead of symbols, it uses numbers and letters to label the list items, rather than symbols. I like this. It's similar to the outline style I learned in high school.
|
|
|
|
\section{Custom Outline Styles}
|
|
|
|
Unfortunately, this isn't exactly the style of outlining I learned in high school.\footnote{Apparently I learned what the Purdue OWL calls a ``decimal outline''. See \kref{https://owl.purdue.edu/owl/general_writing/the_writing_process/developing_an_outline/types_of_outlines.html}{https://owl.purdue.edu/owl/general\_writing/the\_writing\_process/developing\_an\\\_outline/types\_of\_outlines.html}.} However, it is possible to use \texttt{renewcommand} to change the counter style when using the \texttt{[enumerate]} option to get what we want. What we need to know is that the \texttt{enumerate} list style uses two sets of placeholders to keep track of things. \texttt{labelenumi} etc. determines what kind of label you see, and \texttt{enumi} etc. keeps track of the counter. So we can do something like this:
|
|
|
|
\begin{Verbatim}[frame=lines, numbers=left, xleftmargin=5mm, framesep=3mm, breaklines=true, label=\fbox{Custom Outlining Style in outlines Package}]
|
|
\renewcommand{\labelenumi}{\Roman{enumi}.}
|
|
\renewcommand{\labelenumii}{\Alph{enumii}.}
|
|
\renewcommand{\labelenumiii}{\arabic{enumiii}.}
|
|
\renewcommand{\labelenumiv}{\alph{enumiv})}
|
|
|
|
\begin{outline}[enumerate]
|
|
\1 Top-level item.
|
|
\2 Second-level item.
|
|
\3 Third-level item.
|
|
\4 Fourth-level.
|
|
\end{outline}
|
|
\end{Verbatim}
|
|
|
|
\noindent{}which produces this:
|
|
|
|
\renewcommand{\labelenumi}{\Roman{enumi}.}
|
|
\renewcommand{\labelenumii}{\Alph{enumii}.}
|
|
\renewcommand{\labelenumiii}{\arabic{enumiii}.}
|
|
\renewcommand{\labelenumiv}{\alph{enumiv})}
|
|
|
|
\begin{outline}[enumerate]
|
|
\1 Top-level item.
|
|
\2 Second-level item.
|
|
\3 Third-level item.
|
|
\4 Fourth-level.
|
|
\end{outline}
|
|
|
|
Keep in mind that because we are using the standard \texttt{enumerate} commands, this will affect \textit{all} numbered lists that follow it. We would have to reset these if we need to prevent that from happening. For that, we can use this code:
|
|
|
|
\begin{Verbatim}[frame=lines, numbers=left, xleftmargin=5mm, framesep=3mm, breaklines=true, label=\fbox{Commands to Reset enumerate Environment}]
|
|
\renewcommand{\labelenumi}{\arabic{enumi}.}
|
|
\renewcommand{\labelenumii}{(\alph{enumii})}
|
|
\renewcommand{\labelenumiii}{\roman{enumiii}.}
|
|
\renewcommand{\labelenumiv}{\Alph{enumiv}.}
|
|
\end{Verbatim}
|
|
|
|
If you need to pop in and out of your outlines and also numbered lists quite a bit, you could just turn both sets of those \texttt{renewcommand} lines into macros to make your mischief a bit easier to manage.
|
|
|
|
\section{Customizing \texttt{enumerate} and \texttt{itemize} List Environments}
|
|
|
|
Given all that, it's pretty easy to see how to customize list environments. You just need to know the commands that those environments use to keep track of things. Here's a list of the commands used to generate the labels for both environments:
|
|
|
|
\begin{longtblr}
|
|
[
|
|
caption = {Label Commands for List Environments},
|
|
label = {tb:listcommands},
|
|
% theme = {custom1}
|
|
]{
|
|
width = {\textwidth},
|
|
colspec = { X[16,l] X[41,c] X[41,c] },
|
|
hlines = {0.5pt,solid},
|
|
vline{1,4} = {0.5pt,solid},
|
|
rows = {5mm, m, rowsep=1.5pt},
|
|
rowhead = 1,
|
|
cells = {font=\sffamily\fontsize{9pt}{12pt}\selectfont},
|
|
row{1} = {font=\bfseries\sffamily},
|
|
}
|
|
Level & enumerate commands & itemize commands \\
|
|
Level 1 & \texttt{labelenumi} & \texttt{labelitemi} \\
|
|
Level 2 & \texttt{labelenumii} & \texttt{labelitemii} \\
|
|
Level 3 & \texttt{labelenumiii} & \texttt{labelitemiii} \\
|
|
Level 4 & \texttt{labelenumiv} & \texttt{labelitemiv} \\
|
|
\end{longtblr}
|
|
|
|
Notice that we can also use punctuation around these to affect how they are formatted. For example, here \verb|{\arabic{enumiii}.}| I used a period after the label, and here \verb|{\alph{enumiv})}| I used a closing parenthesis after the label.
|
|
|
|
Because \texttt{enumerate} environments also use numbers, we need some counter variables to keep track of those. They look like this:
|
|
|
|
\begin{longtblr}
|
|
[
|
|
caption = {Counter Variables for Numbered Lists},
|
|
label = {tb:enumcountervar},
|
|
% theme = {custom1}
|
|
]{
|
|
width = {0.7\textwidth},
|
|
colspec = { X[30,l] X[70,c] },
|
|
hlines = {0.5pt,solid},
|
|
vline{1,3} = {0.5pt,solid},
|
|
rows = {5mm, m, rowsep=1.5pt},
|
|
rowhead = 1,
|
|
cells = {font=\sffamily\fontsize{9pt}{12pt}\selectfont},
|
|
row{1} = {font=\bfseries\sffamily},
|
|
}
|
|
Level & enumerate counter variable \\
|
|
Level 1 & \texttt{enumi} \\
|
|
Level 2 & \texttt{enumii} \\
|
|
Level 3 & \texttt{enumiii} \\
|
|
Level 4 & \texttt{enumiv} \\
|
|
\end{longtblr}
|
|
|
|
And what can you make those labels look like? Like this:
|
|
|
|
\begin{longtblr}
|
|
[
|
|
caption = {Counter Variable Formats},
|
|
label = {tb:counterform},
|
|
% theme = {custom1}
|
|
]{
|
|
width = {0.7\textwidth},
|
|
colspec = { X[60,l] X[40,c] },
|
|
hlines = {0.5pt,solid},
|
|
vline{1,3} = {0.5pt,solid},
|
|
rows = {5mm, m, rowsep=1.5pt},
|
|
rowhead = 1,
|
|
cells = {font=\fontsize{9pt}{12pt}\selectfont},
|
|
row{1} = {font=\bfseries\sffamily},
|
|
}
|
|
\textsf{Command} & \textsf{Example} \\
|
|
\texttt{\textbackslash{}arabic\{cv\}} & 1 \\
|
|
\texttt{\textbackslash{}roman\{cv\}} & i \\
|
|
\texttt{\textbackslash{}Roman\{cv\}} & I \\
|
|
\texttt{\textbackslash{}alph\{cv\}} & a \\
|
|
\texttt{\textbackslash{}Alph\{cv\}} & A \\
|
|
\end{longtblr}
|
|
|
|
Just substitute one of the counter variables from table \ref{tb:enumcountervar} in place of the \texttt{cv}.
|
|
|
|
And \textit{that}, my friends, is the easy way to create outlines in \LaTeX{}.
|
|
|
|
\chapter{Coda}
|
|
|
|
\section{What I Learned About \LaTeX{} While Creating This Issue}
|
|
|
|
\subsection{Using \texttt{input} to Keep Your \LaTeX{} GUI Happy}
|
|
|
|
You'll notice that chapter \ref{dephell} has a lot of code samples that include code that you enter into the terminal. As such, they include a dollar sign (\$) to indicate the prompt.
|
|
|
|
While it's easy enough to include those in a \texttt{verbatim} environment, I'm using a GUI to create this (Texmaker, in fact\footnote{See \kref{https://www.xm1math.net/texmaker/}{https://www.xm1math.net/texmaker/} for more information.}) and anything in math mode—that is, anything that follows a dollar sign—is highlighted in green until it gets to another dollar sign, even in a \texttt{Verbatim} environment. If it doesn't, then everything after that dollar sign is green, which kind of defeats the purpose of code highlighting.
|
|
|
|
The easy way around this is to write up those code samples in an independent \texttt{.tex} file, and then use the \texttt{input} command to add them at the appropriate point in my story. That keeps the source code in my GUI nice and clean looking, and means that the semantic highlighting actually represents what it's supposed to represent.\footnote{There is also the \texttt{include} command which is similar. For more about the distinction between the two, see \kref{https://tex.stackexchange.com/questions/246/when-should-i-use-input-vs-include}{https://tex.stackexchange.co\\m/questions/246/when-should-i-use-input-vs-include}. I'll have more to say about this in the next issue.}
|
|
|
|
\subsection{the \texttt{ccicons} package}I release this zine under a Creative Commons license (see page 2). I used to include a small image that summarizes that license, which I had downloaded from the Creative Commons website. As it turns out, the \texttt{ccicons} package will do this for you—no need to add that image.\footnote{I actually learned about this while working on issue \#4, but I was very close to the end and I came across it accidentally—it wasn't something I was looking for. Serendipity is somethings a thing, so here we are.}
|
|
|
|
You can add icons individually, but it also has commands to typeset each license and its icons. Because it's basically just a font, you can do with it whatever you would normally do with other text. For example, these lines
|
|
|
|
\begin{Verbatim}[frame=lines, numbers=left, xleftmargin=5mm, framesep=3mm]
|
|
\ccCopy\ccAttribution\ccNonCommercial\ccNoDerivatives
|
|
\ccbyncnd
|
|
{\footnotesize \ccbyncnd}
|
|
{\huge \ccbyncnd}
|
|
\fbox{\ccbyncnd}
|
|
\end{Verbatim}
|
|
|
|
will produce these examples:
|
|
\medskip
|
|
|
|
\ccCopy\ccAttribution\ccNonCommercial\ccNoDerivatives
|
|
|
|
\ccbyncnd
|
|
|
|
{\footnotesize \ccbyncnd}
|
|
|
|
{\huge \ccbyncnd}
|
|
|
|
\fbox{\ccbyncnd}
|
|
|
|
\medskip
|
|
|
|
Notice that the built-in command (the example on the second line) includes a little bit of space between the icons, which is nice.
|
|
|
|
\subsection{Ligatures and \LaTeX{} }
|
|
|
|
I have a table of basic Git commands on page \pageref{tb:gitcommsum}. One of the commands is \texttt{git -{}-version}. Notice that ``version'' has two hyphens in front of it, as is typical with full-word bash options. But just typing two hyphens didn't display two hyphens when I originally compiled this document, it displayed a single hyphen. I was momentarily confused.
|
|
|
|
What I forgot is that \LaTeX{} has a habit of collapsing multiple hyphens into ligatures. Two hyphens get converted to an en-dash, and three hypens get converted to an em-dash. But because this was displaying in a monotype font, it looked like an ordinary hyphen, even though it was an en-dash.
|
|
|
|
The fix for this was to use the \texttt{\{\}} token between the two hyphens. Without it, \LaTeX{} sees the two hyphens as a single entity, whereas with it, it sees them as two separate entities. Using this in my file
|
|
|
|
\begin{Verbatim}[]
|
|
git -{}-version
|
|
\end{Verbatim}
|
|
|
|
\noindent{}gave me what I needed: \texttt{git -{}-version}.
|
|
|
|
Sometimes the simplest things are the easiest ones to forget.
|
|
|
|
|
|
\section{What I Learned About Other Things While Creating This Issue}
|
|
|
|
\subsection{I'm Not Ready For This…}
|
|
|
|
…but there is a Hannah Montana version of Linux.
|
|
|
|
Seriously.
|
|
|
|
Read that \textit{again—there is a Hannah Montana version of Linux}.\footnote{Get it while it's hot at \kref{https://hannahmontana.sourceforge.net/}{https://hannahmontana.sourceforge.net/}.}
|
|
|
|
The developer (who has chosen to remain anonymous—I understand this choice) said that they decided to create this in order to attract young users to Linux. As the FAQ\footnote{\kref{https://hannahmontana.sourceforge.net/faq.html}{https://hannahmontana.sourceforge.net/faq.html}} says, ``I created this idea after a lot of reading and work''.
|
|
|
|
The problem with this sort of approach is that television shows geared toward tweens and teens come and go like busboys in a restaurant. Here today, gone five minutes later. I have no doubt that a lot of middle school students in 2024 have no idea who Hannah Montana is. (As it \textit{should} be.)
|
|
|
|
Still, I applaud the work that went into this. If nothing else, it shows that you can pretty much do anything with Linux if you have the time and the energy and also the curiosity. That's definitely a good thing.
|
|
|
|
\subsection{A Git hosting Alternative}
|
|
|
|
When speaking about public Git repos earlier, I mentioned the only two that I knew of: GitHub and Gitlab. But I just recently found about about Codeberg (\kref{https://codeberg.org/}{https://codeberg.org/}), which is run by a non-profit company in Germany. I'm going to sign up for an account and test it out. I'll get back to you on how it works out.
|
|
|
|
%\newpage % Use only to keep the afterword together if we end up with orphans
|
|
\section{Afterword}
|
|
|
|
\begin{multicols}{2}
|
|
\begin{small}
|
|
\noindent{}This issue got done a lot faster than the previous issue, where I got stuck because I got distracted by some other things going on in my life (like my job). As a result, this zine went from feeling like a ``get to do'' kind of thing to a ``have to do'' kind of thing. Like just about everybody else, I have far too many ``have to do'' things in my life already.
|
|
|
|
What got me unstuck was to focus on the \textit{process}, and not the \textit{product}. I let myself have fun with it, in other words. That's something I need to periodically remind myself of, even when the thing in front of me is an actual ``have to do'' like my job. Despite the fact that my job is boring me to death, there are still aspects to it that are quite enjoyable. I try to enjoy them as much as possible, and not let them be overshadowed by the parts I don't really like.
|
|
|
|
In old news, I do occasionally make other zines besides this one, and I have a website for all of them at \kref{https://just13.click/}{https://just13.click/}.
|
|
I used to have a mailing list there, but Mailchimp blew it up. If you want an email notification of when I produce a new zine, feel free to send me an email at \texttt{wolfgangswishlist@gmail.com} and let me know which zines you want to hear about.
|
|
|
|
I also have some ideas for other zines that might cover some of the topics I talk about in here in greater depth. I'm not sure how that's going to evolve just yet, so stay tuned.
|
|
|
|
On page 2 is a link to a list of topics I intend to cover in future issues. If you have ideas for things you'd like me to talk about, send me an email at the above address.
|
|
|
|
I also have a forum for this zine\footnote{\kref{https://forums.kjodle.net/forumdisplay.php?fid=15}{https://forums.kjodle.net/forumdisplay.php?fid=15}} where I'll be posting updates as I go so that you can see how close we are to a new issue. Feel free to join that forum if you like. I'd love to hear from you.
|
|
|
|
Also, I joined Mastodon a while ago, but am just now getting serious about it. You can find me at \kref{https://mastodon.social/@kjodle}{https://mastodon.social/@kjodle} where I will post updates, probably using the hashtag \texttt{\#thecodex}.
|
|
|
|
I've also included some Easter eggs in this issue. If you find them, I'd love to hear about it. As a former teacher, I'd be thrilled to know that you are reading all the way to the bottom of the page.
|
|
|
|
\medskip
|
|
\begin{flushright}
|
|
\noindent{}Thanks,\\—Ken
|
|
\end{flushright}
|
|
|
|
\end{small}
|
|
\end{multicols}
|
|
|
|
|
|
\end{document}
|