carpentries-incubator / gap-lesson Goto Github PK

Give an example of putting GAP code into an executable shell script, for example, as in
https://github.com/alex-konovalov/gnu/blob/master/grpconst.sh

@fmichonneau has updated the lesson template to enable support of Incubator lessons!

This update:

• Creates a top-of-page banner to indicate that this lesson is in the incubator (and not an official Carpentries lesson). This banner is in addition to the existing "lesson life cycle" banner that appears on some official Carpentries lessons (for example the geospatial lessons) to indicate whether lessons are pre-alpha, alpha, beta, or stable.

• Changes the license information to make it clear the copyright is not held by The Carpentries or any of its lesson programs.

• Replaces The Carpentries (or SWC/DC/LC) logo in the upper left hand corner of the template with The Carpentries Incubator logo.

@fmichonneau and I are happy to do the heavy lifting of bringing this template into your lesson repository (or helping you with the logistics if you'd like to try it yourself). Once this has been done, your lesson will appear on a "Community Contributed Lessons" page on The Carpentries website!

Please respond to this issue to let us know if you approve these changes. Please also indicate whether you would prefer to pull in the template update yourself, or would prefer @fmichonneau and I to take the lead on that. Looking forward to posting your lesson publically and getting the word out about this awesome resource!

Just to remind myself: promote use of IteratorOfSomething

• Fix markup of some lesson elements and check that their content matches their logical meaning (e.g. challenges which now have hidden elements)
• Check questions, objectives and key points for each episode
• Check supplementary files
• Fix timings
• Publish the lesson on Zenodo

This example may be confusing for new users, important we cover it:

gap> a:=[1,2,3];
[ 1, 2, 3 ]
gap> b:=a;
[ 1, 2, 3 ]
gap> a[3]:=35345345;
35345345
gap> a;
[ 1, 2, 35345345 ]
gap> b;
[ 1, 2, 35345345 ]

This part of the lesson has very minimalistic description - at the actual lesson, that was explained and a demo was given, but certainly the text is not sufficient for the self-study.

From the Framapad at PGTC 2018 Tutorial:

If you had an issue with SetHelpViewer("browser"), you will have to specify what browser specifically you want to use (Linux users especially). So for example if you have firefox installed and want to use that the command will be SetHelpViewer("firefox");.

All browser names should not be capitalised. (If you're unsure, check the help page for SetHelpViewer, it gives you nearly all options, but does not mention that there is no default browser for Linux).

There are some comments under PR #13 by @ChrisJefferson - they have to be addressed.

Currently the GAP input is labeled using {.gap} but this is rather something for the future - at the moment, this is not supported (can't find the link to confirm this, but I think to make this working, one should have GAP syntax support for pandoc).

At the moment "Getting ready" requires not only just to start GAP, but also to create a directory and make it a current directory for GAP.

This requires:

• some actions with the file system, which may not be clear to the reader (especially when there were no UNIX shell lesson preceding GAP lesson)
• calling functions from the GAP command line way before we explained how to use it (case-sensitivity, tab completion, commands history are not yet explained, so that may be very painful and time consuming.

Hence we should change the "Getting Ready" part so that it is enough just to start GAP at any location for the first episode. In particular:

• it should be explained how to start it in different operating system in more details ("Run bin/gap.sh script to start GAP" in GAP installation instructions is not clear to those who had never used the terminal).
  It should be explained how to check that installation has been successful.

This will allow more smooth start of the lesson, without losing pace to solve technical problems, and making part of the audience waiting for another part of the audience.

We will need file operations later - we can explain paths and directories in the episode on functions before introducing the Read command, and then introduce LogTo in the episode on regression tests (agree with @ChrisJefferson in #14).

Before creating a file with the GAP code and trying to load it using Read, the reader should be able to create a directory and a file with the GAP code in that directory, understand the concept of the current directory, and know how specify path to a file dependently on the operating system.

ChangeDirectoryCurrent from the IO package may be used to navigate between directories without leaving GAP. This is very helpful to ensure that users of all three major OS would have the same experience.

The lesson should be updated to use this from the IO package (requires compilation, but if the setup instructions are followed, it should work). There will be no need in the IO package after gap-system/gap#364 will be implemented.

Could you add https://raw.githubusercontent.com/swcarpentry/lesson-example/gh-pages/aio.md to this repository?

$ make serve
jekyll serve
Configuration file: /tmp/gap-lesson/_config.yml
            Source: /tmp/gap-lesson
       Destination: /tmp/gap-lesson/_site
 Incremental build: disabled. Enable with --incremental
      Generating... 
  Liquid Exception: Could not find document 'aio.md' in tag 'link'. Make sure the document exists and the path is correct. in /_layouts/base.html
jekyll 3.7.3 | Error:  Could not find document 'aio.md' in tag 'link'.

Make sure the document exists and the path is correct.

make: *** [Makefile:21: serve] Error 1

Some links in the Reference and Instructor Guide seem broken:

 ● Resource: `01-command-line.html`
    Message: ‘File referenced by URL doesn't exist.’
    Found in:
    - ./gap-lesson/_site/guide/index.html
    - ./gap-lesson/_site/reference/index.html
  ● Resource: `02-some-objects.html`
    Message: ‘File referenced by URL doesn't exist.’
    Found in:
    - ./gap-lesson/_site/guide/index.html
    - ./gap-lesson/_site/reference/index.html
  ● Resource: `03-func.html`
    Message: ‘File referenced by URL doesn't exist.’
    Found in:
    - ./gap-lesson/_site/guide/index.html
    - ./gap-lesson/_site/reference/index.html
  ● Resource: `04-testing.html`
    Message: ‘File referenced by URL doesn't exist.’
    Found in:
    - ./gap-lesson/_site/guide/index.html
    - ./gap-lesson/_site/reference/index.html
  ● Resource: `05-small-groups.html`
    Message: ‘File referenced by URL doesn't exist.’
    Found in:
    - ./gap-lesson/_site/guide/index.html
    - ./gap-lesson/_site/reference/index.html
  ● Resource: `06-attributes.html`
    Message: ‘File referenced by URL doesn't exist.’
    Found in:
    - ./gap-lesson/_site/guide/index.html
    - ./gap-lesson/_site/reference/index.html
  ● Resource: `http://www.gap-system.org/Manuals/doc/ref/chap27.htmlGAPDoc`
    Message: ‘HTTP status code: 404’
    Found in:
    - ./gap-lesson/_site/discuss/index.html
  ● Resource: `http://www.gap-system.org/Manuals/doc/tut/chap3.htm`
    Message: ‘HTTP status code: 404’
    Found in:
    - ./gap-lesson/_site/reference/index.html

Move LogTo to later on, maybe in testing section.

A question that is periodically asked in Forum/Support is how to read some data files, for example, comma or space separated values. It would be useful to give some hints/pointers.

TestOneOrderVariadic should be made simpler. It is useful to introduce Info classes and variadic functions, but the code should be shortened to reduce cognitive load.

As the first Software Carpentry workshop that included GAP lesson was part of the largee event (http://www.codima.ac.uk/school2015/), this was covered by subsequent program that week. But the small groups search would fit very well into the SCSCP master-worker skeleton, so an example of parallel small group search may be nice (and it will avoid diving into OpenMath internals, not suitable for the introductory lesson).

The link to http://alex-konovalov.github.io/gap-lesson/conduct/ is broken - does that happen after #19 by @rgaiacs ?

This may be slightly hard to follow for the reader because they may not know in the beginning what a test file is. One should explain this better and add more motivation in the lesson starter. Also, instructor's guide should have a pointer to various extra options of Test.