From andyo at oreilly.com Wed Apr 19 05:02:46 2017 From: andyo at oreilly.com (Andy Oram) Date: Wed, 19 Apr 2017 08:02:46 -0400 Subject: [FM Discuss] Proposed update to Introduction to the Command Line Message-ID: FLOSS Manuals ran a sprint together with the Free Software Foundation more than 10 years ago to create this book. It proved to be popular, and it deserves an update. A new source of readership may come from recent support for GNU-style tools added by Microsoft to Windows ( https://blogs.msdn.microsoft.com/commandline/learn-about-bash-on-windows-subsystem-for-linux/ ). I coordinate the writing when this book was created, and am trying to gather contributors for the update. I'm in touch with the FSF to recruit contributors among their base. I hope FLOSS Manuals supporters can look for contributors as well. The process for putting out a new official version is unclear. Someone is responsible for approving updates and moving them from the Write section of the seat to the released version of the book. How would members of this list suggest doing that? I have been collecting ideas for the update. My current list follows and all suggestions are welcome. Andy --- Motivate the reader by describing common tasks and applying command-line tools to solving these tasks. Remove material to make room for any new material we add. The current lenght is good--not too intimidating--and we should not give in to bloat. Try to find a unifying project, such as collaborative document or web page editing. This project could involve Git and Markdown. Perhaps HTML is too complex for this book. JSON is also complex, but understandable with syntax highlighting (coloring) in tools such as vim and Emacs. What do non-profits need? They can benefit especially from free software and often have goals aligned with the ideals of free software. Expand our vision. The book already goes beyond the command line to introduce comprehensive tools such as vi, as well as some scripting languages. In addition, consider text formats such as Markdown. Consider git for collaboration. Make a new web site as a project. Microsoft's recent support for bash and other common Unix tools should provide a new readership. grep is a good tool to introduce early--not in its full-fledged regular-expression syntax, but just as a way to search for something on your system. Difficulty: many people hardly touch plain-text files until they learn the command-line. Plain-text files are important for system configuration, which is one motivation for learning the command line and text-based tools. Some applications: vi/vim is useful for crafting a long email message before sending it. Markdown is useful for editing wikis. Adding a directory to the PATH is a common need when you install new software. There are two major levels to using a tool. One is a primitive understanding that allows for small changes. The other requires developing a mental model, which is a big job and takes time. -- Andy Oram | Editor O'Reilly Media, Inc. | 617-499-7479 | oreilly.com -------------- next part -------------- An HTML attachment was scrubbed... URL: From gpittman at iglou.com Wed Apr 19 06:39:17 2017 From: gpittman at iglou.com (Gregory Pittman) Date: Wed, 19 Apr 2017 09:39:17 -0400 Subject: [FM Discuss] Proposed update to Introduction to the Command Line In-Reply-To: References: Message-ID: On 04/19/2017 08:02 AM, Andy Oram wrote: > FLOSS Manuals ran a sprint together with the Free Software Foundation > more than 10 years ago to create this book. It proved to be popular, and > it deserves an update. A new source of readership may come from recent > support for GNU-style tools added by Microsoft to Windows > (https://blogs.msdn.microsoft.com/commandline/learn-about-bash-on-windows-subsystem-for-linux/). > > I coordinate the writing when this book was created, and am trying to > gather contributors for the update. I'm in touch with the FSF to recruit > contributors among their base. I hope FLOSS Manuals supporters can look > for contributors as well. > > The process for putting out a new official version is unclear. Someone > is responsible for approving updates and moving them from the Write > section of the seat to the released version of the book. How would > members of this list suggest doing that? > > I have been collecting ideas for the update. My current list follows and > all suggestions are welcome. > > Andy > The starting point should I think be starting with a clean slate to create an initially rough, then progressively detailed outline of what the book should cover. I've seen too many articles of various length that go into tremendous depth about a few commands, only to lose steam and fizzle. Once you have a refined outline, then go to the original book and determine how to edit/rearrange/enhance/replace what is there. What are the kinds of tasks where using the command line is useful and arguably the most efficient way of doing things? Working with files - listing, copying, moving, removing, changing permissions (and when to suspect you have a permissions problem), and batch operations. Working with file content - searching for content inside files, modifying content inside a file, and perhaps some sensible ideas about how regular expressions work. Serial operations, piping, saving to a file, appending a file, and leading to bash scripts. Various system commands, including an understanding of when/how to use su and sudo. Using ssh/sftp -- very useful in a home network. Above all, lots of examples. Online articles tend to use up a lot of space with screenshots showing the results of a command with options, but there might just be a verbal description, perhaps an "anatomy and physiology" of what the command does, and otherwise expect the user to try it out on their own system. I'm not in favor of including instructions on vi/vim -- this is a subject of its own, and there are alternative text editors that someone might choose to use, chacun ? son go?t. BTW, is the original flossmanual still around somewhere? I can't find it. Greg From M.Chesterman at mmu.ac.uk Wed Apr 19 06:42:10 2017 From: M.Chesterman at mmu.ac.uk (Mick Chesterman) Date: Wed, 19 Apr 2017 13:42:10 +0000 Subject: [FM Discuss] Proposed update to Introduction to the Command Line In-Reply-To: References: Message-ID: <724a4270a04343dbb5630c190575ede3@BFEX02.ad.mmu.ac.uk> Hi Andy , This is Mick Chesterman here aka @mickfuzz writing from my day job. I?ve just finished a batch of marking so I think I can justify sometime to work on FM issues at work for a while. Testing out the new workflow and documenting it has been on the to do list for too long so I?m happy to try this out and see if we can get the system working for you. I?m working on this right now here if anyone fancies helping! http://write.flossmanuals.net/floss-manuals-workflow/_edit/ Also, let?s test out the pdf / ebook generation of the Let?s go here http://write.flossmanuals.net/command-line/_edit/# and click on Publish Tab It generates this epub http://objavi.booktype.pro:80/data/books/commandline-en-2017.04.19-15.13.01.epub normal pdf fails but the beta render creates the following and an ability to tweak the settings. http://objavi.booktype.pro:80/data/books/commandline-en-2017.04.19-14.59.32.pdf Thanks Mick Mick Chesterman Educational Innovation and Enterprise Tutor & EdLab Project Developer Department of Childhood, Youth and Education Studies. Manchester Metropolitan University Web: http://edlab.org.uk / Twitter: @EdLabMMU Phone: 0161 2472060 Please note: My working days are Monday, Tuesday, Wednesday and Thursday From: Discuss [mailto:discuss-bounces at lists.flossmanuals.net] On Behalf Of Andy Oram Sent: 19 April 2017 13:03 To: discuss at lists.flossmanuals.net Subject: [FM Discuss] Proposed update to Introduction to the Command Line FLOSS Manuals ran a sprint together with the Free Software Foundation more than 10 years ago to create this book. It proved to be popular, and it deserves an update. A new source of readership may come from recent support for GNU-style tools added by Microsoft to Windows (https://blogs.msdn.microsoft.com/commandline/learn-about-bash-on-windows-subsystem-for-linux/). I coordinate the writing when this book was created, and am trying to gather contributors for the update. I'm in touch with the FSF to recruit contributors among their base. I hope FLOSS Manuals supporters can look for contributors as well. The process for putting out a new official version is unclear. Someone is responsible for approving updates and moving them from the Write section of the seat to the released version of the book. How would members of this list suggest doing that? I have been collecting ideas for the update. My current list follows and all suggestions are welcome. Andy --- Motivate the reader by describing common tasks and applying command-line tools to solving these tasks. Remove material to make room for any new material we add. The current lenght is good--not too intimidating--and we should not give in to bloat. Try to find a unifying project, such as collaborative document or web page editing. This project could involve Git and Markdown. Perhaps HTML is too complex for this book. JSON is also complex, but understandable with syntax highlighting (coloring) in tools such as vim and Emacs. What do non-profits need? They can benefit especially from free software and often have goals aligned with the ideals of free software. Expand our vision. The book already goes beyond the command line to introduce comprehensive tools such as vi, as well as some scripting languages. In addition, consider text formats such as Markdown. Consider git for collaboration. Make a new web site as a project. Microsoft's recent support for bash and other common Unix tools should provide a new readership. grep is a good tool to introduce early--not in its full-fledged regular-expression syntax, but just as a way to search for something on your system. Difficulty: many people hardly touch plain-text files until they learn the command-line. Plain-text files are important for system configuration, which is one motivation for learning the command line and text-based tools. Some applications: vi/vim is useful for crafting a long email message before sending it. Markdown is useful for editing wikis. Adding a directory to the PATH is a common need when you install new software. There are two major levels to using a tool. One is a primitive understanding that allows for small changes. The other requires developing a mental model, which is a big job and takes time. -- Andy Oram | Editor O'Reilly Media, Inc. | 617-499-7479 | oreilly.com "Before acting on this email or opening any attachments you should read the Manchester Metropolitan University email disclaimer available on its website http://www.mmu.ac.uk/emaildisclaimer " -------------- next part -------------- An HTML attachment was scrubbed... URL: From andyo at oreilly.com Wed Apr 19 07:19:55 2017 From: andyo at oreilly.com (Andy Oram) Date: Wed, 19 Apr 2017 10:19:55 -0400 Subject: [FM Discuss] Proposed update to Introduction to the Command Line In-Reply-To: References: Message-ID: Thanks for all the replies so far. We are starting to get a nice discussion going, and I'm happy to lead an effort to write a new outline. We need a place for that. I created a new account on http://write.flossmanuals.net/. I noticed that Groups are now available. Shall I start a group for the command-line book and invite people to it? That means we can free this general discussion list from the topic. Andy -------------- next part -------------- An HTML attachment was scrubbed... URL: From mick at flossmanuals.net Wed Apr 19 10:47:40 2017 From: mick at flossmanuals.net (Mick) Date: Wed, 19 Apr 2017 18:47:40 +0100 Subject: [FM Discuss] Proposed update to Introduction to the Command Line In-Reply-To: References: Message-ID: Group chat is not something that has been active on that site so I'd do a quick functionality test before inviting people. I'd be happy to test it with you. Thanks Mick On 19/04/17 15:19, Andy Oram wrote: > > I created a new account on http://write.flossmanuals.net/. I noticed > that Groups are now available. Shall I start a group for the > command-line book and invite people to it? That means we can free this > general discussion list from the topic. > -------------- next part -------------- An HTML attachment was scrubbed... URL: From andyo at oreilly.com Wed Apr 19 11:10:52 2017 From: andyo at oreilly.com (Andy Oram) Date: Wed, 19 Apr 2017 14:10:52 -0400 Subject: [FM Discuss] Proposed update to Introduction to the Command Line In-Reply-To: References: Message-ID: Thanks for your support, Mick. I just created the group, Update to Command Line Manual. I think each interested person has to make the choice to join the group now. Andy Andy Oram | Editor O'Reilly Media, Inc. | 617-499-7479 | oreilly.com On Wed, Apr 19, 2017 at 1:47 PM, Mick wrote: > Group chat is not something that has been active on that site so I'd do a > quick functionality test before inviting people. I'd be happy to test it > with you. > > Thanks > > Mick > > On 19/04/17 15:19, Andy Oram wrote: > > > I created a new account on http://write.flossmanuals.net/. I noticed that > Groups are now available. Shall I start a group for the command-line book > and invite people to it? That means we can free this general discussion > list from the topic. > > > > _______________________________________________ > Discuss mailing list > Discuss at lists.flossmanuals.net > http://lists.flossmanuals.net/listinfo.cgi/discuss-flossmanuals.net > > -------------- next part -------------- An HTML attachment was scrubbed... URL: From M.Chesterman at mmu.ac.uk Thu Apr 20 00:32:53 2017 From: M.Chesterman at mmu.ac.uk (Mick Chesterman) Date: Thu, 20 Apr 2017 07:32:53 +0000 Subject: [FM Discuss] Proposed update to Introduction to the Command Line In-Reply-To: References: Message-ID: <56ddfb830bd44814986e5347f060d57d@BFEX02.ad.mmu.ac.uk> That's a good point Greg, We need to create a json entry for the current manual to get it on the front page, that's quite an oversight! To try to test this workflow out - does anyone fancy trying to do that and helping to document the process? It either involves making a pull request on this file https://gitlab.com/mickfuzz/fm_en_splash/blob/master/data/book_details.json or copying the format of a book entry and emailing it to admin @ flossmanuals.net http://write.flossmanuals.net/floss-manuals-workflow/how-do-i-make-an-updated-version-of-a-manual/ There is a space for documentation of this here. http://write.flossmanuals.net/floss-manuals-workflow/how-do-i-make-an-updated-version-of-a-manual/ Thanks Mick > -----Original Message----- > > BTW, is the original flossmanual still around somewhere? I can't find it. > > Greg "Before acting on this email or opening any attachments you should read the Manchester Metropolitan University email disclaimer available on its website http://www.mmu.ac.uk/emaildisclaimer " From M.Chesterman at mmu.ac.uk Wed Apr 26 00:32:56 2017 From: M.Chesterman at mmu.ac.uk (Mick Chesterman) Date: Wed, 26 Apr 2017 07:32:56 +0000 Subject: [FM Discuss] Proposed update to Introduction to the Command Line In-Reply-To: References: <56ddfb830bd44814986e5347f060d57d@BFEX02.ad.mmu.ac.uk> Message-ID: <360822d3325b4f048fc630c3836f158f@BFEX02.ad.mmu.ac.uk> Hi Andy, I?ve started the process so you can send people to edit here. http://write.flossmanuals.net/command-line-draft-201/_info/ And I?ve started to try to document that process here. http://write.flossmanuals.net/floss-manuals-workflow/how-do-i-make-an-updated-version-of-a-manual/ I?ve done a bit more work on the ?publishing? workflow bit to try to demystify it (especially for those not familiar with git) Andy, it would be great if you could try to follow this to create an entry for the command line manual, and give feedback to the process. Thanks Mick From: Andy Oram [mailto:andyo at oreilly.com] Sent: 23 April 2017 12:03 To: Mick Chesterman Subject: Re: [FM Discuss] Proposed update to Introduction to the Command Line There's some background I don't have to understand your most recent email about a pull request, etc. (A pull request assumes you have an existing sandbox set up, right?) I'm assuming someone with all the right environment set up will do the steps to make Introduction to the Command Line editable. "Before acting on this email or opening any attachments you should read the Manchester Metropolitan University email disclaimer available on its website http://www.mmu.ac.uk/emaildisclaimer " -------------- next part -------------- An HTML attachment was scrubbed... URL: From M.Chesterman at mmu.ac.uk Wed Apr 26 00:35:16 2017 From: M.Chesterman at mmu.ac.uk (Mick Chesterman) Date: Wed, 26 Apr 2017 07:35:16 +0000 Subject: [FM Discuss] Proposed update to Introduction to the Command Line In-Reply-To: <360822d3325b4f048fc630c3836f158f@BFEX02.ad.mmu.ac.uk> References: <56ddfb830bd44814986e5347f060d57d@BFEX02.ad.mmu.ac.uk> <360822d3325b4f048fc630c3836f158f@BFEX02.ad.mmu.ac.uk> Message-ID: <4bf8181de2a44dfc9e4550223ef72d4c@BFEX02.ad.mmu.ac.uk> For info, links to the files and online version are http://flossmanuals.net/command-line http://archive.flossmanuals.net/_booki/command-line/command-line.pdf http://archive.flossmanuals.net/_booki/command-line/command-line.epub "Before acting on this email or opening any attachments you should read the Manchester Metropolitan University email disclaimer available on its website http://www.mmu.ac.uk/emaildisclaimer " -------------- next part -------------- An HTML attachment was scrubbed... URL: