Browse Source

zap userland-specific stuff, add intro + a couple entries

This marks the start of the workings: technical notebook project.
Brennen Bearnes 4 years ago
parent
commit
bdbcc6cde6
75 changed files with 519 additions and 6775 deletions
  1. 241
    0
      .exrc
  2. 6
    25
      README.md
  3. 2
    10
      chapters
  4. 0
    1
      diff/README.md
  5. 0
    3
      diff/findprop_output
  6. 0
    6
      diff/genesis_nkj
  7. 0
    5
      diff/genesis_nkj_by_verse
  8. 0
    6
      diff/genesis_nrsv
  9. 0
    5
      diff/genesis_nrsv_by_verse
  10. 0
    328
      diff/index.md
  11. 0
    3
      diff/okpoem_output
  12. 1
    12
      endmatter/index.md
  13. 0
    1
      general_purpose/README.md
  14. 0
    167
      general_purpose/index.md
  15. 0
    3
      general_purpose/simple_markpoem
  16. 0
    42
      get_shell/index.md
  17. 4
    4
      header.html
  18. 118
    2978
      index.html
  19. 15
    11
      introduction/index.md
  20. 6
    2
      links.md
  21. 0
    1
      literary_environment/README.md
  22. 0
    10
      literary_environment/all_authors
  23. 0
    10
      literary_environment/all_authors.tsv
  24. 0
    3
      literary_environment/authors_contemporary_fic
  25. 0
    1
      literary_environment/authors_nat_hist
  26. 0
    7
      literary_environment/authors_sff
  27. 0
    7
      literary_environment/colors
  28. 0
    10
      literary_environment/firstnames
  29. 0
    2
      literary_environment/hello_world
  30. 0
    989
      literary_environment/index.md
  31. 0
    10
      literary_environment/lastnames
  32. 0
    1
      literary_problem/README.md
  33. 0
    150
      literary_problem/index.md
  34. 0
    239
      miscellany/index.md
  35. 0
    30
      miscellany/mostcommon
  36. 0
    1
      programmerthink/README.md
  37. 0
    293
      programmerthink/index.md
  38. 0
    1
      script/README.md
  39. 0
    41
      script/addprop
  40. 0
    13
      script/findprop
  41. 0
    305
      script/index.md
  42. 0
    45
      script/markpoem
  43. 0
    7
      script/okpoems
  44. 0
    14
      shared_space/index.md
  45. 0
    6
      slides/10.md
  46. 0
    3
      slides/11.md
  47. 0
    16
      slides/12.md
  48. 0
    4
      slides/13.md
  49. 0
    7
      slides/14.md
  50. 0
    5
      slides/2.md
  51. 0
    8
      slides/3.md
  52. 0
    12
      slides/4.1.md
  53. 0
    13
      slides/4.md
  54. 0
    5
      slides/5.md
  55. 0
    3
      slides/6.md
  56. 0
    3
      slides/7.md
  57. 0
    5
      slides/8.md
  58. 0
    13
      slides/9.md
  59. 0
    4
      slides/Makefile
  60. BIN
      slides/fake_desktop.png
  61. 0
    91
      slides/footer.html
  62. BIN
      slides/fuckit.jpeg
  63. BIN
      slides/fuckit.jpg
  64. 0
    22
      slides/header.html
  65. 0
    316
      slides/index.html
  66. 0
    100
      slides/render.pl
  67. 0
    8
      slides/scratch
  68. 0
    137
      slides/slides.css
  69. 85
    0
      sysops/index.md
  70. 0
    38
      timebinding_animals/index.md
  71. 41
    0
      vim/index.md
  72. 0
    11
      web/hello_world.html
  73. 0
    140
      web/index.md
  74. 0
    3
      wordcount.sh
  75. 0
    0
      workings.css

+ 241
- 0
.exrc View File

@@ -0,0 +1,241 @@
1
+if &cp | set nocp | endif
2
+let s:cpo_save=&cpo
3
+set cpo&vim
4
+noremap! <M-BS> 
5
+noremap! <expr> <SNR>100_transpose "\<BS>\<Right>".matchstr(getcmdline()[0 : getcmdpos()-2], '.$')
6
+noremap! <expr> <SNR>100_transposition getcmdpos()>strlen(getcmdline())?"\<Left>":getcmdpos()>1?'':"\<Right>"
7
+imap <C-Tab> :tabnext
i
8
+imap <C-S-Tab> :tabprevious
i
9
+imap <F5> :wall
10
+imap <F4> :set invnumber
a
11
+map! <S-Insert> <MiddleMouse>
12
+map <NL> j_
13
+map  k_
14
+nnoremap <silent>  :CtrlP
15
+nmap <silent> ,slr :DBListVar
16
+xmap <silent> ,sa :DBVarRangeAssign
17
+nmap <silent> ,sap :'<,'>DBVarRangeAssign
18
+nmap <silent> ,sal :.,.DBVarRangeAssign
19
+nmap <silent> ,sas :1,$DBVarRangeAssign
20
+nmap ,so <Plug>DBOrientationToggle
21
+nmap ,sh <Plug>DBHistory
22
+xmap <silent> ,stcl :exec "DBListColumn '".DB_getVisualBlock()."'"
23
+nmap ,stcl <Plug>DBListColumn
24
+nmap ,slv <Plug>DBListView
25
+nmap ,slp <Plug>DBListProcedure
26
+nmap ,slt <Plug>DBListTable
27
+xmap <silent> ,slc :exec "DBListColumn '".DB_getVisualBlock()."'"
28
+nmap ,slc <Plug>DBListColumn
29
+nmap ,sbp <Plug>DBPromptForBufferParameters
30
+nmap ,sdpa <Plug>DBDescribeProcedureAskName
31
+xmap <silent> ,sdp :exec "DBDescribeProcedure '".DB_getVisualBlock()."'"
32
+nmap ,sdp <Plug>DBDescribeProcedure
33
+nmap ,sdta <Plug>DBDescribeTableAskName
34
+xmap <silent> ,sdt :exec "DBDescribeTable '".DB_getVisualBlock()."'"
35
+nmap ,sdt <Plug>DBDescribeTable
36
+xmap <silent> ,sT :exec "DBSelectFromTableTopX '".DB_getVisualBlock()."'"
37
+nmap ,sT <Plug>DBSelectFromTopXTable
38
+nmap ,sta <Plug>DBSelectFromTableAskName
39
+nmap ,stw <Plug>DBSelectFromTableWithWhere
40
+xmap <silent> ,st :exec "DBSelectFromTable '".DB_getVisualBlock()."'"
41
+nmap ,st <Plug>DBSelectFromTable
42
+nmap <silent> ,sep :'<,'>DBExecRangeSQL
43
+nmap <silent> ,sel :.,.DBExecRangeSQL
44
+nmap <silent> ,sea :1,$DBExecRangeSQL
45
+nmap ,sq <Plug>DBExecSQL
46
+nmap ,sE <Plug>DBExecSQLUnderTopXCursor
47
+nmap ,se <Plug>DBExecSQLUnderCursor
48
+xmap ,sE <Plug>DBExecVisualTopXSQL
49
+xmap ,se <Plug>DBExecVisualSQL
50
+map ,ds <Plug>DrawItStop
51
+map ,di <Plug>DrawItStart
52
+nmap <silent> ,cv <Plug>VCSVimDiff
53
+nmap <silent> ,cu <Plug>VCSUpdate
54
+nmap <silent> ,cU <Plug>VCSUnlock
55
+nmap <silent> ,cs <Plug>VCSStatus
56
+nmap <silent> ,cr <Plug>VCSReview
57
+nmap <silent> ,cq <Plug>VCSRevert
58
+nmap <silent> ,cn <Plug>VCSAnnotate
59
+nmap <silent> ,cN <Plug>VCSSplitAnnotate
60
+nmap <silent> ,cl <Plug>VCSLog
61
+nmap <silent> ,cL <Plug>VCSLock
62
+nmap <silent> ,ci <Plug>VCSInfo
63
+nmap <silent> ,cg <Plug>VCSGotoOriginal
64
+nmap <silent> ,cG <Plug>VCSClearAndGotoOriginal
65
+nmap <silent> ,cd <Plug>VCSDiff
66
+nmap <silent> ,cD <Plug>VCSDelete
67
+nmap <silent> ,cc <Plug>VCSCommit
68
+nmap <silent> ,ca <Plug>VCSAdd
69
+map ,rwp <Plug>RestoreWinPosn
70
+map ,swp <Plug>SaveWinPosn
71
+map ,tt <Plug>AM_tt
72
+map ,tsq <Plug>AM_tsq
73
+map ,tsp <Plug>AM_tsp
74
+map ,tml <Plug>AM_tml
75
+map ,tab <Plug>AM_tab
76
+map ,m= <Plug>AM_m=
77
+map ,tW@ <Plug>AM_tW@
78
+map ,t@ <Plug>AM_t@
79
+map ,t~ <Plug>AM_t~
80
+map ,t? <Plug>AM_t?
81
+map ,w= <Plug>AM_w=
82
+map ,ts= <Plug>AM_ts=
83
+map ,ts< <Plug>AM_ts<
84
+map ,ts; <Plug>AM_ts;
85
+map ,ts: <Plug>AM_ts:
86
+map ,ts, <Plug>AM_ts,
87
+map ,t= <Plug>AM_t=
88
+map ,t< <Plug>AM_t<
89
+map ,t; <Plug>AM_t;
90
+map ,t: <Plug>AM_t:
91
+map ,t, <Plug>AM_t,
92
+map ,t# <Plug>AM_t#
93
+map ,t| <Plug>AM_t|
94
+map ,T~ <Plug>AM_T~
95
+map ,Tsp <Plug>AM_Tsp
96
+map ,Tab <Plug>AM_Tab
97
+map ,TW@ <Plug>AM_TW@
98
+map ,T@ <Plug>AM_T@
99
+map ,T? <Plug>AM_T?
100
+map ,T= <Plug>AM_T=
101
+map ,T< <Plug>AM_T<
102
+map ,T; <Plug>AM_T;
103
+map ,T: <Plug>AM_T:
104
+map ,Ts, <Plug>AM_Ts,
105
+map ,T, <Plug>AM_T,o
106
+map ,T# <Plug>AM_T#
107
+map ,T| <Plug>AM_T|
108
+map ,Htd <Plug>AM_Htd
109
+map ,anum <Plug>AM_aunum
110
+map ,aenum <Plug>AM_aenum
111
+map ,aunum <Plug>AM_aunum
112
+map ,afnc <Plug>AM_afnc
113
+map ,adef <Plug>AM_adef
114
+map ,adec <Plug>AM_adec
115
+map ,ascom <Plug>AM_ascom
116
+map ,aocom <Plug>AM_aocom
117
+map ,adcom <Plug>AM_adcom
118
+map ,acom <Plug>AM_acom
119
+map ,abox <Plug>AM_abox
120
+map ,a( <Plug>AM_a(
121
+map ,a= <Plug>AM_a=
122
+map ,a< <Plug>AM_a<
123
+map ,a, <Plug>AM_a,
124
+map ,a? <Plug>AM_a?
125
+nmap <silent> ,s :set nolist!
:redr
126
+noremap ,c :SyntasticCheck
127
+nmap ,ok :!addprop % meta-ok-poem
:e
128
+nmap ,f :FufFile
129
+nmap ,tn :tabnew
130
+nmap ,l :Glog
:copen
131
+nmap ,w :wall
132
+nmap ,p :cprev
133
+nmap ,n :cnext
134
+nmap ,q gqip
135
+nmap ,d :call BPB_DecorateFilter()
136
+nmap ,r :call BPB_ExecFilter()
137
+nmap ,td :.-1r !today

138
+noremap! ð <Up>
139
+noremap! î <Down>
140
+noremap! æ <S-Right>
141
+cnoremap ä <S-Right>
142
+inoremap ä dw
143
+noremap! â <S-Left>
144
+map K i
g;
145
+xmap S <Plug>VSurround
146
+vmap [% [%m'gv``
147
+vmap ]% ]%m'gv``
148
+vmap a% [%v]%
149
+nmap cs <Plug>Csurround
150
+nmap ds <Plug>Dsurround
151
+nmap gx <Plug>NetrwBrowseX
152
+xmap gS <Plug>VgSurround
153
+nmap ySS <Plug>YSsurround
154
+nmap ySs <Plug>YSsurround
155
+nmap yss <Plug>Yssurround
156
+nmap yS <Plug>YSurround
157
+nmap ys <Plug>Ysurround
158
+nnoremap <silent> <Plug>NetrwBrowseX :call netrw#NetrwBrowseX(expand("<cWORD>"),0)
159
+noremap <silent> <Plug>DrawItStop :set lz
:call DrawIt#DrawItStop()
:set nolz
160
+noremap <silent> <Plug>DrawItStart :set lz
:call DrawIt#DrawItStart()
:set nolz
161
+nnoremap <silent> <Plug>SurroundRepeat .
162
+nnoremap <silent> <Plug>VCSVimDiff :VCSVimDiff
163
+nnoremap <silent> <Plug>VCSUpdate :VCSUpdate
164
+nnoremap <silent> <Plug>VCSUnlock :VCSUnlock
165
+nnoremap <silent> <Plug>VCSStatus :VCSStatus
166
+nnoremap <silent> <Plug>VCSSplitAnnotate :VCSAnnotate!
167
+nnoremap <silent> <Plug>VCSReview :VCSReview
168
+nnoremap <silent> <Plug>VCSRevert :VCSRevert
169
+nnoremap <silent> <Plug>VCSLog :VCSLog
170
+nnoremap <silent> <Plug>VCSLock :VCSLock
171
+nnoremap <silent> <Plug>VCSInfo :VCSInfo
172
+nnoremap <silent> <Plug>VCSClearAndGotoOriginal :VCSGotoOriginal!
173
+nnoremap <silent> <Plug>VCSGotoOriginal :VCSGotoOriginal
174
+nnoremap <silent> <Plug>VCSDiff :VCSDiff
175
+nnoremap <silent> <Plug>VCSDelete :VCSDelete
176
+nnoremap <silent> <Plug>VCSCommit :VCSCommit
177
+nnoremap <silent> <Plug>VCSAnnotate :VCSAnnotate
178
+nnoremap <silent> <Plug>VCSAdd :VCSAdd
179
+nmap <silent> <Plug>RestoreWinPosn :call RestoreWinPosn()
180
+nmap <silent> <Plug>SaveWinPosn :call SaveWinPosn()
181
+nmap <SNR>50_WE <Plug>AlignMapsWrapperEnd
182
+map <SNR>50_WS <Plug>AlignMapsWrapperStart
183
+map <M-Left> h
184
+map <M-Right> l
185
+map <C-Tab> :tabnext
186
+map <C-S-Tab> :tabprevious
187
+map <F9> :set invhlsearch
188
+map <F5> :wall
189
+map <F4> :set invnumber
190
+map <F3> :NERDTreeFind
191
+map <F2> :NERDTreeToggle
192
+map <S-Insert> <MiddleMouse>
193
+cnoremap  <Home>
194
+inoremap  ^
195
+cnoremap  <Left>
196
+inoremap <expr>  getline('.')=~'^\s*$'&&col('.')>strlen(getline('.'))?"0\<C-D>\<Esc>kJs":"\<Left>"
197
+cnoremap <expr>  getcmdpos()>strlen(getcmdline())?"\<C-D>":"\<Del>"
198
+inoremap <expr>  col('.')>strlen(getline('.'))?"\<C-D>":"\<Del>"
199
+inoremap <expr>  col('.')>strlen(getline('.'))?"\<C-E>":"\<End>"
200
+cnoremap <expr>  getcmdpos()>strlen(getcmdline())?&cedit:"\<Right>"
201
+inoremap <expr>  col('.')>strlen(getline('.'))?"\<C-F>":"\<Right>"
202
+imap S <Plug>ISurround
203
+imap s <Plug>Isurround
204
+imap  <Plug>Isurround
205
+cnoremap  
206
+inoremap  
207
+let &cpo=s:cpo_save
208
+unlet s:cpo_save
209
+set autoindent
210
+set autoread
211
+set background=dark
212
+set backspace=indent,eol,start
213
+set directory=~/.vim/swapfiles,.,/tmp
214
+set expandtab
215
+set fileencodings=ucs-bom,utf-8,default,latin1
216
+set foldopen=block,hor,mark,percent,quickfix,tag,undo
217
+set guioptions=aegimrLt
218
+set helplang=en
219
+set history=3500
220
+set ignorecase
221
+set incsearch
222
+set isfname=@,48-57,/,.,-,_,+,,,#,$,%,~,=,:
223
+set iskeyword=@,48-57,_,192-255,:
224
+set listchars=tab:⇾\ ,trail:·
225
+set mouse=a
226
+set printoptions=paper:letter
227
+set ruler
228
+set runtimepath=~/.vim,~/.vim/bundle/vundle,~/.vim/bundle/nerdtree,~/.vim/bundle/syntastic,~/.vim/bundle/Align,~/.vim/bundle/vcscommand.vim,~/.vim/bundle/vim-fugitive,~/.vim/bundle/vim-surround,~/.vim/bundle/vim-repeat,~/.vim/bundle/vim-colorschemes,~/.vim/bundle/vim-colors-solarized,~/.vim/bundle/vim-tomorrow-theme,~/.vim/bundle/desert-warm-256,~/.vim/bundle/ColorSchemeMenuMaker,~/.vim/bundle/vim-matchit,~/.vim/bundle/L9,~/.vim/bundle/FuzzyFinder,~/.vim/bundle/ack.vim,~/.vim/bundle/ctrlp.vim,~/.vim/bundle/unite.vim,~/.vim/bundle/DrawIt,~/.vim/bundle/vim-golang,~/.vim/bundle/vim-markdown,~/.vim/bundle/mru,~/.vim/bundle/vim-rsi,~/.vim/bundle/dbext.vim,/var/lib/vim/addons,/usr/share/vim/vimfiles,/usr/share/vim/vim74,/usr/share/vim/vimfiles/after,/var/lib/vim/addons/after,~/.vim/after,~/.vim/bundle/vundle/,~/.vim/bundle/vundle/after,~/.vim/bundle/nerdtree/after,~/.vim/bundle/syntastic/after,~/.vim/bundle/Align/after,~/.vim/bundle/vcscommand.vim/after,~/.vim/bundle/vim-fugitive/after,~/.vim/bundle/vim-surround/after,~/.vim/bundle/vim-repeat/after,~/.vim/bundle/vim-colorschemes/after,~/.vim/bundle/vim-colors-solarized/after,~/.vim/bundle/vim-tomorrow-theme/after,~/.vim/bundle/desert-warm-256/after,~/.vim/bundle/ColorSchemeMenuMaker/after,~/.vim/bundle/vim-matchit/after,~/.vim/bundle/L9/after,~/.vim/bundle/FuzzyFinder/after,~/.vim/bundle/ack.vim/after,~/.vim/bundle/ctrlp.vim/after,~/.vim/bundle/unite.vim/after,~/.vim/bundle/DrawIt/after,~/.vim/bundle/vim-golang/after,~/.vim/bundle/vim-markdown/after,~/.vim/bundle/mru/after,~/.vim/bundle/vim-rsi/after,~/.vim/bundle/dbext.vim/after
229
+set shiftwidth=2
230
+set showcmd
231
+set smartcase
232
+set softtabstop=2
233
+set statusline=%<%{fugitive#statusline()}\ %f\ %h%m%r%=%-14.(%l,%c%V%)\ %P
234
+set suffixes=.bak,~,.swp,.o,.info,.aux,.log,.dvi,.bbl,.blg,.brf,.cb,.ind,.idx,.ilg,.inx,.out,.toc
235
+set termencoding=utf-8
236
+set title
237
+set ttimeout
238
+set ttimeoutlen=50
239
+set visualbell
240
+set window=39
241
+" vim: set ft=vim :

+ 6
- 25
README.md View File

@@ -1,37 +1,18 @@
1
-userland:  a book about the command line for humans
2
-===================================================
1
+workings:  a technical notebook
2
+===============================
3 3
 
4 4
 This is the source for some text which can be found here:
5 5
 
6
-[http://p1k3.com/userland-book/](//p1k3.com/userland-book)
6
+[http://squiggle.city/~brennen/workings-book/](//squiggle.city/~brennen/workings-book/)
7 7
 
8 8
 ...which is probably the best place to read it.
9 9
 
10 10
 what
11 11
 ----
12 12
 
13
-From the introduction:
14
-
15
-> Late last year, [a side trip](//p1k3.com/2013/8/4) into text utilities got me
16
-> thinking about how much my writing habits depend on the Linux command line.
17
-> This struck me as a good hook for talking about the tools I use every day
18
-> with an audience of mixed technical background.
19
->
20
-> So now I'm writing a (short, haphazard) book.  This isn't a book about system
21
-> administration, or writing big software systems, or becoming a wizard.  I am
22
-> not a wizard, and I don't subscribe to the idea that wizardry is a requirement
23
-> for using these tools.  In fact I barely know what I'm doing most of the time,
24
-> but I still get some stuff done.
25
->
26
-> My hope herein is to convey something useful to people who use computers every
27
-> day, but for whom the command line environment seems mystifying, obscure, or
28
-> generally uninviting.  I intend to gloss over many complexities in favor of
29
-> demonstrating a rough-and-ready toolset.
30
->
31
-
32
-[p1k3.com/userland-book.git](//p1k3.com/userland-book.git) is the canonical git
33
-repo, but I'm pushing everything to a [GitHub
34
-mirror](https://github.com/brennen/userland-book), and welcome feedback there.
13
+I attempt to keep a notebook about the technical problems I encounter and solve
14
+(or attempt to solve), the research I conduct along the way, and the patterns
15
+or general principles I try to extract from my work.
35 16
 
36 17
 how
37 18
 ---

+ 2
- 10
chapters View File

@@ -1,13 +1,5 @@
1 1
 ./introduction/index.md
2
-./get_shell/index.md
3
-./literary_environment/index.md
4
-./literary_problem/index.md
5
-./programmerthink/index.md
6
-./script/index.md
7
-./general_purpose/index.md
8
-./diff/index.md
9
-./shared_space/index.md
10
-./web/index.md
11
-./miscellany/index.md
2
+./sysops/index.md
3
+./vim/index.md
12 4
 ./endmatter/index.md
13 5
 ./links.md

+ 0
- 1
diff/README.md View File

@@ -1 +0,0 @@
1
-./index.md

+ 0
- 3
diff/findprop_output View File

@@ -1,3 +0,0 @@
1
-/home/brennen/p1k3/archives/2013/2/9
2
-/home/brennen/p1k3/archives/2012/3/17
3
-/home/brennen/p1k3/archives/2012/3/26

+ 0
- 6
diff/genesis_nkj View File

@@ -1,6 +0,0 @@
1
-In the beginning God created the heavens and the earth.  The earth was without
2
-form, and void; and darkness was on the face of the deep.  And the Spirit of
3
-God was hovering over the face of the waters.  Then God said, "Let there be
4
-light"; and there was light.  And God saw the light, that it was good; and God
5
-divided the light from the darkness.  God called the light Day, and the darkness
6
-He called Night.  So the evening and the morning were the first day.

+ 0
- 5
diff/genesis_nkj_by_verse View File

@@ -1,5 +0,0 @@
1
-In the beginning God created the heavens and the earth.
2
-The earth was without form, and void; and darkness was on the face of the deep.  And the Spirit of God was hovering over the face of the waters.
3
-Then God said, "Let there be light"; and there was light.
4
-And God saw the light, that it was good; and God divided the light from the darkness.
5
-God called the light Day, and the darkness He called Night.  So the evening and the morning were the first day.

+ 0
- 6
diff/genesis_nrsv View File

@@ -1,6 +0,0 @@
1
-In the beginning when God created the heavens and the earth, the earth was a
2
-formless void and darkness covered the face of the deep, while a wind from
3
-God swept over the face of the waters.  Then God said, "Let there be light";
4
-and there was light.  And God saw that the light was good; and God separated
5
-the light from the darkness.  God called the light Day, and the darkness he
6
-called Night.  And there was evening and there was morning, the first day.

+ 0
- 5
diff/genesis_nrsv_by_verse View File

@@ -1,5 +0,0 @@
1
-In the beginning when God created the heavens and the earth,
2
-the earth was a formless void and darkness covered the face of the deep, while a wind from God swept over the face of the waters.
3
-Then God said, "Let there be light"; and there was light.
4
-And God saw that the light was good; and God separated the light from the darkness.
5
-God called the light Day, and the darkness he called Night.  And there was evening and there was morning, the first day.

+ 0
- 328
diff/index.md View File

@@ -1,328 +0,0 @@
1
-6. one of these things is not like the others
2
-=============================================
3
-
4
-If you're the sort of person who took a few detours into the history of
5
-religion in college, you might be familiar with some of the ways people used to
6
-do textual comparison.  When pen, paper, and typesetting were what scholars had
7
-to work with, they did some fairly sophisticated things in order to expose the
8
-relationships between multiple pieces of text.
9
-
10
--> <img src="images/throckmorton_small.jpg" height=320 width=470> <-
11
-
12
-Here's a book I got in college:  _Gospel Parallels: A Comparison of the
13
-Synoptic Gospels_, Burton H. Throckmorton, Jr., Ed.  It breaks up three books
14
-from the New Testament by the stories and themes that they contain, and shows
15
-the overlapping sections of each book that contain parallel texts.  You can
16
-work your way through and see what parts only show up in one book, or in two
17
-but not the other, or in all three.  Pages are arranged like so:
18
-
19
-<pre>
20
-                 § JESUS DOES SOME STUFF
21
-     ________________________________________________
22
-    |  MAT            |    MAR             |  LUK    |
23
-    |-----------------+--------------------+---------|
24
-    | Stuff           |                    |         |
25
-    |                 | Stuff              |         |
26
-    |                 | Stuff              | Stuff   |
27
-    |                 | Stuff              |         |
28
-    |                 | Stuff              |         |
29
-    |                 |                    |         |
30
-</pre>
31
-
32
-The way I understand it, a book like this one only scratches the surface of the
33
-field.  Tools like this support a lot of theory about which books copied each
34
-other and how, and what other sources they might have copied that we've since
35
-lost.
36
-
37
-This is some _incredibly_ dry material, even if you kind of dig thinking about
38
-the questions it addresses.  It takes a special temperament to actually sit
39
-poring over fragmentary texts in ancient languages and do these painstaking
40
-comparisons.  Even if you're a writer or editor and work with a lot of
41
-revisions of a text, there's a good chance you rarely do this kind of
42
-comparison on your own work, because that shit is _tedious_.
43
-
44
-diff
45
-----
46
-
47
-It turns out that academics aren't the only people who need tools for comparing
48
-different versions of a text.  Working programmers, in fact, need to do this
49
-_constantly_.  Programmers are also happiest when putting off the _actual_ task
50
-at hand to solve some incidental problem that cropped up along the way, so by
51
-now there are a lot of ways to say "here's how this file is different from this
52
-file", or "here's how this file is different from itself a year ago".
53
-
54
-Let's look at a couple of shell scripts from an earlier chapter:
55
-
56
-<!-- exec -->
57
-
58
-    $ cat ../script/okpoems
59
-    #!/bin/bash
60
-    
61
-    # find all the marker files and get the name of
62
-    # the directory containing each
63
-    find ~/p1k3/archives -name 'meta-ok-poem' | xargs -n1 dirname
64
-    
65
-    exit 0
66
-
67
-<!-- end -->
68
-
69
-<!-- exec -->
70
-
71
-    $ cat ../script/findprop
72
-    #!/bin/bash
73
-    
74
-    if [ ! $1 ]
75
-    then
76
-      echo "usage: findprop <property>"
77
-      exit
78
-    fi
79
-    
80
-    # find all the marker files and get the name of
81
-    # the directory containing each
82
-    find ~/p1k3/archives -name $1 | xargs -n1 dirname
83
-    
84
-    exit 0
85
-
86
-<!-- end -->
87
-
88
-It's pretty obvious these are similar files, but do we know what _exactly_
89
-changed between them at a glance?  It wouldn't be hard to figure out, once.  If
90
-you wanted to be really certain about it, you could print them out, set them
91
-side by side, and go over them with a highlighter.
92
-
93
-Now imagine doing that for a bunch of files, some of them hundreds or thousands
94
-of lines long.  I've actually done that before, colored markers and all, but I
95
-didn't feel smart while I was doing it.  This is a job for software.
96
-
97
-<!-- exec -->
98
-
99
-    $ diff ../script/okpoems ../script/findprop
100
-    2a3,8
101
-    > if [ ! $1 ]
102
-    > then
103
-    >   echo "usage: findprop <property>"
104
-    >   exit
105
-    > fi
106
-    > 
107
-    5c11
108
-    < find ~/p1k3/archives -name 'meta-ok-poem' | xargs -n1 dirname
109
-    ---
110
-    > find ~/p1k3/archives -name $1 | xargs -n1 dirname
111
-
112
-<!-- end -->
113
-
114
-That's not the most human-friendly output, but it's a little simpler than it
115
-seems at first glance.  It's basically just a way of describing the changes
116
-needed to turn `okpoems` into `findprop`.  The string `2a3,8` can be read as
117
-"at line 2, add lines 3 through 8".  Lines with a `>` in front of them are
118
-added.  `5c11` can be read as "line 5 in the original file becomes line 11 in
119
-the new file", and the `<` line is replaced with the `>` line.  If you wanted,
120
-you could take a copy of the original file and apply these instructions by hand
121
-in your text editor, and you'd wind up with the new file.
122
-
123
-A lot of people (me included) prefer what's known as a "unified" diff, because
124
-it's easier to read and offers context for the changed lines.  We can ask for
125
-one of these with `diff -u`:
126
-
127
-<!-- exec -->
128
-
129
-    $ diff -u ../script/okpoems ../script/findprop
130
-    --- ../script/okpoems	2014-04-19 00:08:03.321230818 -0600
131
-    +++ ../script/findprop	2014-04-21 21:51:29.360846449 -0600
132
-    @@ -1,7 +1,13 @@
133
-     #!/bin/bash
134
-     
135
-    +if [ ! $1 ]
136
-    +then
137
-    +  echo "usage: findprop <property>"
138
-    +  exit
139
-    +fi
140
-    +
141
-     # find all the marker files and get the name of
142
-     # the directory containing each
143
-    -find ~/p1k3/archives -name 'meta-ok-poem' | xargs -n1 dirname
144
-    +find ~/p1k3/archives -name $1 | xargs -n1 dirname
145
-     
146
-     exit 0
147
-
148
-<!-- end -->
149
-
150
-That's a little longer, and has some metadata we might not always care about,
151
-but if you look for lines starting with `+` and `-`, it's easy to read as
152
-"added these, took away these".  This diff tells us at a glance that we added
153
-some lines to complain if we didn't get a command line argument, and replaced
154
-`'meta-ok-poem'` in the `find` command with that argument.  Since it shows us
155
-some context, we have a pretty good idea where those lines are in the file
156
-and what they're for.
157
-
158
-What if we don't care exactly _how_ the files differ, but only whether they
159
-do?
160
-
161
-<!-- exec -->
162
-
163
-    $ diff -q ../script/okpoems ../script/findprop
164
-    Files ../script/okpoems and ../script/findprop differ
165
-
166
-<!-- end -->
167
-
168
-I use `diff` a lot in the course of my day job, because I spend a lot of time
169
-needing to know just how two programs differ.  Just as importantly, I often
170
-need to know how (or whether!) the _output_ of programs differs.  As a concrete
171
-example, I want to make sure that `findprop meta-ok-poem` is really a suitable
172
-replacement for `okpoems`.  Since I expect their output to be identical, I can
173
-do this:
174
-
175
-<!-- exec -->
176
-
177
-    $ ../script/okpoems > okpoem_output
178
-    
179
-<!-- end -->
180
-
181
-<!-- exec -->
182
-
183
-    $ ../script/findprop meta-ok-poem > findprop_output
184
-    
185
-<!-- end -->
186
-
187
-<!-- exec -->
188
-
189
-    $ diff -s okpoem_output findprop_output
190
-    Files okpoem_output and findprop_output are identical
191
-
192
-<!-- end -->
193
-
194
-The `-s` just means that `diff` should explicitly tell us if files are the
195
-**s**ame.  Otherwise, it'd output nothing at all, because there aren't any
196
-differences.
197
-
198
-As with many other tools, `diff` doesn't very much care whether it's looking at
199
-shell scripts or a list of filenames or what-have-you.  If you read the man
200
-page, you'll find some features geared towards people writing C-like
201
-programming languages, but its real specialty is just text files with lines
202
-made out of characters, which works well for lots of code, but certainly could
203
-be applied to English prose.
204
-
205
-Since I have a couple of versions ready to hand, let's apply this to a text
206
-with some well-known variations and a bit of a literary legacy.  Here's the
207
-first day of the Genesis creation narrative in a couple of English
208
-translations:
209
-
210
-<!-- exec -->
211
-
212
-    $ cat genesis_nkj
213
-    In the beginning God created the heavens and the earth.  The earth was without
214
-    form, and void; and darkness was on the face of the deep.  And the Spirit of
215
-    God was hovering over the face of the waters.  Then God said, "Let there be
216
-    light"; and there was light.  And God saw the light, that it was good; and God
217
-    divided the light from the darkness.  God called the light Day, and the darkness
218
-    He called Night.  So the evening and the morning were the first day.
219
-
220
-<!-- end -->
221
-
222
-<!-- exec -->
223
-
224
-    $ cat genesis_nrsv
225
-    In the beginning when God created the heavens and the earth, the earth was a
226
-    formless void and darkness covered the face of the deep, while a wind from
227
-    God swept over the face of the waters.  Then God said, "Let there be light";
228
-    and there was light.  And God saw that the light was good; and God separated
229
-    the light from the darkness.  God called the light Day, and the darkness he
230
-    called Night.  And there was evening and there was morning, the first day.
231
-
232
-<!-- end -->
233
-
234
-What happens if we diff them?
235
-
236
-<!-- exec -->
237
-
238
-    $ diff -u genesis_nkj genesis_nrsv
239
-    --- genesis_nkj	2014-05-11 16:28:29.692508461 -0600
240
-    +++ genesis_nrsv	2014-05-11 16:28:29.744508459 -0600
241
-    @@ -1,6 +1,6 @@
242
-    -In the beginning God created the heavens and the earth.  The earth was without
243
-    -form, and void; and darkness was on the face of the deep.  And the Spirit of
244
-    -God was hovering over the face of the waters.  Then God said, "Let there be
245
-    -light"; and there was light.  And God saw the light, that it was good; and God
246
-    -divided the light from the darkness.  God called the light Day, and the darkness
247
-    -He called Night.  So the evening and the morning were the first day.
248
-    +In the beginning when God created the heavens and the earth, the earth was a
249
-    +formless void and darkness covered the face of the deep, while a wind from
250
-    +God swept over the face of the waters.  Then God said, "Let there be light";
251
-    +and there was light.  And God saw that the light was good; and God separated
252
-    +the light from the darkness.  God called the light Day, and the darkness he
253
-    +called Night.  And there was evening and there was morning, the first day.
254
-
255
-<!-- end -->
256
-
257
-Kind of useless, right?  If a given line differs by so much as a character,
258
-it's not the same line.  This highlights the limitations of `diff` for comparing
259
-things that
260
-
261
-- aren't logically grouped by line
262
-- aren't easily thought of as versions of the same text with some lines changed
263
-
264
-We could edit the files into a more logically defined structure, like
265
-one-line-per-verse, and try again:
266
-
267
-<!-- exec -->
268
-
269
-    $ diff -u genesis_nkj_by_verse genesis_nrsv_by_verse
270
-    --- genesis_nkj_by_verse	2014-05-11 16:51:14.312457198 -0600
271
-    +++ genesis_nrsv_by_verse	2014-05-11 16:53:02.484453134 -0600
272
-    @@ -1,5 +1,5 @@
273
-    -In the beginning God created the heavens and the earth.
274
-    -The earth was without form, and void; and darkness was on the face of the deep.  And the Spirit of God was hovering over the face of the waters.
275
-    +In the beginning when God created the heavens and the earth,
276
-    +the earth was a formless void and darkness covered the face of the deep, while a wind from God swept over the face of the waters.
277
-     Then God said, "Let there be light"; and there was light.
278
-    -And God saw the light, that it was good; and God divided the light from the darkness.
279
-    -God called the light Day, and the darkness He called Night.  So the evening and the morning were the first day.
280
-    +And God saw that the light was good; and God separated the light from the darkness.
281
-    +God called the light Day, and the darkness he called Night.  And there was evening and there was morning, the first day.
282
-
283
-<!-- end -->
284
-
285
-It might be a little more descriptive, but editing all that text just for a
286
-quick comparison felt suspiciously like work, and anyway the output still
287
-doesn't seem very useful.
288
-
289
-wdiff
290
------
291
-
292
-For cases like this, I'm fond of a tool called `wdiff`:
293
-
294
-<!-- exec -->
295
-
296
-    $ wdiff genesis_nkj genesis_nrsv
297
-    In the beginning {+when+} God created the heavens and the [-earth.  The-] {+earth, the+} earth was [-without
298
-    form, and void;-] {+a
299
-    formless void+} and darkness [-was on-] {+covered+} the face of the [-deep.  And the Spirit of-] {+deep, while a wind from+}
300
-    God [-was hovering-] {+swept+} over the face of the waters.  Then God said, "Let there be light";
301
-    and there was light.  And God saw [-the light,-] that [-it-] {+the light+} was good; and God
302
-    [-divided-] {+separated+}
303
-    the light from the darkness.  God called the light Day, and the darkness
304
-    [-He-] {+he+}
305
-    called Night.  [-So the-]  {+And there was+} evening and [-the morning were-] {+there was morning,+} the first day.
306
-
307
-<!-- end -->
308
-
309
-Deleted words are surrounded by `[- -]` and inserted ones by `{+ +}`.  You can
310
-even ask it to spit out HTML tags for insertion and deletion...
311
-
312
-    $ wdiff -w '<del>' -x '</del>' -y '<ins>' -z '</ins>' genesis_nkj genesis_nrsv
313
-
314
-...and come up with something your browser will render like this:
315
-
316
-<blockquote>
317
-<p>In the beginning <ins>when</ins> God created the heavens and the <del>earth.  The</del> <ins>earth, the</ins> earth was <del>without
318
-form, and void;</del> <ins>a
319
-formless void</ins> and darkness <del>was on</del> <ins>covered</ins> the face of the <del>deep.  And the Spirit of</del> <ins>deep, while a wind from</ins>
320
-God <del>was hovering</del> <ins>swept</ins> over the face of the waters.  Then God said, "Let there be light";
321
-and there was light.  And God saw <del>the light,</del> that <del>it</del> <ins>the light</ins> was good; and God
322
-<del>divided</del> <ins>separated</ins>
323
-the light from the darkness.  God called the light Day, and the darkness
324
-<del>He</del> <ins>he</ins>
325
-called Night.  <del>So the</del>  <ins>And there was</ins> evening and <del>the morning were</del> <ins>there was morning,</ins> the first day.</p>
326
-</blockquote>
327
-
328
-Burton H. Throckmorton, Jr. this ain't.  Still, it has its uses.

+ 0
- 3
diff/okpoem_output View File

@@ -1,3 +0,0 @@
1
-/home/brennen/p1k3/archives/2013/2/9
2
-/home/brennen/p1k3/archives/2012/3/17
3
-/home/brennen/p1k3/archives/2012/3/26

+ 1
- 12
endmatter/index.md View File

@@ -8,18 +8,7 @@ further reading
8 8
 - [AT&T Archives: The UNIX Operating System](https://www.youtube.com/watch?v=tc4ROCJYbm0) (YouTube)
9 9
 - [I had a couple drinks and woke up with 1,000 nerds](https://medium.com/message/tilde-club-i-had-a-couple-drinks-and-woke-up-with-1-000-nerds-a8904f0a2ebf) - Paul Ford
10 10
 
11
-code
12
-----
13
-
14
-<a href="https://p1k3.com/userland-book.git">p1k3.com/userland-book.git</a>
15
-should be considered the canonical git repository, but I'm pushing everything
16
-to a <a href="https://github.com/brennen/userland-book">GitHub mirror</a>, and
17
-welcome feedback there.
18
-
19 11
 copying
20 12
 -------
21 13
 
22
-I may eventually dedicate this thing to the public domain, but for the time
23
-being please feel free to use it under the terms of Creative Commons BY-SA
24
-(Attribution / Share-Alike), whatever the latest version is.  I promise I will
25
-not license it under more restrictive terms than that.
14
+[CC BY-SA 4.0][cc-by-sa]

+ 0
- 1
general_purpose/README.md View File

@@ -1 +0,0 @@
1
-index.md

+ 0
- 167
general_purpose/index.md View File

@@ -1,167 +0,0 @@
1
-5. general purpose programmering
2
-================================
3
-
4
-I didn't set out to write a book about programming, _as such_, but because
5
-programming and the command line are so inextricably linked, this text
6
-draws near the subject almost of its own accord.
7
-
8
-If you're not terribly interested in programming, this chapter can easily
9
-enough be skipped.  It's more in the way of philosophical rambling than
10
-concrete instruction, and will be of most use to those with an existing
11
-background in writing code.
12
-
13
--> ✢ <-
14
-
15
-If you've used computers for more than a few years, you're probably viscerally
16
-aware that most software is fragile and most systems decay.  In the time since
17
-I took my first tentative steps into the little world of a computer (a friend's
18
-dad's unidentifiable gaming machine, my own father's blue monochrome Zenith
19
-laptop, the Apple II) the churn has been overwhelming.  By now I've learned my
20
-way around vastly more software --- operating systems, programming languages and
21
-development environments, games, editors, chat clients, mail systems --- than I
22
-presently could use if I wanted to.  Most of it has gone the way of some
23
-ancient civilization, surviving (if at all) only in faint, half-understood
24
-cultural echoes and occasional museum-piece displays.  Every user of technology
25
-becomes, in time, a refugee from an irretrievably recent past.
26
-
27
-And yet, despite all this, the shell endures.  Most of the ideas in this book
28
-are older than I am.  Most of them could have been applied in 1994 or
29
-thereabouts, when I first logged on to multiuser systems running AT&T Unix.
30
-Since the early 1990s, systems built on a fundamental substrate of Unix-like
31
-behavior and abstractions have proliferated wildly, becoming foundational at
32
-once to the modern web, the ecosystem of free and open software, and the
33
-technological dominance ca. 2014 of companies like Apple, Google, and Facebook.
34
-
35
-Why is this, exactly?
36
-
37
--> ✣ <-
38
-
39
-As I've said (and hopefully shown), the commands you write in your shell
40
-are essentially little programs.  Like other programs, they can be stored
41
-for later use and recombined with other commands, creating new uses for
42
-your ideas.
43
-
44
-It would be hard to say that there's any _one_ reason command line environments
45
-remain so vital after decades of evolution and hard-won refinement in computer
46
-interfaces, but it seems like this combinatory nature is somewhere near the
47
-heart of it.  The command line often lacks the polish of other interfaces we
48
-depend on, but in exchange it offers a richness and freedom of expression
49
-rarely seen elsewhere, and invites its users to build upon its basic
50
-facilities.
51
-
52
-What is it that makes last chapter's `addprop` preferable to the more specific
53
-`markpoem`?  Let's look at an alternative implementation of `markpoem`:
54
-
55
-<!-- exec -->
56
-
57
-    $ cat simple_markpoem
58
-    #!/bin/bash
59
-    
60
-    addprop $1 meta-ok-poem
61
-
62
-<!-- end -->
63
-
64
-Is this script trivial?  Absolutely.  It's so trivial that it barely seems to
65
-exist, because I already wrote `addprop` to do all the heavy lifting and play
66
-well with others, freeing us to imagine new uses for its central idea without
67
-worrying about the implementation details.
68
-
69
-Unlike `markpoem`, `addprop` doesn't know anything about poetry.  All it knows
70
-about, in fact, is putting a file (or three) in a particular place.  And this
71
-is in keeping with a basic insight of Unix:  Pieces of software that do one
72
-very simple thing generalize well.  Good command line tools are like a hex
73
-wrench, a hammer, a utility knife:  They embody knowledge of turning, of
74
-striking, of cutting --- and with this kind of knowledge at hand, the user can
75
-change the world even though no individual tool is made with complete knowledge
76
-of the world as a whole.  There's a lot of power in the accumulation of small
77
-competencies.
78
-
79
-Of course, if your code is only good at one thing, to be of any use, it has to
80
-talk to code that's good at other things.  There's another basic insight in the
81
-Unix tradition:  Tools should be composable.  All those little programs have to
82
-share some assumptions, have to speak some kind of trade language, in order to
83
-combine usefully.  Which is how we've arrived at standard IO, pipelines,
84
-filesystems, and text as as a lowest-common-denominator medium of exchange.  If
85
-you think about most of these things, they have some very rough edges, but they
86
-give otherwise simple tools ways to communicate without becoming
87
-super-complicated along the way.
88
-
89
--> ✤ <-
90
-
91
-What is the command line?
92
-
93
-The command line is an environment of tool use.
94
-
95
-So are kitchens, workshops, libraries, and programming languages.
96
-
97
--> ✥ <-
98
-
99
-Here's a confession:  I don't like writing shell scripts very much, and I
100
-can't blame anyone else for feeling the same way.
101
-
102
-That doesn't mean you shouldn't _know_ about them, or that you shouldn't
103
-_write_ them.  I write little ones all the time, and the ability to puzzle
104
-through other people's scripts comes in handy.  Oftentimes, the best, most
105
-tasteful way to automate something is to build a script out of the commonly
106
-available commands.  The standard tools are already there on millions of
107
-machines.  Many of them have been pretty well understood for a generation, and
108
-most will probably be around for a generation or three to come.  They do neat
109
-stuff.  Scripts let you build on ideas you've already worked out, and give
110
-repeatable operations a memorable, user-friendly name.  They encourage reuse of
111
-existing programs, and help express your ideas to people who'll come after you.
112
-
113
-One of the reliable markers of powerful software is that it can be scripted: It
114
-extends to its users some of the same power that its authors used in creating
115
-it.  Scriptable software is to some extent _living_ software.  It's a book that
116
-you, the reader, get to help write.
117
-
118
-In all these ways, shell scripts are wonderful, a little bit magical, and
119
-quietly indispensable to the machinery of modern civilization.
120
-
121
-Unfortunately, in all the ways that a shell like Bash is weird, finicky, and
122
-covered in 40 years of incidental cruft, long-form Bash scripts are even worse.
123
-Bash is a useful glue language, particularly if you're already comfortable
124
-wiring commands together.  Syntactic and conceptual innovations like pipes are
125
-beautiful and necessary.  What Bash is _not_, despite its power, is a very good
126
-general purpose programming language.  It's just not especially good at things
127
-like math, or complex data structures, or not looking like a punctuation-heavy
128
-variety of alphabet soup.
129
-
130
-It turns out that there's a threshold of complexity beyond which life becomes
131
-easier if you switch from shell scripting to a more robust language.  Just
132
-where this threshold is located varies a lot between users and problems, but I
133
-often think about switching languages before a script gets bigger than I can
134
-view on my screen all at once.  `addprop` is a good example:
135
-
136
-<!-- exec -->
137
-
138
-    $ wc -l ../script/addprop
139
-    41 ../script/addprop
140
-
141
-<!-- end -->
142
-
143
-41 lines is a touch over what fits on one screen in the editor I usually use.
144
-If I were going to add much in the way of features, I'd think pretty hard about
145
-porting it to another language first.
146
-
147
-What's cool is that if you know a language like C, Python, Perl, Ruby, PHP, or
148
-JavaScript, your code can participate in the shell environment as a first class
149
-citizen simply by respecting the conventions of standard IO, files, and command
150
-line arguments.  Often, in order to create a useful utility, it's only
151
-necessary to deal with `STDIN`, or operate on a particular sort of file, and
152
-most languages offer simple conventions for doing these things.
153
-
154
--> * <-
155
-
156
-I think the shell can be taught and understood as a humane environment, despite
157
-all of its ugliness and complication, because it offers the materials of its
158
-own construction to its users, whatever their concerns.  The writer, the
159
-philosopher, the scientist, the programmer:  Files and text and pipes know
160
-little enough about these things, but in their very indifference to the
161
-specifics of any one complex purpose, they're adaptable to the basic needs of
162
-many.  Simple utilities which enact simple kinds of knowledge survive and
163
-recombine because there is a wisdom to be found in small things.
164
-
165
-Files and text know nothing about poetry, nothing in particular of the human
166
-soul.  Neither do pen and ink, printing presses or codex books, but somehow we
167
-got Shakespeare and Montaigne.

+ 0
- 3
general_purpose/simple_markpoem View File

@@ -1,3 +0,0 @@
1
-#!/bin/bash
2
-
3
-addprop $1 meta-ok-poem

+ 0
- 42
get_shell/index.md View File

@@ -1,42 +0,0 @@
1
-0. get you a shell
2
-==================
3
-
4
-You don't have to have a shell at hand to get something out of this book.
5
-Still, as with most practical subjects, you'll learn more if you try things out
6
-as you go.  You shouldn't feel guilty about skipping this section.  It will
7
-always be here later if you need it.
8
-
9
-Not so long ago, it was common for schools and ISPs to hand out shell accounts
10
-on big shared systems.  People learned the command line as a side effect of
11
-reading e-mail.
12
-
13
-That doesn't happen as often now, but in the meanwhile computers have become
14
-relatively cheap and free software is abundant.  If you're reading this on the
15
-web, you can probably get access to a shell.  Some options follow.
16
-
17
-ask for an account on squiggle.city
18
------------------------------------
19
-
20
-[squiggle.city][squiggle] is a server I'm running explicitly for teaching
21
-purposes, modeled on [tilde.club][tildeclub].
22
-
23
-You can get ahold of me by mailing bbearnes at Google's giant e-mail service,
24
-or on twitter [as @brennen][atbrennen].  Just let me know you'd like an account
25
-and I'll walk you through the basics.
26
-
27
-Limited time offer, contains no implied warranty of fitness or merchantability,
28
-accounts free while supplies last!
29
-
30
-use a raspberry pi or beaglebone
31
---------------------------------
32
-
33
-Do you have a single-board computer laying around?  Perfect.  If you already
34
-run the standard Raspbian, Debian on a BeagleBone, or a similar-enough Linux,
35
-you don't need much else.  I wrote most of this text on a Raspberry Pi, and the
36
-example commands should all work there.
37
-
38
-use a virtual machine
39
----------------------
40
-
41
-_To come:  Instructions for running Linux in a virtual machine on your own
42
-computer or using a cloud provider like Linode, DigitalOcean, or Amazon._

+ 4
- 4
header.html View File

@@ -2,12 +2,12 @@
2 2
 <html lang=en>
3 3
 <head>
4 4
   <meta charset="utf-8">
5
-  <title>userland: a book about the command line for humans</title>
6
-  <link rel=stylesheet href="userland.css" />
7
-  <link rel="alternate" type="application/atom+xml" title="changes" href="//p1k3.com/userland-book/feed.xml" />
5
+  <title>workings: a technical notebook</title>
6
+  <link rel=stylesheet href="workings.css" />
7
+  <link rel="alternate" type="application/atom+xml" title="changes" href="//squiggle.city/~brennen/workings-book/feed.xml" />
8 8
   <script src="js/jquery.js" type="text/javascript"></script>
9 9
 </head>
10 10
 
11 11
 <body>
12 12
 
13
-<h1 class=bigtitle>userland</h1>
13
+<h1 class=bigtitle>workings</h1>

+ 118
- 2978
index.html
File diff suppressed because it is too large
View File


+ 15
- 11
introduction/index.md View File

@@ -1,20 +1,23 @@
1
-a book about the command line for humans
2
-========================================
1
+a technical notebook
2
+====================
3 3
 
4
-In the fall of 2013, [thinking about](//p1k3.com/2013/8/4) text utilities got
5
-me thinking in turn about how my writing habits depend on the Linux command
6
-line.  This seems like a good hook for explaining some tools I use every day,
7
-so now I'm writing a short, haphazard book.
4
+It is late in 2014, and I have just quit my job at SparkFun after 7 years of
5
+PHP, SQL, Linux, git, IRC, and heavy substance abuse.
8 6
 
9
-This isn't a book about system administration, writing complex software, or
10
-becoming a wizard.  I am not a wizard, and I don't subscribe to the idea that
11
-wizardry required to use these tools.  In fact, I barely know what I'm doing
12
-most of the time.  I still get some stuff done.
7
+I have already written [a short book][userland-book] on the basics of the
8
+command line.  I continue to work on that project; this book is intended as
9
+something else altogether.  It is meant to be a long-form technical logbook or
10
+journal, capturing the outlines of problems and their solutions as I encounter
11
+them.  It may often be dry, verbose, sketchy, embarrassing, and downright wrong.
13 12
 
14
-This is a work in progress.  It probably gets some stuff wrong.
13
+I'm writing this because I want a compendium of the stuff I discover, and I
14
+hope that writing documentation will force me to do cleaner, more reproducible
15
+work.  If it gradually becomes useful to anyone else, so much the better.
15 16
 
17
+Former students of Laurel-Concord High School will likely remember the logbooks
18
+that inspired this one.  Go Bears.
16 19
 
20
+-- bpb / [p1k3](https://p1k3.com) / [@brennen](https://ello.com/brennen)
17 21
 
18 22
 <div class=details>
19 23
   <h2 class=clicker>contents</h2>

+ 6
- 2
links.md View File

@@ -1,8 +1,12 @@
1
-[p1k3]: //p1k3.com/
2
-[atbrennen]: https://twitter.com/brennen
1
+
2
+[cc-by-sa]: http://creativecommons.org/licenses/by-sa/4.0/
3
+[p1k3]: https://p1k3.com/
4
+[atbrennen]: https://ello.co/brennen
3 5
 [kwic]: http://en.wikipedia.org/wiki/Key_Word_in_Context
4 6
 [www]: http://info.cern.ch/hypertext/WWW/TheProject.html
5 7
 [virtualbox]: https://www.virtualbox.org/wiki/Downloads
6 8
 [userland-debian-image]: https://getyouashell.com/
9
+[userland-book]: https://p1k3.com/userland-book/
7 10
 [squiggle]: http://squiggle.city/
11
+[squiggle.city]: http://squiggle.city/
8 12
 [tildeclub]: http://tilde.club/

+ 0
- 1
literary_environment/README.md View File

@@ -1 +0,0 @@
1
-index.md

+ 0
- 10
literary_environment/all_authors View File

@@ -1,10 +0,0 @@
1
-Eden Robinson
2
-Gwendolyn L. Waring
3
-James Tiptree, Jr.
4
-John Brunner
5
-John Ronald Reuel Tolkien
6
-Jo Walton
7
-Miriam Toews
8
-Pat Cadigan
9
-Ursula K. Le Guin
10
-Vanessa Veselka

+ 0
- 10
literary_environment/all_authors.tsv View File

@@ -1,10 +0,0 @@
1
-Robinson	Eden
2
-Waring	Gwendolyn	L.
3
-Tiptree	James		Jr.
4
-Brunner	John
5
-Tolkien	John	Ronald Reuel
6
-Walton	Jo
7
-Toews	Miriam
8
-Cadigan	Pat
9
-Le Guin	Ursula	K.
10
-Veselka	Vanessa

+ 0
- 3
literary_environment/authors_contemporary_fic View File

@@ -1,3 +0,0 @@
1
-Eden Robinson
2
-Vanessa Veselka
3
-Miriam Toews

+ 0
- 1
literary_environment/authors_nat_hist View File

@@ -1 +0,0 @@
1
-Gwendolyn L. Waring

+ 0
- 7
literary_environment/authors_sff View File

@@ -1,7 +0,0 @@
1
-Ursula K. Le Guin
2
-Jo Walton
3
-Pat Cadigan
4
-John Ronald Reuel Tolkien
5
-Vanessa Veselka
6
-James Tiptree, Jr.
7
-John Brunner

+ 0
- 7
literary_environment/colors View File

@@ -1,7 +0,0 @@
1
-RED
2
-blue
3
-red
4
-BLUE
5
-Green
6
-green
7
-GREEN

+ 0
- 10
literary_environment/firstnames View File

@@ -1,10 +0,0 @@
1
-Eden
2
-Gwendolyn
3
-James
4
-John
5
-John
6
-Jo
7
-Miriam
8
-Pat
9
-Ursula
10
-Vanessa

+ 0
- 2
literary_environment/hello_world View File

@@ -1,2 +0,0 @@
1
-hello
2
-world

+ 0
- 989
literary_environment/index.md View File

@@ -1,989 +0,0 @@
1
-1. the command line as literary environment
2
-===========================================
3
-
4
-There're a lot of ways to structure an introduction to the command line.  I'm
5
-going to start with writing as a point of departure because, aside from web
6
-development, it's what I use a computer for most.  I want to shine a light on
7
-the humane potential of ideas that are usually understood as nerd trivia.
8
-Computers have utterly transformed the practice of writing within the space of
9
-my lifetime, but it seems to me that writers as a class miss out on many of the
10
-software tools and patterns taken as a given in more "technical" fields.
11
-
12
-Writing, particularly writing of any real scope or complexity, is very much a
13
-technical task.  It makes demands, both physical and psychological, of its
14
-practitioners.  As with woodworkers, graphic artists, and farmers, writers
15
-exhibit strong preferences in their tools, materials, and environment, and they
16
-do so because they're engaged in a physically and cognitively challenging task.
17
-
18
-My thesis is that the modern Linux command line is a pretty good environment
19
-for working with English prose and prosody, and that maybe this will illuminate
20
-the ways it could be useful in your own work with a computer, whatever that
21
-work happens to be.
22
-
23
-terms and definitions
24
----------------------
25
-
26
-What software are we actually talking about when we say "the command line"?
27
-
28
-For the purposes of this discussion, we're talking about an environment built
29
-on a very old paradigm called Unix.
30
-
31
--> <img src="images/jp_unix.jpg" height=320 width=470> <-
32
-
33
-...except what classical Unix really looks like is this:
34
-
35
--> <img src="images/blinking.gif" width=470> <-
36
-
37
-The Unix-like environment we're going to use isn't very classical, really.
38
-It's an operating system kernel called Linux, combined with a bunch of things
39
-written by other people (people in the GNU and Debian projects, and many
40
-others).  Purists will tell you that this isn't properly Unix at all.  In
41
-strict historical terms they're right, or at least a certain kind of right, but
42
-for the purposes of my cultural agenda I'm going to ignore them right now.
43
-
44
--> <img src="images/debian.png"> <-
45
-
46
-This is what's called a shell.  There are many different shells, but they
47
-pretty much all operate on the same idea:  You navigate a filesystem and run
48
-programs by typing commands.  Commands can be combined in various ways to make
49
-programs of their own, and in fact the way you use the computer is often just
50
-to write little programs that invoke other programs, turtles-all-the-way-down
51
-style.
52
-
53
-The standard shell these days is something called Bash, so we'll use Bash.
54
-It's what you'll most often see in the wild.  Like most shells, Bash is ugly
55
-and stupid in more ways than it is possible to easily summarize.  It's also an
56
-incredibly powerful and expressive piece of software.
57
-
58
-twisty little passages
59
-----------------------
60
-
61
-Have you ever played a text-based adventure game or MUD, of the kind that
62
-describes a setting and takes commands for movement and so on?  Readers of a
63
-certain age and temperament might recognize the opening of Crowther & Woods'
64
-_Adventure_, the great-granddaddy of text adventure games:
65
-
66
-    YOU ARE STANDING AT THE END OF A ROAD BEFORE A SMALL BRICK BUILDING.
67
-    AROUND YOU IS A FOREST.  A SMALL STREAM FLOWS OUT OF THE BUILDING ANd
68
-    DOWN A GULLY.
69
-
70
-    > GO EAST
71
-
72
-    YOU ARE INSIDE A BUILDING, A WELL HOUSE FOR A LARGE SPRING.
73
-
74
-    THERE ARE SOME KEYS ON THE GROUND HERE.
75
-
76
-    THERE IS A SHINY BRASS LAMP NEARBY.
77
-
78
-    THERE IS FOOD HERE.
79
-
80
-    THERE IS A BOTTLE OF WATER HERE.
81
-
82
-You can think of the shell as a kind of environment you inhabit, in much the
83
-way your character inhabits an adventure game.  The difference is that instead
84
-of navigating around virtual rooms and hallways with commands like `LOOK` and
85
-`EAST`, you navigate between directories by typing commands like `ls` and `cd
86
-notes`:
87
-
88
-    $ ls
89
-    code  Downloads  notes  p1k3  photos  scraps  userland-book
90
-    $ cd notes
91
-    $ ls
92
-    notes.txt  sparkfun  TODO.txt
93
-
94
-`ls` lists files.  Some files are directories, which means they can contain
95
-other files, and you can step inside of them by typing `cd` (for **c**hange
96
-**d**irectory).
97
-
98
-In the Macintosh and Windows world, directories have been called
99
-"folders" for a long time now.  This isn't the _worst_ metaphor for what's
100
-going on, and it's so pervasive by now that it's not worth fighting about.
101
-It's also not exactly a _great_ metaphor, since computer filesystems aren't
102
-built very much like the filing cabinets of yore.  A directory acts a lot like
103
-a container of some sort, but it's an infinitely expandable one which may
104
-contain nested sub-spaces much larger than itself.  Directories are frequently
105
-like the TARDIS: Bigger on the inside.
106
-
107
-cat
108
----
109
-
110
-When you're in the shell, you have many tools at your disposal - programs that
111
-can be used on many different files, or chained together with other programs.
112
-They tend to have weird, cryptic names, but a lot of them do very simple
113
-things.  Tasks that might be a menu item in a big program like Word, like
114
-counting the number of words in a document or finding a particular phrase, are
115
-often programs unto themselves.  We'll start with something even more basic
116
-than that.
117
-
118
-Suppose you have some files, and you're curious what's in them.  For example,
119
-suppose you've got a list of authors you're planning to reference, and you just
120
-want to check its contents real quick-like.  This is where our friend `cat`
121
-comes in:
122
-
123
-<!-- exec -->
124
-
125
-    $ cat authors_sff
126
-    Ursula K. Le Guin
127
-    Jo Walton
128
-    Pat Cadigan
129
-    John Ronald Reuel Tolkien
130
-    Vanessa Veselka
131
-    James Tiptree, Jr.
132
-    John Brunner
133
-
134
-<!-- end -->
135
-
136
-"Why," you might be asking, "is the command to dump out the contents of a file
137
-to a screen called `cat`?  What do felines have to do with anything?"
138
-
139
-It turns out that `cat` is actually short for "concatenate", which is a long
140
-word basically meaning "stick things together".  In programming, we usually
141
-refer to sticking two bits of text together as "string concatenation", probably
142
-because programmers like to feel like they're being very precise about very
143
-simple actions.
144
-
145
-Suppose you wanted to see the contents of a _set_ of author lists:
146
-
147
-<!-- exec -->
148
-
149
-    $ cat authors_sff authors_contemporary_fic authors_nat_hist
150
-    Ursula K. Le Guin
151
-    Jo Walton
152
-    Pat Cadigan
153
-    John Ronald Reuel Tolkien
154
-    Vanessa Veselka
155
-    James Tiptree, Jr.
156
-    John Brunner
157
-    Eden Robinson
158
-    Vanessa Veselka
159
-    Miriam Toews
160
-    Gwendolyn L. Waring
161
-
162
-<!-- end -->
163
-
164
-wildcards
165
----------
166
-
167
-We're working with three filenames: `authors_sff`, `authors_contemporary_fic`,
168
-and `authors_nat_hist`.  That's an awful lot of typing every time we want to do
169
-something to all three files.  Fortunately, our shell offers a shorthand for
170
-"all the files that start with `authors_`":
171
-
172
-<!-- exec -->
173
-
174
-    $ cat authors_*
175
-    Eden Robinson
176
-    Vanessa Veselka
177
-    Miriam Toews
178
-    Gwendolyn L. Waring
179
-    Ursula K. Le Guin
180
-    Jo Walton
181
-    Pat Cadigan
182
-    John Ronald Reuel Tolkien
183
-    Vanessa Veselka
184
-    James Tiptree, Jr.
185
-    John Brunner
186
-
187
-<!-- end -->
188
-
189
-In Bash-land, `*` basically means "anything", and is known in the vernacular,
190
-somewhat poetically, as a "wildcard".  You should always be careful with
191
-wildcards, especially if you're doing anything destructive.  They can and will
192
-surprise the unwary.  Still, once you're used to the idea, they will save you a
193
-lot of RSI.
194
-
195
-sort
196
-----
197
-
198
-There's a problem here.  Our author list is out of order, and thus confusing to
199
-reference.  Fortunately, since one of the most basic things you can do to a
200
-list is to sort it, someone else has already solved this problem for us.
201
-Here's a command that will give us some organization:
202
-
203
-<!-- exec -->
204
-
205
-    $ sort authors_*
206
-    Eden Robinson
207
-    Gwendolyn L. Waring
208
-    James Tiptree, Jr.
209
-    John Brunner
210
-    John Ronald Reuel Tolkien
211
-    Jo Walton
212
-    Miriam Toews
213
-    Pat Cadigan
214
-    Ursula K. Le Guin
215
-    Vanessa Veselka
216
-    Vanessa Veselka
217
-
218
-<!-- end -->
219
-
220
-Does it bother you that they aren't sorted by last name?  Me too.  As a partial
221
-solution, we can ask `sort` to use the second "field" in each line as its sort
222
-**k**ey (by default, sort treats whitespace as a division between fields):
223
-
224
-<!-- exec -->
225
-
226
-    $ sort -k2 authors_*
227
-    John Brunner
228
-    Pat Cadigan
229
-    Ursula K. Le Guin
230
-    Gwendolyn L. Waring
231
-    Eden Robinson
232
-    John Ronald Reuel Tolkien
233
-    James Tiptree, Jr.
234
-    Miriam Toews
235
-    Vanessa Veselka
236
-    Vanessa Veselka
237
-    Jo Walton
238
-
239
-<!-- end -->
240
-
241
-That's closer, right?  It sorted on "Cadigan" and "Veselka" instead of "Pat"
242
-and "Vanessa".  (Of course, it's still far from perfect, because the
243
-second field in each line isn't necessarily the person's last name.)
244
-
245
-options
246
--------
247
-
248
-Above, when we wanted to ask `sort` to behave differently, we gave it what is
249
-known as an option.  Most programs with command-line interfaces will allow
250
-their behavior to be changed by adding various options.  Options usually 
251
-(but not always!) look like `-o` or `--option`.
252
-
253
-For example, if we wanted to see just the unique lines, irrespective of case,
254
-for a file called colors:
255
-
256
-<!-- exec -->
257
-
258
-    $ cat colors
259
-    RED
260
-    blue
261
-    red
262
-    BLUE
263
-    Green
264
-    green
265
-    GREEN
266
-
267
-<!-- end -->
268
-
269
-We could write this:
270
-
271
-<!-- exec -->
272
-
273
-    $ sort -uf colors
274
-    blue
275
-    Green
276
-    RED
277
-
278
-<!-- end -->
279
-
280
-Here `-u` stands for **u**nique and `-f` stands for **f**old case, which means
281
-to treat upper- and lower-case letters as the same for comparison purposes.  You'll
282
-often see a group of short options following the `-` like this.
283
-
284
-uniq
285
-----
286
-
287
-Did you notice how Vanessa Veselka shows up twice in our list of authors?
288
-That's useful if we want to remember that she's in more than one category, but
289
-it's redundant if we're just worried about membership in the overall set of
290
-authors.  We can make sure our list doesn't contain repeating lines by using
291
-`sort`, just like with that list of colors:
292
-
293
-<!-- exec -->
294
-
295
-    $ sort -u -k2 authors_*
296
-    John Brunner
297
-    Pat Cadigan
298
-    Ursula K. Le Guin
299
-    Gwendolyn L. Waring
300
-    Eden Robinson
301
-    John Ronald Reuel Tolkien
302
-    James Tiptree, Jr.
303
-    Miriam Toews
304
-    Vanessa Veselka
305
-    Jo Walton
306
-
307
-<!-- end -->
308
-
309
-But there's another approach to this --- `sort` is good at only displaying a line
310
-once, but suppose we wanted to see a count of how many different lists an
311
-author shows up on?  `sort` doesn't do that, but a command called `uniq` does,
312
-if you give it the option `-c` for **c**ount.
313
-
314
-`uniq` moves through the lines in its input, and if it sees a line more than
315
-once in sequence, it will only print that line once.  If you have a bunch of
316
-files and you just want to see the unique lines across all of those files, you
317
-probably need to run them through `sort` first.  How do you do that?
318
-
319
-<!-- exec -->
320
-
321
-    $ sort authors_* | uniq -c
322
-          1 Eden Robinson
323
-          1 Gwendolyn L. Waring
324
-          1 James Tiptree, Jr.
325
-          1 John Brunner
326
-          1 John Ronald Reuel Tolkien
327
-          1 Jo Walton
328
-          1 Miriam Toews
329
-          1 Pat Cadigan
330
-          1 Ursula K. Le Guin
331
-          2 Vanessa Veselka
332
-
333
-<!-- end -->
334
-
335
-standard IO
336
------------
337
-
338
-The `|` is called a "pipe".  In the command above, it tells your shell that
339
-instead of printing the output of `sort authors_*` right to your terminal, it
340
-should send it to `uniq -c`.
341
-
342
--> <img src="images/pipe.gif"> <-
343
-
344
-Pipes are some of the most important magic in the shell.  When the people who
345
-built Unix in the first place give interviews about the stuff they remember
346
-from the early days, a lot of them reminisce about the invention of pipes and
347
-all of the new stuff it immediately made possible.
348
-
349
-Pipes help you control a thing called "standard IO".  In the world of the
350
-command line, programs take **i**nput and produce **o**utput.  A pipe is a way
351
-to hook the output from one program to the input of another.
352
-
353
-Unlike a lot of the weirdly named things you'll encounter in software, the
354
-metaphor here is obvious and makes pretty good sense.  It even kind of looks
355
-like a physical pipe.
356
-
357
-What if, instead of sending the output of one program to the input of another,
358
-you'd like to store it in a file for later use?
359
-
360
-Check it out:
361
-
362
-<!-- exec -->
363
-
364
-    $ sort authors_* | uniq > ./all_authors
365
-    
366
-<!-- end -->
367
-
368
-<!-- exec -->
369
-
370
-    $ cat all_authors
371
-    Eden Robinson
372
-    Gwendolyn L. Waring
373
-    James Tiptree, Jr.
374
-    John Brunner
375
-    John Ronald Reuel Tolkien
376
-    Jo Walton
377
-    Miriam Toews
378
-    Pat Cadigan
379
-    Ursula K. Le Guin
380
-    Vanessa Veselka
381
-
382
-<!-- end -->
383
-
384
-I like to think of the `>` as looking like a little funnel.  It can be
385
-dangerous --- you should always make sure that you're not going to clobber
386
-an existing file you actually want to keep.
387
-
388
-If you want to tack more stuff on to the end of an existing file, you can use
389
-`>>` instead.  To test that, let's use `echo`, which prints out whatever string
390
-you give it on a line by itself:
391
-
392
-<!-- exec -->
393
-
394
-    $ echo 'hello' > hello_world
395
-    
396
-<!-- end -->
397
-
398
-<!-- exec -->
399
-
400
-    $ echo 'world' >> hello_world
401
-    
402
-<!-- end -->
403
-
404
-<!-- exec -->
405
-
406
-    $ cat hello_world
407
-    hello
408
-    world
409
-
410
-<!-- end -->
411
-
412
-You can also take a file and pull it directly back into the input of a given
413
-program, which is a bit like a funnel going the other direction:
414
-
415
-<!-- exec -->
416
-
417
-    $ nl < all_authors
418
-         1	Eden Robinson
419
-         2	Gwendolyn L. Waring
420
-         3	James Tiptree, Jr.
421
-         4	John Brunner
422
-         5	John Ronald Reuel Tolkien
423
-         6	Jo Walton
424
-         7	Miriam Toews
425
-         8	Pat Cadigan
426
-         9	Ursula K. Le Guin
427
-        10	Vanessa Veselka
428
-
429
-<!-- end -->
430
-
431
-`nl` is just a way to **n**umber **l**ines.  This command accomplishes pretty much
432
-the same thing as `cat all_authors | nl`, or `nl all_authors`.  You won't see
433
-it used as often as `|` and `>`, since most utilities can read files on their
434
-own, but it can save you typing `cat` quite as often.
435
-
436
-We'll use these features liberally from here on out.
437
-
438
-`--help` and man pages
439
-----------------------
440
-
441
-You can change the behavior of most tools by giving them different options.
442
-This is all well and good if you already know what options are available,
443
-but what if you don't?
444
-
445
-Often, you can ask the tool itself:
446
-
447
-    $ sort --help
448
-    Usage: sort [OPTION]... [FILE]...
449
-      or:  sort [OPTION]... --files0-from=F
450
-    Write sorted concatenation of all FILE(s) to standard output.
451
-    
452
-    Mandatory arguments to long options are mandatory for short options too.
453
-    Ordering options:
454
-    
455
-      -b, --ignore-leading-blanks  ignore leading blanks
456
-      -d, --dictionary-order      consider only blanks and alphanumeric characters
457
-      -f, --ignore-case           fold lower case to upper case characters
458
-      -g, --general-numeric-sort  compare according to general numerical value
459
-      -i, --ignore-nonprinting    consider only printable characters
460
-      -M, --month-sort            compare (unknown) < 'JAN' < ... < 'DEC'
461
-      -h, --human-numeric-sort    compare human readable numbers (e.g., 2K 1G)
462
-      -n, --numeric-sort          compare according to string numerical value
463
-      -R, --random-sort           sort by random hash of keys
464
-          --random-source=FILE    get random bytes from FILE
465
-      -r, --reverse               reverse the result of comparisons
466
-
467
-...and so on.  (It goes on for a while in this vein.)
468
-
469
-If that doesn't work, or doesn't provide enough info, the next thing to try is
470
-called a man page.  ("man" is short for "manual".  It's sort of an unfortunate
471
-abbreviation.)
472
-
473
-    $ man sort
474
-
475
-    SORT(1)                         User Commands                        SORT(1)
476
-
477
-
478
-
479
-    NAME
480
-           sort - sort lines of text files
481
-
482
-    SYNOPSIS
483
-           sort [OPTION]... [FILE]...
484
-           sort [OPTION]... --files0-from=F
485
-
486
-    DESCRIPTION
487
-           Write sorted concatenation of all FILE(s) to standard output.
488
-
489
-...and so on.  Manual pages vary in quality, and it can take a while to get
490
-used to reading them, but they're very often the best place to look for help.
491
-
492
-If you're not sure what _program_ you want to use to solve a given problem, you
493
-might try searching all the man pages on the system for a keyword.  `man`
494
-itself has an option to let you do this - `man -k keyword` - but most systems
495
-also have a shortcut called `apropos`, which I like to use because it's easy to
496
-remember if you imagine yourself saying "apropos of [some problem I have]..."
497
-
498
-<!-- exec -->
499
-
500
-    $ apropos -s1 sort
501
-    apt-sortpkgs (1)     - Utility to sort package index files
502
-    bunzip2 (1)          - a block-sorting file compressor, v1.0.6
503
-    bzip2 (1)            - a block-sorting file compressor, v1.0.6
504
-    comm (1)             - compare two sorted files line by line
505
-    sort (1)             - sort lines of text files
506
-    tsort (1)            - perform topological sort
507
-
508
-<!-- end -->
509
-
510
-It's useful to know that the manual represented by `man` has numbered sections
511
-for different kinds of manual pages.  Most of what the average user needs to
512
-know about lives in section 1, "User Commands", so you'll often see the names
513
-of different tools written like `sort(1)` or `cat(1)`.  This can be a good way
514
-to make it clear in writing that you're talking about a specific piece of
515
-software rather than a verb or a small carnivorous mammal.  (I specified `-s1`
516
-for section 1 above just to cut down on clutter, though in practice I usually
517
-don't bother.)
518
-
519
-Like other literary traditions, Unix is littered with this sort of convention.
520
-This one just happens to date from a time when the manual was still a physical
521
-book.
522
-
523
-wc
524
---
525
-
526
-`wc` stands for **w**ord **c**ount.  It does about what you'd expect - it
527
-counts the number of words in its input.
528
-
529
-    $ wc index.md
530
-      736  4117 24944 index.md
531
-
532
-736 is the number of lines, 4117 the number of words, and 24944 the number of
533
-characters in the file I'm writing right now.  I use this constantly.  Most
534
-obviously, it's a good way to get an idea of how much you've written.  `wc` is
535
-the tool I used to track my progress the last time I tried National Novel
536
-Writing Month:
537
-
538
-    $ find ~/p1k3/archives/2010/11 -regextype egrep -regex '.*([0-9]+|index)' -type f | xargs wc -w | tail -1
539
-     6585 total
540
-
541
-<!-- exec -->
542
-
543
-    $ cowsay 'embarrassing.'
544
-     _______________
545
-    < embarrassing. >
546
-     ---------------
547
-            \   ^__^
548
-             \  (oo)\_______
549
-                (__)\       )\/\
550
-                    ||----w |
551
-                    ||     ||
552
-
553
-<!-- end -->
554
-
555
-Anyway.  The less obvious thing about `wc` is that you can use it to count the
556
-output of other commands.  Want to know _how many_ unique authors we have?
557
-
558
-<!-- exec -->
559
-
560
-    $ sort authors_* | uniq | wc -l
561
-    10
562
-
563
-<!-- end -->
564
-
565
-This kind of thing is trivial, but it comes in handy more often than you might
566
-think.
567
-
568
-head, tail, and cut
569
--------------------
570
-
571
-Remember our old pal `cat`, which just splats everything it's given back to
572
-standard output?
573
-
574
-Sometimes you've got a piece of output that's more than you actually want to
575
-deal with at once.  Maybe you just want to glance at the first few lines in a
576
-file:
577
-
578
-<!-- exec -->
579
-
580
-    $ head -3 colors
581
-    RED
582
-    blue
583
-    red
584
-
585
-<!-- end -->
586
-
587
-...or maybe you want to see the last thing in a list:
588
-
589
-<!-- exec -->
590
-
591
-    $ sort colors | uniq -i | tail -1
592
-    red
593
-
594
-<!-- end -->
595
-
596
-...or maybe you're only interested in the first "field" in some list. You might
597
-use `cut`  here, asking it to treat spaces as delimiters between fields and
598
-return only the first field for each line of its input:
599
-
600
-<!-- exec -->
601
-
602
-    $ cut -d' ' -f1 ./authors_*
603
-    Eden
604
-    Vanessa
605
-    Miriam
606
-    Gwendolyn
607
-    Ursula
608
-    Jo
609
-    Pat
610
-    John
611
-    Vanessa
612
-    James
613
-    John
614
-
615
-<!-- end -->
616
-
617
-Suppose we're curious what the few most commonly occurring first names on our
618
-author list are?  Here's an approach, silly but effective, that combines a lot
619
-of what we've discussed so far and looks like plenty of one-liners I wind up
620
-writing in real life:
621
-
622
-<!-- exec -->
623
-
624
-    $ cut -d' ' -f1 ./authors_* | sort | uniq -ci | sort -n | tail -3
625
-          1 Ursula
626
-          2 John
627
-          2 Vanessa
628
-
629
-<!-- end -->
630
-
631
-Let's walk through this one step by step:
632
-
633
-First, we have `cut` extract the first field of each line in our author lists.
634
-
635
-    cut -d' ' -f1 ./authors_*
636
-
637
-Then we sort these results
638
-
639
-    | sort
640
-
641
-and pass them to `uniq`, asking it for a case-insensitive count of each
642
-repeated line
643
-
644
-    | uniq -ci
645
-
646
-then sort again, numerically, 
647
-
648
-    | sort -n
649
-
650
-and finally, we chop off everything but the last three lines:
651
-
652
-    | tail -3
653
-
654
-If you wanted to make sure to count an individual author's first name
655
-only once, even if that author appears more than once in the files,
656
-you could instead do:
657
-
658
-<!-- exec -->
659
-
660
-    $ sort -u ./authors_* | cut -d' ' -f1 | uniq -ci | sort -n | tail -3
661
-          1 Ursula
662
-          1 Vanessa
663
-          2 John
664
-
665
-<!-- end -->
666
-
667
-tab separated values
668
---------------------
669
-
670
-Notice above how we had to tell `cut` that "fields" in `authors_*` are
671
-delimited by spaces?  It turns out that if you don't use `-d`, `cut` defaults
672
-to using tab characters for a delimiter.
673
-
674
-Tab characters are sort of weird little animals.  You can't usually _see_ them
675
-directly --- they're like a space character that takes up more than one space
676
-when displayed.  By convention, one tab is usually rendered as 8 spaces, but
677
-it's up to the software that's displaying the character what it wants to do.
678
-
679
-(In fact, it's more complicated than that:  Tabs are often rendered as marking
680
-_tab stops_, which is a concept I remember from 7th grade typing classes, but
681
-haven't actually thought about in my day-to-day life for nearly 20 years.)
682
-
683
-Here's a version of our `all_authors` that's been rearranged so that the first
684
-field is the author's last name, the second is their first name, the third is
685
-their middle name or initial (if we know it) and the fourth is any suffix.
686
-Fields are separated by a single tab character:
687
-
688
-<!-- exec -->
689
-
690
-    $ cat all_authors.tsv
691
-    Robinson	Eden
692
-    Waring	Gwendolyn	L.
693
-    Tiptree	James		Jr.
694
-    Brunner	John
695
-    Tolkien	John	Ronald Reuel
696
-    Walton	Jo
697
-    Toews	Miriam
698
-    Cadigan	Pat
699
-    Le Guin	Ursula	K.
700
-    Veselka	Vanessa
701
-
702
-<!-- end -->
703
-
704
-That looks kind of garbled, right?  In order to make it a little more obvious
705
-what's happening, let's use `cat -T`, which displays tab characters as `^I`:
706
-
707
-<!-- exec -->
708
-
709
-    $ cat -T all_authors.tsv
710
-    Robinson^IEden
711
-    Waring^IGwendolyn^IL.
712
-    Tiptree^IJames^I^IJr.
713
-    Brunner^IJohn
714
-    Tolkien^IJohn^IRonald Reuel
715
-    Walton^IJo
716
-    Toews^IMiriam
717
-    Cadigan^IPat
718
-    Le Guin^IUrsula^IK.
719
-    Veselka^IVanessa
720
-
721
-<!-- end -->
722
-
723
-It looks odd when displayed because some names are at or nearly at 8 characters long.
724
-"Robinson", at 8 characters, overshoots the first tab stop, so "Eden" gets indented
725
-further than other first names, and so on.
726
-
727
-Fortunately, in order to make this more human-readable, we can pass it through
728
-`expand`, which turns tabs into a given number of spaces (8 by default):
729
-
730
-<!-- exec -->
731
-
732
-    $ expand -t14 all_authors.tsv
733
-    Robinson      Eden
734
-    Waring        Gwendolyn     L.
735
-    Tiptree       James                       Jr.
736
-    Brunner       John
737
-    Tolkien       John          Ronald Reuel
738
-    Walton        Jo
739
-    Toews         Miriam
740
-    Cadigan       Pat
741
-    Le Guin       Ursula        K.
742
-    Veselka       Vanessa
743
-
744
-<!-- end -->
745
-
746
-Now it's easy to sort by last name:
747
-
748
-<!-- exec -->
749
-
750
-    $ sort -k1 all_authors.tsv | expand -t14
751
-    Brunner       John
752
-    Cadigan       Pat
753
-    Le Guin       Ursula        K.
754
-    Robinson      Eden
755
-    Tiptree       James                       Jr.
756
-    Toews         Miriam
757
-    Tolkien       John          Ronald Reuel
758
-    Veselka       Vanessa
759
-    Walton        Jo
760
-    Waring        Gwendolyn     L.
761
-
762
-<!-- end -->
763
-
764
-Or just extract middle names and initials:
765
-
766
-<!-- exec -->
767
-
768
-    $ cut -f3 all_authors.tsv
769
-    
770
-    L.
771
-    
772
-    
773
-    Ronald Reuel
774
-    
775
-    
776
-    
777
-    K.
778
-    
779
-
780
-<!-- end -->
781
-
782
-It probably won't surprise you to learn that there's a corresponding `paste`
783
-command, which takes two or more files and stitches them together with tab
784
-characters.  Let's extract a couple of things from our author list and put them
785
-back together in a different order:
786
-
787
-<!-- exec -->
788
-
789
-    $ cut -f1 all_authors.tsv > lastnames
790
-    
791
-<!-- end -->
792
-
793
-<!-- exec -->
794
-
795
-    $ cut -f2 all_authors.tsv > firstnames
796
-    
797
-<!-- end -->
798
-
799
-<!-- exec -->
800
-
801
-    $ paste firstnames lastnames | sort -k2 | expand -t12
802
-    John        Brunner
803
-    Pat         Cadigan
804
-    Ursula      Le Guin
805
-    Eden        Robinson
806
-    James       Tiptree
807
-    Miriam      Toews
808
-    John        Tolkien
809
-    Vanessa     Veselka
810
-    Jo          Walton
811
-    Gwendolyn   Waring
812
-
813
-<!-- end -->
814
-
815
-As these examples show, TSV is something very like a primitive spreadsheet:  A
816
-way to represent information in columns and rows.  In fact, it's a close cousin
817
-of CSV, which is often used as a lowest-common-denominator format for
818
-transferring spreadsheets, and which represents data something like this:
819
-
820
-    last,first,middle,suffix
821
-    Tolkien,John,Ronald Reuel,
822
-    Tiptree,James,,Jr.
823
-
824
-The advantage of tabs is that they're supported by a bunch of the standard
825
-tools.  A disadvantage is that they're kind of ugly and can be weird to deal
826
-with, but they're useful anyway, and character-delimited rows are often a
827
-good-enough way to hack your way through problems that call for basic
828
-structure.
829
-
830
-finding text: grep
831
-------------------
832
-
833
-After all those contortions, what if you actually just want to see _which lists_
834
-an individual author appears on?
835
-
836
-<!-- exec -->
837
-
838
-    $ grep 'Vanessa' ./authors_*
839
-    ./authors_contemporary_fic:Vanessa Veselka
840
-    ./authors_sff:Vanessa Veselka
841
-
842
-<!-- end -->
843
-
844
-`grep` takes a string to search for and, optionally, a list of files to search
845
-in.   If you don't specify files, it'll look through standard input instead:
846
-
847
-<!-- exec -->
848
-
849
-    $ cat ./authors_* | grep 'Vanessa'
850
-    Vanessa Veselka
851
-    Vanessa Veselka
852
-
853
-<!-- end -->
854
-
855
-Most of the time, piping the output of `cat` to `grep` is considered silly,
856
-because `grep` knows how to find things in files on its own.  Many thousands of
857
-words have been written on this topic by leading lights of the nerd community.
858
-
859
-You've probably noticed that this result doesn't contain filenames (and thus
860
-isn't very useful to us).  That's because all `grep` saw was the lines in the
861
-files, not the names of the files themselves.
862
-
863
-now you have n problems
864
------------------------
865
-
866
-To close out this introductory chapter, let's spend a little time on a topic
867
-that will likely vex, confound, and (occasionally) delight you for as long as
868
-you are acquainted with the command line.
869
-
870
-When I was talking about `grep` a moment ago, I fudged the details more than a
871
-little by saying that it expects a string to search for.  What `grep`
872
-_actually_ expects is a _pattern_.  Moreover, it expects a specific kind of
873
-pattern, what's known as a _regular expression_, a cumbersome phrase frequently
874
-shortened to regex.
875
-
876
-There's a lot of theory about what makes up a regular expression.  Fortunately,
877
-very little of it matters to the short version that will let you get useful
878
-stuff done.  The short version is that a regex is like using wildcards in the
879
-shell to match groups of files, but for text in general and with more magic.
880
-
881
-<!-- exec -->
882
-
883
-    $ grep 'Jo.*' ./authors_*
884
-    ./authors_sff:Jo Walton
885
-    ./authors_sff:John Ronald Reuel Tolkien
886
-    ./authors_sff:John Brunner
887
-
888
-<!-- end -->
889
-
890
-The pattern `Jo.*` says that we're looking for lines which contain a literal
891
-`Jo`, followed by any quantity (including none) of any character.  In a regex,
892
-`.` means "anything" and `*` means "any amount of the preceding thing".
893
-
894
-`.` and `*` are magical.  In the particular dialect of regexen understood
895
-by `grep`, other magical things include:
896
-
897
-<table>
898
-    <tr><td><code>^</code>    </td>  <td>start of a line                     </td></tr>
899
-    <tr><td><code>$</code>    </td>  <td>end of a line                       </td></tr>
900
-    <tr><td><code>[abc]</code></td>  <td>one of a, b, or c                   </td></tr>
901
-    <tr><td><code>[a-z]</code></td>  <td>a character in the range a through z</td></tr>
902
-    <tr><td><code>[0-9]</code></td>  <td>a character in the range 0 through 9</td></tr>
903
-
904
-    <tr><td><code>+</code>    </td>  <td>one or more of the preceding thing  </td></tr>
905
-    <tr><td><code>?</code>    </td>  <td>0 or 1 of the preceding thing       </td></tr>
906
-    <tr><td><code>*</code>    </td>  <td>any number of the preceding thing   </td></tr>
907
-
908
-    <tr><td><code>(foo|bar)</code></td>  <td>"foo" or "bar"</td></tr>
909
-    <tr><td><code>(foo)?</code></td>     <td>optional "foo"</td></tr>
910
-</table>
911
-
912
-It's actually a little more complicated than that:  By default, if you want to
913
-use a lot of the magical characters, you have to prefix them with `\`.  This is
914
-both ugly and confusing, so unless you're writing a very simple pattern, it's
915
-often easiest to call `grep -E`, for **E**xtended regular expressions, which
916
-means that lots of characters will have special meanings.
917
-
918
-Authors with 4-letter first names:
919
-
920
-<!-- exec -->
921
-
922
-    $ grep -iE '^[a-z]{4} ' ./authors_*
923
-    ./authors_contemporary_fic:Eden Robinson
924
-    ./authors_sff:John Ronald Reuel Tolkien
925
-    ./authors_sff:John Brunner
926
-
927
-<!-- end -->
928
-
929
-A count of authors named John:
930
-
931
-<!-- exec -->
932
-
933
-    $ grep -c '^John ' ./all_authors
934
-    2
935
-
936
-<!-- end -->
937
-
938
-Lines in this file matching the words "magic" or "magical":
939
-
940
-    $ grep -iE 'magic(al)?' ./index.md
941
-    Pipes are some of the most important magic in the shell.  When the people who
942
-    shell to match groups of files, but with more magic.
943
-    `.` and `*` are magical.  In the particular dialect of regexen understood
944
-    by `grep`, other magical things include:
945
-    use a lot of the magical characters, you have to prefix them with `\`.  This is
946
-    Lines in this file matching the words "magic" or "magical":
947
-        $ grep -iE 'magic(al)?' ./index.md
948
-
949
-Find some "-agic" words in a big list of words:
950
-
951
-<!-- exec -->
952
-
953
-    $ grep -iE '(m|tr|pel)agic' /usr/share/dict/words
954
-    magic
955
-    magic's
956
-    magical
957
-    magically
958
-    magician
959
-    magician's
960
-    magicians
961
-    pelagic
962
-    tragic
963
-    tragically
964
-    tragicomedies
965
-    tragicomedy
966
-    tragicomedy's
967
-
968
-<!-- end -->
969
-
970
-`grep` isn't the only - or even the most important - tool that makes use of
971
-regular expressions, but it's a good place to start because it's one of the
972
-fundamental building blocks for so many other operations.  Filtering lists of
973
-things, matching patterns within collections, and writing concise descriptions
974
-of how text should be transformed are at the heart of a practical approach to
975
-Unix-like systems.  Regexen turn out to be a seductively powerful way to do
976
-these things - so much so that they've crept their way into text editors,
977
-databases, and full-featured programming languages.
978
-
979
-There's a dark side to all of this, for the truth about regular expressions is
980
-that they are ugly, inconsistent, brittle, and _incredibly_ difficult to think
981
-clearly about.  They take years to master and reward the wielder with great
982
-power, but they are also a trap: a temptation towards the path of cleverness
983
-masquerading as wisdom.
984
-
985
--> ✑ <-
986
-
987
-I'll be returning to this theme, but for the time being let's move on.  Now
988
-that we've established, however haphazardly, some of the basics, let's consider
989
-their application to a real-world task.

+ 0
- 10
literary_environment/lastnames View File

@@ -1,10 +0,0 @@
1
-Robinson
2
-Waring
3
-Tiptree
4
-Brunner
5
-Tolkien
6
-Walton
7
-Toews
8
-Cadigan
9
-Le Guin
10
-Veselka

+ 0
- 1
literary_problem/README.md View File

@@ -1 +0,0 @@
1
-index.md

+ 0
- 150
literary_problem/index.md View File

@@ -1,150 +0,0 @@
1
-2. a literary problem
2
-=====================
3
-
4
-The [previous chapter](../literary_environment) introduced a bunch of tools
5
-using contrived examples.  Now we'll look at a real problem, and work through a
6
-solution by building on tools we've already covered.
7
-
8
-So on to the problem:  I write poetry.
9
-
10
-{rimshot dot wav}
11
-
12
-Most of the poems I have written are not very good, but lately I've been
13
-thinking that I'd like to comb through the last ten years' worth and pull
14
-the least-embarrassing stuff into a single collection.
15
-
16
-I've hinted at how the contents of my blog are stored as files, but let's take
17
-a look at the whole thing:
18
-
19
-    $ ls -F ~/p1k3/archives/
20
-    1997/  2003/  2009/  bones/     meta/
21
-    1998/  2004/  2010/  chapbook/  winfield/
22
-    1999/  2005/  2011/  cli/       wip/
23
-    2000/  2006/  2012/  colophon/
24
-    2001/  2007/  2013/  europe/
25
-    2002/  2008/  2014/  hack/
26
-
27
-(`ls`, again, just lists files.  `-F` tells it to append a character that shows
28
-it what type of file we're looking at, such as a trailing / for directories.
29
-`~` is a shorthand that means "my home directory", which in this case is
30
-`/home/brennen`.)
31
-
32
-Each of the directories here holds other directories.  The ones for each year
33
-have sub-directories for the months of the year, which in turn contain files
34
-for the days.  The files are just little pieces of HTML and Markdown and some
35
-other stuff.  Many years ago, before I had much of an idea how to program, I
36
-wrote a script to glue them all together into a web page and serve them up to
37
-visitors.  This all sounds complicated, but all it really means is that if I
38
-want to write a blog entry, I just open a file and type some stuff.  Here's an
39
-example for March 1st:
40
-
41
-<!-- exec -->
42
-
43
-    $ cat ~/p1k3/archives/2014/3/1
44
-    <h1>Saturday, March 1</h1>
45
-    
46
-    <markdown>
47
-    Sometimes I'm going along on a Saturday morning, still a little dazed from the
48
-    night before, and I think something like "I should just go write a detailed
49
-    analysis of hooded sweatshirts".  Mostly these thoughts don't survive contact
50
-    with an actual keyboard.  It's almost certainly for the best.
51
-    </markdown>
52
-
53
-<!-- end -->
54
-
55
-And here's an older one that contains a short poem:
56
-
57
-<!-- exec -->
58
-
59
-    $ cat ~/p1k3/archives/2012/10/9
60
-    <h1>tuesday, october 9</h1>
61
-    
62
-    <freeverse>i am a stateful machine
63
-    i exist in a manifold of consequence
64
-    a clattering miscellany of impure functions
65
-    and side effects</freeverse>
66
-
67
-<!-- end -->
68
-
69
-Notice that `<freeverse>` bit?  It kind of looks like an HTML tag, but it's
70
-not.  What it actually does is tell my blog script that it should format the
71
-text it contains like a poem.  The specifics don't matter for our purposes
72
-(yet), but this convention is going to come in handy, because the first thing I
73
-want to do is get a list of all the entries that contain poems.
74
-
75
-Remember `grep`?
76
-
77
-    $ grep -ri '<freeverse>' ~/p1k3/archives > ~/possible_poems
78
-
79
-Let's step through this bit by bit:
80
-
81
-First, I'm asking `grep` to search **r**ecursively, **i**gnoring case.
82
-"Recursively" just means that every time the program finds a directory, it
83
-should descend into that directory and search in any files there as well.
84
-
85
-    grep -ri
86
-
87
-Next comes a pattern to search for.  It's in single quotes because the
88
-characters `<` and `>` have a special meaning to the shell, and here we need
89
-the shell to understand that it should treat them as literal angle brackets
90
-instead.
91
-
92
-    '<freeverse>'
93
-
94
-This is the path I want to search:
95
-
96
-    ~/p1k3/archives
97
-
98
-Finally, because there are so many entries to search, I know the process will
99
-be slow and produce a large list, so I tell the shell to redirect it to a file
100
-called `possible_poems` in my home directory:
101
-
102
-    > ~/possible_poems
103
-
104
-This is quite a few instances...
105
-
106
-    $ wc -l ~/possible_poems
107
-    679 /home/brennen/possible_poems
108
-
109
-...and it's also not super-pretty to look at:
110
-
111
-    $ head -5 ~/possible_poems
112
-    /home/brennen/p1k3/archives/2011/10/14:<freeverse>i've got this friend has a real knack
113
-    /home/brennen/p1k3/archives/2011/4/25:<freeverse>i can't claim to strive for it
114
-    /home/brennen/p1k3/archives/2011/8/10:<freeverse>one diminishes or becomes greater
115
-    /home/brennen/p1k3/archives/2011/8/12:<freeverse>
116
-    /home/brennen/p1k3/archives/2011/1/1:<freeverse>six years on
117
-
118
-Still, it's a decent start.  I can see paths to the files I have to check, and
119
-usually a first line.  Since I use a fancy text editor, I can just go down the
120
-list opening each file in a new window and copying the stuff I'm interested in
121
-to a new file.
122
-
123
-This is good enough for government work, but what if instead of jumping around
124
-between hundreds of files, I'd rather read everything in one file and just weed
125
-out the bad ones as I go?
126
-
127
-    $ cat `grep -ril '<freeverse>' ~/p1k3/archives` > ~/possible_poems_full
128
-
129
-This probably bears some explaining.  `grep` is still doing all the real work
130
-here.  The main difference from before is that `-l` tells grep to just list any
131
-files it finds which contain a match.
132
-
133
-    `grep -ril '<freeverse>' ~/p1k3/archives`
134
-
135
-Notice those backticks around the grep command?  This part is a little
136
-trippier.  It turns out that if you put backticks around something in a
137
-command, it'll get executed and replaced with its result, which in turn gets
138
-executed as part of the larger command.  So what we're really saying is
139
-something like:
140
-
141
-    $ cat [all of the files in the blog directory with <freeverse> in them]
142
-
143
-Did you catch that?  I just wrote a command that rewrote itself as a
144
-_different_, more specific command.  And it appears to have worked on the
145
-first try:
146
-
147
-    $ wc ~/possible_poems_full
148
-     17628  80980 528699 /home/brennen/possible_poems_full
149
-
150
-Welcome to wizard school.

+ 0
- 239
miscellany/index.md View File

@@ -1,239 +0,0 @@
1
-8. a miscellany of tools and techniques
2
-=======================================
3
-
4
-dict
5
-----
6
-
7
-Want to know the definition of a word, or find useful synonyms?
8
-
9
-    $ dict concatenate | head -10
10
-    4 definitions found
11
-    
12
-    From The Collaborative International Dictionary of English v.0.48 [gcide]:
13
-    
14
-      Concatenate \Con*cat"e*nate\ (k[o^]n*k[a^]t"[-e]*n[=a]t), v. t.
15
-         [imp. & p. p. {Concatenated}; p. pr. & vb. n.
16
-         {Concatenating}.] [L. concatenatus, p. p. of concatenare to
17
-         concatenate. See {Catenate}.]
18
-         To link together; to unite in a series or chain, as things
19
-         depending on one another.
20
-
21
-aspell
22
-------
23
-
24
-Need to interactively spell-check your presentation notes?
25
-
26
-    $ aspell check presentation
27
-
28
-Just want a list of potentially-misspelled words in a given file?
29
-
30
-<!-- exec -->
31
-
32
-    $ aspell list < ../literary_environment/index.md | sort | uniq -ci | sort -nr | head -5
33
-         40 td
34
-         24 Veselka
35
-         17 Reuel
36
-         16 Brunner
37
-         15 Tiptree
38
-
39
-<!-- end -->
40
-
41
-mostcommon
42
-----------
43
-
44
-Something like that last sequence sure does seem to show up a lot in my work:
45
-Spit out the _n_ most common lines in the input, one way or another.   Here's
46
-a little script to be less repetitive about it.
47
-
48
-<!-- exec -->
49
-
50
-    $ aspell list < ../literary_environment/index.md | ./mostcommon -i -n5
51
-         40 td
52
-         24 Veselka
53
-         17 Reuel
54
-         16 Brunner
55
-         15 Tiptree
56
-
57
-<!-- end -->
58
-
59
-This turns out to be pretty simple:
60
-
61
-<!-- exec -->
62
-
63
-    $ cat ./mostcommon
64
-    #!/usr/bin/env bash
65
-    
66
-    # Optionally specify number of lines to show, defaulting to 10:
67
-    TOSHOW=10
68
-    CASEOPT=""
69
-    
70
-    while getopts ":in:" opt; do
71
-      case $opt in
72
-        i)
73
-          CASEOPT="-i"
74
-          ;;
75
-        n)
76
-          TOSHOW=$OPTARG
77
-          ;;
78
-        \?)
79
-          echo "Invalid option: -$OPTARG" >&2
80
-          exit 1
81
-          ;;
82
-        :)
83
-          echo "Option -$OPTARG requires an argument." >&2
84
-          exit 1
85
-          ;;
86
-      esac
87
-    done
88
-    
89
-    # sort and then uniqify STDIN,
90
-    # sort numerically on the first field,
91
-    # chop off everything but $TOSHOW lines of input
92
-    
93
-    sort < /dev/stdin | uniq -c $CASEOPT | sort -k1 -nr | head -$TOSHOW
94
-
95
-<!-- end -->
96
-
97
-Notice, though, that it doesn't handle opening files directly.  If you wanted
98
-to find the most common lines in a file with it, you'd have to say something
99
-like `mostcommon < filename` in order to redirect the file to `mostcommon`'s
100
-input.
101
-
102
-Also notice that most of the script is boilerplate for handling a couple of
103
-options.  The work is all done in a oneliner.  Worth it?  Maybe not, but an
104
-interesting exercise.
105
-
106
-cal and ncal
107
-------------
108
-
109
-Want to know what the calendar looks like for this month?
110
-
111
-    $ cal
112
-         April 2014       
113
-    Su Mo Tu We Th Fr Sa  
114
-           1  2  3  4  5  
115
-     6  7  8  9 10 11 12  
116
-    13 14 15 16 17 18 19  
117
-    20 21 22 23 24 25 26  
118
-    27 28 29 30           
119
-
120
-How about for September, 1950, in a more compact format?
121
-
122
-<!-- exec -->
123
-
124
-    $ ncal -m9 1950
125
-        September 1950    
126
-    Su     3 10 17 24   
127
-    Mo     4 11 18 25   
128
-    Tu     5 12 19 26   
129
-    We     6 13 20 27   
130
-    Th     7 14 21 28   
131
-    Fr  1  8 15 22 29   
132
-    Sa  2  9 16 23 30   
133
-
134
-<!-- end -->
135
-
136
-Need to know the date of Easter this year?
137
-
138
-<!-- exec -->
139
-
140
-    $ ncal -e
141
-    April 20 2014
142
-
143
-<!-- end -->
144
-
145
-seq
146
----
147
-
148
-Need the numbers 1-5?
149
-
150
-<!-- exec -->
151
-
152
-    $ seq 1 5
153
-    1
154
-    2
155
-    3
156
-    4
157
-    5
158
-
159
-<!-- end -->
160
-
161
-shuf
162
-----
163
-
164
-Want to shuffle some lines?
165
-
166
-<!-- exec -->
167
-
168
-    $ seq 1 5 | shuf
169
-    2
170
-    1
171
-    4
172
-    3
173
-    5
174
-
175
-<!-- end -->
176
-
177
-ptx
178
----
179
-
180
-Want to make a [permuted index][kwic] of some phrase?
181
-
182
-<!-- exec -->
183
-
184
-    $ echo 'i like american music' | ptx
185
-                                  i like   american music
186
-                                           i like american music
187
-                                       i   like american music
188
-                         i like american   music
189
-
190
-<!-- end -->
191
-
192
-
193
-
194
-figlet
195
-------
196
-
197
-Need to make ASCII art of some giant letters?
198
-
199
-<!-- exec -->
200
-
201
-    $ figlet "R T F M"
202
-     ____    _____   _____   __  __ 
203
-    |  _ \  |_   _| |  ___| |  \/  |
204
-    | |_) |   | |   | |_    | |\/| |
205
-    |  _ <    | |   |  _|   | |  | |
206
-    |_| \_\   |_|   |_|     |_|  |_|
207
-                                    
208
-
209
-<!-- end -->
210
-
211
-cowsay
212
-------
213
-
214
-How about ASCII art of a <del>cow</del> dragon saying something?
215
-
216
-<!-- exec -->
217
-
218
-    $ cowsay -f dragon "RTFM, man"
219
-     ___________
220
-    < RTFM, man >
221
-     -----------
222
-          \                    / \  //\
223
-           \    |\___/|      /   \//  \\
224
-                /0  0  \__  /    //  | \ \    
225
-               /     /  \/_/    //   |  \  \  
226
-               @_^_@'/   \/_   //    |   \   \ 
227
-               //_^_/     \/_ //     |    \    \
228
-            ( //) |        \///      |     \     \
229
-          ( / /) _|_ /   )  //       |      \     _\
230
-        ( // /) '/,_ _ _/  ( ; -.    |    _ _\.-~        .-~~~^-.
231
-      (( / / )) ,-{        _      `-.|.-~-.           .~         `.
232
-     (( // / ))  '/\      /                 ~-. _ .-~      .-~^-.  \
233
-     (( /// ))      `.   {            }                   /      \  \
234
-      (( / ))     .----~-.\        \-'                 .~         \  `. \^-.
235
-                 ///.----..>        \             _ -~             `.  ^-`  ^-_
236
-                   ///-._ _ _ _ _ _ _}^ - - - - ~                     ~-- ,.-~
237
-                                                                      /.-~
238
-
239
-<!-- end -->

+ 0
- 30
miscellany/mostcommon View File

@@ -1,30 +0,0 @@
1
-#!/usr/bin/env bash
2
-
3
-# Optionally specify number of lines to show, defaulting to 10:
4
-TOSHOW=10
5
-CASEOPT=""
6
-
7
-while getopts ":in:" opt; do
8
-  case $opt in
9
-    i)
10
-      CASEOPT="-i"
11
-      ;;
12
-    n)
13
-      TOSHOW=$OPTARG
14
-      ;;
15
-    \?)
16
-      echo "Invalid option: -$OPTARG" >&2
17
-      exit 1
18
-      ;;
19
-    :)
20
-      echo "Option -$OPTARG requires an argument." >&2
21
-      exit 1
22
-      ;;
23
-  esac
24
-done
25
-
26
-# sort and then uniqify STDIN,
27
-# sort numerically on the first field,
28
-# chop off everything but $TOSHOW lines of input
29
-
30
-sort < /dev/stdin | uniq -c $CASEOPT | sort -k1 -nr | head -$TOSHOW

+ 0
- 1
programmerthink/README.md View File

@@ -1 +0,0 @@
1
-index.md

+ 0
- 293
programmerthink/index.md View File

<
@@ -1,293 +0,0 @@
1
-3. programmerthink
2
-==================
3
-
4
-In the [preceding chapter](#a-literary-problem), I worked through accumulating
5
-a big piece of text from some other, smaller texts.  I started with a bunch of
6
-files and wound up with one big file called `potential_poems_full`.
7
-
8
-Let's talk for a minute about how programmers approach problems like this one.
9
-What I've just done is sort of an old-school humanities take on things:
10
-Metaphorically speaking, I took a book off the shelf and hauled it down to the
11
-copy machine to xerox a bunch of pages, and now I'm going to start in on them
12
-with a highlighter and some Post-Its or something.  A process like this will
13
-often trigger a cascade of questions in the programmer-mind:
14
-
15
-- What if, halfway through the project, I realize my selection criteria were all
16
-  wrong and have to backtrack?
17
-- What if I discover corrections that also need to be made in the source documents?
18
-- What if I want to access metadata, like the original location of a file?
19
-- What if I want to quickly re-order the poems according to some new criteria?
20
-- Why am I storing the same text in two different places?
21
-
22
-A unifying theme of these questions is that they could all be answered by
23
-involving a little more abstraction.
24
-
25
--> ★ <-
26
-
27
-Some kinds of abstraction are so common in the physical world that we can
28
-forget they're part of a sophisticated technology.  For example, a good deal of
29
-bicycle maintenance can be accomplished with a cheap multi-tool containing a
30
-few different sizes of hex wrench and a couple of screwdrivers.
31
-
32
-A hex wrench or screwdriver doesn't really know anything about bicycles.  All
33
-it _really_ knows about is fitting into a space and allowing torque to be
34
-applied.  Standardized fasteners and adjustment mechanisms on a bicycle ensure
35
-that the work can be done anywhere, by anyone with a certain set of tools.
36
-Standard tools mean that if you can work on a particular bike, you can work on
37
-_most_ bikes, and even on things that aren't bikes at all, but were designed by
38
-people with the same abstractions in mind.
39
-
40
-The relationship between a wrench, a bolt, and the purpose of a bolt is a lot
41
-like something we call _indirection_ in software.  Programs like `grep` or
42
-`cat` don't really know anything about poetry.  All they _really_ know about is
43
-finding lines of text in input, or sticking inputs together.  Files, lines, and
44
-text are like standardized fasteners that allow a user who can work on one kind
45
-of data (be it poetry, a list of authors, the source code of a program) to use
46
-the same tools for other problems and other data.
47
-
48
--> ★ <-
49
-
50
-When I first started writing stuff on the web, I edited a page --- a single HTML
51
-file --- by hand.  When the entries on my nascent blog got old, I manually
52
-cut-and-pasted them to archive files with names like `old_main97.html`, which
53
-held all of the stuff I'd written in 1997.
54
-
55
-I'm not holding this up as an example of youthful folly.  In fact, it worked
56
-fine, and just having a single, static file that you can open in any text
57
-editor has turned out to be a _lot_ more future-proof than the sophisticated
58
-blogging software people were starting to write at the time.
59
-
60
-And yet.  Something about this habit nagged at my developing programmer mind
61
-after a few years.  It was just a little bit too manual and repetitive, a
62
-little bit silly to have to write things like a table of contents by hand, or
63
-move entries around by copy-and-pasting them to different files.  Since I knew
64
-the date for each entry, and wanted to make them navigable on that basis, why
65
-not define a directory structure for the years and months, and then write a
66
-file to hold each day?  That way, all I'd have to do is concatenate the files
67
-in one directory to display any given month:
68
-
69
-    $ cat ~/p1k3/archives/2014/1/* | head -10
70
-    <h1>Sunday, January 12</h1>
71
-    
72