Talk: Ittcl

Introduction to the Discussion

Please keep in mind while we are discussing this chapter and others: this is Andy's project and we are Volunteers.

i think this is a fun project. i'm anxious to make progress. i also think our discussions will provide valuable thoughts and feedback to make the project really great. but Andy may or may not arrive at the same conclusions we arrive at, or make the same decision we would. and if and when we inevitably disagree with each other, let's try and keep our hats on, folks!
let's put forth a few good notes for review, and then leave it up to Andy. -cheers.

Rhockens (talk) 10:37, 3 June 2019 (EDT)
See also ITTCL Community on Gitter (chat and networking).

Rhockens (talk) 09:13, 2 June 2019 (EDT)
Removed the proposed changes section that was on the main page since suggestions incorporate into this section and the v1/v2 comparison on main page.

discussion INTRODUCTION chapter, Proposed Changes

+ Motivate the reader with common tasks; how command line can solve these tasks
+ discuss making mention of Other Vendors' broadening support of Command line/Bash/other Unix tools. Microsoft, with Windows 10 command line and Debian in its App Store for example. Google, now supports Gnu/Linux tools natively in their 2019 Chromebooks.
+ Unifying Project: Find a Unifying Project for book to refer to all the way through. collaborative document. web page editing. use Git. use Markdown.
+ discuss pointing to more web resources

--S4t4nders (talk) 18:57, 16 May 2019 (EDT)

• motivate the reader with common tasks, i think its a good idea to have a story or a project to inspire our readers for sure. what those common tasks or stories are going to be, may depend on who the reader is.
  
• mention other vendors' broadening support for Gnu/Linux and its many command line tools, is a good idea as long as it wont be confusing for the reader as to what this book is covering. i think we're just covering the Gnu tools which come with, say, Trisequel or Debian?
  
• a unifying project is currently noted in the proposed changes column based on the wiki notes. but i want to first make sure i've understood it correctly. is the intent of discussing a unifying project meant to determine a project for the book's topics to all revolve around and kind of hook into to create some coherence? or, perhaps i've misunderstood. but it would seem we would need to propose and discuss a few unifying projects and decide on them before anybody begins to write anything so that we're all using the same project as a unifying element within our sections. which also might be the question, who are we writing to? we'd need to choose an attractive project for the answer to that question.
  
• regarding pointing to more web resources, i always want to be careful in this regard, because web links go stale without warning and then the text needs to be updated, or risk looking and feeling dated and broken. if resources outside the book were referred to without using web links that would break, or need to be maintained, i think that would be fine. otherwise, perhaps leave out actual web links altogether.
  
  

discussion BASICS chapter, Proposed Changes

+ move grep earlier, as a simple way to search

this grep item is up for discussion here because Andy didnt say put it in BASICS; just to move it earlier.

--S4t4nders (talk) 18:12, 16 May 2019 (EDT)

• i think introducing grep in a simple form can fit into this chapter just fine.
  
  

discussion COMMANDS chapter, Proposed Changes

+ discuss adding Visual Bash
+ consider changing name of this chapter from COMMANDS to BEGINNING (as a part of the common trilogy Beginning, Intermediate, Advanced)

--S4t4nders (talk) 18:17, 16 May 2019 (EDT)

• regarding Visual Bash, i'd simply question its place in a command line book. i propose sticking with the title and trying to be consistent on that. if our readers were looking for 'visual' anything, they may actually be in the wrong place.
  
• regarding changing the name of the chapter, i'm not sure we're allowed to do that. but that was a suggestion i put in the Proposed Changes column because it seemed appropriate to me, for an introductory book to be divided into Beginning, Intermediate and Advanced sections within the book.
  
  

Rhockens (talk) 12:46, 30 May 2019 (EDT)
The content of last section of this basics chapter seems too advanced for this stage of the book. It very briefly introduces stdin, stdout, stderr and gives examples of commands using the redirection operator > (but not >>) and pipe. It also introduces file descriptors and the exec command. [Edited Rhockens (talk) 10:43, 1 June 2019 (EDT)]

Rhockens (talk) 10:43, 1 June 2019 (EDT)
There is in fact a reference to >>. This chapter introduces but doesn't explain the * wildcard as well as pipe. Introduces command tee. Discussion of redirection seems rather advanced for this early stage of book. [Fixed typos Rhockens (talk) 11:21, 3 June 2019 (EDT)]

Rhockens (talk) 12:55, 30 May 2019 (EDT)
This is the second mention of history (first is in Basics). Author only mentions ability to scroll through prior commands using keyboard up arrow/down arrow. On second reference in this section, perhaps describe history in more detail and introduce history command itself.

discussion ADVANCED-ISH chapter, Proposed Changes

+ Add the <(command) feature as an alternative to piping
+ something on Performance measurement
+ something on Security
+ considering changing the name of this chapter to Intermediate (as part of the series Beginning, Intermediate, Advanced)

--S4t4nders (talk) 18:20, 16 May 2019 (EDT)

• i understand the alternative to Piping as being added to, and not replacing.
  
• regarding something on Performance Measurement:
  

it may be useful for an introductory reader to understand what the machine is doing while its just "sitting there". and how to understand not only the names of apps running right now, but the resources those apps are consuming in terms of processor and memory, perhaps network resources being used could be surfaced here as well. i'd recommend limiting to the command line apps already on a default installation (nothing extra to be installed). this may also be useful for scripting exercises in other parts of this book to use data generated by the user's/reader's machine. [top is mentioned in the Processes chapter but not explained in detail. Rhockens (talk) 08:25, 2 June 2019 (EDT)]

• regarding something on Security
  

i'm thinking something around passwords (currently in the Quickie section of the Appendix, but could be expanded here). why passwords are needed, where they are kept, something about hashing and why it is cool in terms of basic crypto.

• regarding changing the name of the chapter from ADVANCED-ISH to INTERMEDIATE
  

again, i'm not sure we're allowed to do that. this is a suggestion i put in the Proposed Changes column because it seemed appropriate to me, for an introductory book to be divided into Beginning, Intermediate and Advanced sections within the book.

Rhockens (talk) 08:03, 31 May 2019 (EDT)
Regarding Add the <(command) feature as an alternative to piping...

I think this is introduced briefly in the section on Redirection (the fifth chapter under Commands) and illustrated with the command:

$mail joe < myfile.txt

Rhockens (talk) 08:06, 31 May 2019 (EDT)
The section on pipes introduces a number of commands -- cat, cut, sort, uniq, and grep -- but mainly to illustrate the use of pipes rather than to introduce the commands themselves. Would it be helpful if these were introduced in an earlier chapter or chapters?

Rhockens (talk) 10:10, 31 May 2019 (EDT)
In the chapter/section on command history, the notion of sharing bash history is introduced; at that point though I don't think there has been a discussion of hidden files nor of text editors; meanwhile, book suggests editing .bashrc.

discussion ADVANCED chapter, Proposed Changes

+ discuss making mention of FTP and Rsync, relatives of Telnet
+ discuss making mention of Tmux and Byobu, near Screen
+ Add a one-page quick-ref sheet to chapters on key tools
+ Add explanation on difference between $(command) and (command)
+ Remove section on 'Making Your Own Interpreter'
+ Add section on Basic System Administration. systemd (viewing/ starting/ stopping services etc). systemd journal (viewing entries/ errors). Boot times (systemd-analyze). Memory usage (free/ top). Disk usage/ mount points and options/ filetypes (fdisk/ lsblk/ mount). Networking/ connections (ip/ ping/ traceroute). Identifying listening services (ss)
+ Add section on Basic System Security. File permissions (moved from section 17) + noexec/ nosuid. SELinux/ Apparmor/ PAM (?). Firewall rules
+ consider leaving this chapter's name the way it is, Advanced (but consider changing two previous chapters to Beginning and Intermediate, to compliment this chapter)

discussion TEXT EDITORS chapter, Proposed Changes

+ choose one or two: Nano, Vim, Emacs, GEdit
+ discuss where to add 'Markdown'
+ Add a one-page quick-ref sheet to chapters on key tools

--S4t4nders (talk) 18:54, 16 May 2019 (EDT)

• this maybe as important as choosing a Unifying Project. perhaps its more important. and perhaps we should just choose ONE editor. make mention that there are always choices, many choices. but those reading intro type books can be sidelined by having to make decisions. and they often dont know enough to make a good decision. we can keep it simple for them by saying ... we're choosing to use this one, for the examples in this book, because its ubiquitous and easy. and then keep moving! and if we choose just one it can be another unifying element of the book. to be used throughout the book for every chapter and section and example and screenshot. i'm going to vote for the simplest and easiest choice of the above, Nano.
  

Rhockens (talk) 18:28, 31 May 2019 (EDT)
Perhaps introduce Nano earlier in the book (since a few examples prior to the Text Editors chapter require a text editor; e.g., to edit .bashrc). Then introduce Vim later on. Also might wish to keep either Vim or Emacs as the key bindings section of Advanced > Interactive Editing references both (although only goes into Emacs).

discussion SCRIPTING chapter, Proposed Changes

+ Add a one-page quick-ref sheet to chapters on key tools

discussion SCRIPTING LANGUAGES chapter, Proposed Changes

+ Perl (Remove), Ruby (Remove), GNUOctave (Remove)
+ Python (Add Chapter)
+ Jupyter (Add Chapter)
+ Git (Add Chapter)
+ discuss Making mention of IDEs
+ discuss Data Science Project/ Data Manipulation project for Jupyter
+ Add a one-page quick-ref sheet to chapters on key tools

Rhockens (talk) 08:14, 2 June 2019 (EDT)
In the first edition of the book the Git chapter appears in the Advanced section. Is the suggestion to add it under Scripting Languages?

Rhockens (talk) 16:22, 4 June 2019 (EDT)
Pro Git, written by Scott Chacon and Ben Straub and published by Apress, has a very well presented | introduction to GIt. It does a nice job of explaining and contextualizing concepts that may not be obvious to someone who has no prior experience with version control.

discussion APPENDICES chapter, Proposed Changes

+ discuss the merits of keeping the Command Quickie section here if we are adding Quick Ref sheets to each chapter

Quick Reference

On 5/27 on Gitter Andy wrote: We want something people can read stand-alone... choose a small set of common arguments we think is useful, and document those... our documentation should be different from the man pages

Rhockens (talk) 16:17, 4 June 2019 (EDT)
I've seen a few styles in other quick reference cards and pages:

Command name without options or arguments and very brief description; e.g.,

rmdir: remove directory

Multiple versions of the same command with individual arguments:

ls: list files

ls -l: list files, long format

ls -a: list all files, including hidden files and directories

Commands with arguments:

rm filename: remove a non-directory file

On 5/27 on Gitter Andy wrote: How shall we organize a list, which is going to cover several pages? A straightforward alphabetical listing? Organized (and perhaps grouped) by function?

Organized/grouped by function would seem most helpful to the novice and how a lot of other quick reference cards do it: e.g.,

Getting Help

man

info

Working with Files

cp

mv

rm

I assume the organization would reflect the future organization of the book. (An alphabetical index of all commands in the book would also be useful.)

See the content inventory for notes on how the commands are introduced in the first edition. I haven't made notes on every chapter yet, but I've included a list of the commands introduced in each chapter for most of them. Here are the commands as introduced in the initial chapters of the first edition:

Ch 3: date

Ch 4: echo

Ch 5: pwd, cd

Ch 6: apropos, cat, cp, info, less, ls, man, mkdir, rmdir

Ch 7: ls, tee, exec [technically a shell builtin I think]

Ch 9: sudo, su

On 5/27 on Gitter Andy wrote: I think that most, if not all, of the commands covered in the book will be in section 1 of the man pages. The rest are either system-specific (section 4, for instance) or about things such as file formats.

I agree and the manual page section number should probably be omitted from the quick reference.

On 5/27 on Gitter Andy wroteWould the page be easier to scan if the command name were the first column instead of the second?

Rhockens (talk) 16:17, 4 June 2019 (EDT)
Yes!