kjodle/the-codex
kjodle/the-codex
1
1
Fork 0
Code Issues Pull Requests Projects Releases 2 Wiki Activity

Final (?) round of edits

Browse Source
This commit is contained in:
Kenneth John Odle 2024-08-17 09:44:11 -04:00
parent cbb72d38e7
commit cc9438c486
1 changed files with 17 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
005/codex-005.tex
View File

@ -215,7 +215,7 @@ I was having problems finding an actual teaching job (so many other people decid
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. 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 nor the inclination to learn required for this. 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! 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. 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.
@ -249,11 +249,11 @@ Except that I also used to design websites, so my spreadsheets are easy on the e
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. 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.
\fbox{\texttt{tl;dr:} I'm \textit{really} good with Microsoft Excel. } \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. 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 \textit{don't} want things to get interesting. You \textit{want} this job to be boring. 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. 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.
@ -313,7 +313,7 @@ Technical writing—that is, writing instruction manuals and work instructions a
} % end scalebox } % end scalebox
\end{center} \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 knowing how to respond to others reaching out to us when \textit{they} need help. 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.) 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.)
@ -486,7 +486,7 @@ Git is a command line based technology. Yes, there are GUIs out there for Git, a
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. 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 might end up with less understanding of Git than you would by working on the command line. 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} \section{Local Repositories}
@ -498,7 +498,7 @@ Technically, the \texttt{.git} directory is the actual repository. But most peop
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). 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 our 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). 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.} 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.}
@ -510,7 +510,7 @@ Of course, there's a shortcut to this. You can use
\input{include/checkout} \input{include/checkout}
\noindent{}which creates a branch called ``branchname'' and moves us to it automatically. \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. 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.
@ -552,7 +552,7 @@ origin https://github.com/chrislgarry/Apollo-11 (fetch)
origin https://github.com/chrislgarry/Apollo-11 (push) origin https://github.com/chrislgarry/Apollo-11 (push)
\end{Verbatim} \end{Verbatim}
I named my remote origin ``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: 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} \input{include/remoteremove}
@ -581,7 +581,7 @@ Running \texttt{git branch} again confirms that our branch has been renamed:
\subsection{Pushing Changes to a Remote Repository} \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 remote branch>. Since the remote is named ``ogit'' and the branch is named ``main'', the full command looks like this: 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} \input{include/push}
@ -618,7 +618,7 @@ I mentioned earlier that you could use Git if you're a writer to keep track of c
\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. \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} \end{enumerate}
The advantage to the workflow I'm describing here is that you can do 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. 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: 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:
@ -659,9 +659,9 @@ One of my favorite aspects of Git is that it's fairly intuitive to understand an
hlines = {0.5pt,solid}, hlines = {0.5pt,solid},
vline{1,3} = {0.5pt,solid}, vline{1,3} = {0.5pt,solid},
rows = {5mm, m, rowsep=1.5pt}, rows = {5mm, m, rowsep=1.5pt},
row{1} = {font=\bfseries},
rowhead = 1, rowhead = 1,
cells = {font=\sffamily\fontsize{8pt}{11pt}\selectfont}, cells = {font=\sffamily\fontsize{8pt}{11pt}\selectfont},
row{1} = {font=\bfseries},
} }
Command & Purpose {\& Example, if applicable} \\ Command & Purpose {\& Example, if applicable} \\
\texttt{git init} & {Creates a local git repository \\ \texttt{git init} } \\ \texttt{git init} & {Creates a local git repository \\ \texttt{git init} } \\
@ -731,7 +731,7 @@ which gives us this beautiful outline:
\4 A fourth-level item, all by itself just to annoy your English teacher \4 A fourth-level item, all by itself just to annoy your English teacher
\end{outline} \end{outline}
The indents in your source code are absolutely not necessary, but you can indent with tabs or spaces to help you keep visual track of things. The actual levels are controlled by the number after the backslash. 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} \section{Caveats}
@ -901,9 +901,9 @@ And \textit{that}, my friends, is the easy way to create outlines in \LaTeX{}.
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. 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,\footnote{See \kref{https://www.xm1math.net/texmaker/}{https://www.xm1math.net/texmaker/} for more information.} in fact) 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. 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 text 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.} 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.} \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.}
@ -936,7 +936,7 @@ Notice that the built-in command (the example on the second line) includes a lit
\subsection{Ligatures and \LaTeX{} } \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, it displayed a single hyphen. I was momentarily confused. 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. 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.
@ -946,7 +946,7 @@ The fix for this was to use the \texttt{\{\}} token between the two hyphens. Wit
git -{}-version git -{}-version
\end{Verbatim} \end{Verbatim}
\noindent{}gives me what I needed: \texttt{git -{}-version}. \noindent{}gave me what I needed: \texttt{git -{}-version}.
Sometimes the simplest things are the easiest ones to forget. Sometimes the simplest things are the easiest ones to forget.
@ -976,7 +976,7 @@ When speaking about public Git repos earlier, I mentioned the only two that I kn
\begin{multicols}{2} \begin{multicols}{2}
\begin{small} \begin{small}
\noindent{}This one 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. \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. 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.