search

carpentries-incubator / snakemake-novice-bioinformatics

Introduction to Snakemake for Bioinformatics
https://carpentries-incubator.github.io/snakemake-novice-bioinformatics
Other
17 stars 9 forks source link

Clarifying how to use the editor #52

Open tbooth opened 1 year ago

tbooth commented 1 year ago

from @tkphd

Two editors are mentioned here, but no editor is invoked in the lesson material. Throughout, when showing changes to a file, preface it with the command the instructor should use to launch the editor. Provide installation instructions or suggest a framework (like gitforwindows) that provides an editor. "Setup" is meant to be run by the learner hours or days ahead of the workshop. Any alias they set will be lost by the time they need it. Recommend editing ~/.nanorc to set appropriate flags instead, or editing ~/.bashrc to retain the alias, and revisiting this at the beginning of the lesson to make sure everyone has a consistent editing environment.

tbooth commented 1 year ago

Two editors are mentioned here, but no editor is invoked in the lesson material. Throughout, when showing changes to a file, preface it with the command the instructor should use to launch the editor.

I know this is done in the shell novice lesson, with $ nano filename being shown every time a file is edited, and nano being the prescribed editor. However, when teaching these lessons over the last two years we've instructed the learners to open the Snakefile in Gedit and keep the window open, so there is no command to run before changing a file.

I can add some more guidance to the instructor notes on choice of editor and practicalities of presenting this, but I don't think peppering these lessons with repeated instructions on how to start a text editor is helpful to anyone.

tbooth commented 1 year ago

Provide installation instructions or suggest a framework (like gitforwindows) that provides an editor.

Again, the ability to edit text files is a prerequisite to this course, and is discussed in the Carpenties shell novice lessons.

tbooth commented 1 year ago

"Setup" is meant to be run by the learner hours or days ahead of the workshop. Any alias they set will be lost by the time they need it. Recommend editing ~/.nanorc to set appropriate flags instead, or editing ~/.bashrc to retain the alias, and revisiting this at the beginning of the lesson to make sure everyone has a consistent editing environment.

Again, I think this is down to whoever is running the particular course to decide what editor environment they are happiest presenting and how much introduction it needs for their given audience. They may decide to use neither GEdit nor Nano, in which case the course shouldn't stand in their way and be over-prescriptive.

Mentioning ~/.nanorc is a good idea - I'll suggest that in place of the alias.

tbooth commented 2 months ago

Further comments were made by @cmeesters:

when introducing gedit (in the setup section), it is recommended to start the editor in the background. I noticed, myself, that you have to describe what the ampersand (&) actually does to newbies.

likewise with Nano, a number of rather "cryptic" command line flags are given and not explained.

tbooth commented 2 months ago

likewise with Nano, a number of rather "cryptic" command line flags are given and not explained.

I don't understand this comment. The text explains that these flags in nano select the equivalent settings described above for GEdit, and then for good measure I give the settings in more legible .nanorc format. At this point I could digress into a detailed discussion of editor configuration, but the point is to give the learner a setup that will work. So I don't see what I should add here that will actually be useful.

tbooth commented 2 months ago

when introducing gedit (in the setup section), it is recommended to start the editor in the background. I noticed, myself, that you have to describe what the ampersand (&) actually does to newbies.

Actually it's more complex that this, because gedit has a habit of printing sporadic warnings into the terminal which is annoying and confusing. So I'm going to remove the recommendation to use gedit & and add a callout to explain further.

cmeesters commented 2 months ago

I don't understand this comment. (about nano)

Well, nano -wiSOE -T 4 -Y python Snakefile is preceded with "The following command will start editing with the suggested settings ... ". I merely think this does not really elucidate matters for newbies.

Essentially, all editors with a steep learning curve (nano, vi, emacs, ...) have their quirks and will lead to issues with some participants in the classrooms. Choosing gedit and nano (as nano is not that strange as vi and emacs are) is an attempt to reduce such issues. However, when people start not knowing what ls is and what flags are, -wiSOE -T 4 -Y is mysterious gibberish. It is challenging to navigate around this issue, I know. You might as well leave it as is - perhaps someone has an idea at a later time.

tbooth commented 2 months ago

So this gets to the fundamental question: is this course aimed at Linux newbies or is it aimed at people with shell scripting experience. I wrote it for the latter, but you (and previously @tkphd) are saying it should be modified to suit the former.

"when people start not knowing what ls is and what flags are" ... they are in the wrong place. This is not (yet) the course for them. There are many many great resources for people to learn these things, not least the Carpentries lessons introducing Linux. I do not propose to re-invent that wheel by providing introductory Linux exposition within this course.