asker-tool 2.1.2

data/README.md

@@ -0,0 +1,53 @@
+# ASKER (version 2.1)
+
+Generate a lot of questions from an _input file_ base on your own _definitions_.
+
+---
+# Description
+
+ASKER helps trainers to create a huge amount of questions, from a definitions (_conceptual entities_) input file.
+
+Steps:
+
+1. Create an input file with your definitions (_conceptual entities_).
+1. Run _asker_ and get the results into `output` directory.
+
+Features:
+
+* Free Software [LICENSE](https://github.com/dvarrui/asker/blob/devel/LICENSE).
+* Multiplatform.
+* Input file formats: HAML, XML.
+* Output file format: GIFT (Moodle cuestionairs).
+* Ruby program.
+
+---
+# Usage
+
+To execute ASKER, we use `asker` command, with a path to an input file as argument. For example, to run our `jedi.haml` input file example, we do:
+
+```
+asker docs/examples/starwars/jedi.haml
+```
+
+* The program generates your output files into the `output` directory by default.
+* In this example, we use a demo input definition file `docs/examples/starwars/jedi.haml`, that contains conceptual entities about _"Jedi's"_ context.
+* [Example input files](https://github.com/dvarrui/asker/blob/devel/docs/examples).
+* More examples at `github/dvarrui/asker-inputs` repository.
+
+---
+# Documentation
+
+* [Installation](https://github.com/dvarrui/asker/blob/devel/docs/install/README.md)
+    1. Install Ruby on your system.
+    2. `gem install asker-tool`
+* [Inputs](https://github.com/dvarrui/asker/blob/devel/docs/inputs/README.md)
+* [Commands](https://github.com/dvarrui/asker/blob/devel/docs/commands.md)
+* [Contributions](https://github.com/dvarrui/asker/blob/devel/docs/contributions.md)
+* [Base idea](https://github.com/dvarrui/asker/blob/devel/docs/idea.md)
+* [History](https://github.com/dvarrui/asker/blob/devel/docs/history.md)
+
+---
+# Contact
+
+* **Email**: `teuton.software@protonmail.com`
+* **Twitter**: `@SoftwareTeuton`

data/bin/asker

@@ -0,0 +1,4 @@
+#!/usr/bin/ruby
+require 'asker/cli'
+# Start Asker command line interface
+CLI.start(ARGV)

data/docs/changelog/v2.1.md

@@ -0,0 +1,99 @@
+
+# version 2.1
+
+Things/ideas to do for 2.1 Asker version.
+
+## GUI
+
+Create a graphic fron end to execute asker and edit input files.
+
+## Videos
+
+* Documentation: Revise documentation
+* Perhaps, videos on youtube explaining all this: (1) Get documentation, (2) Installation, (3) Consult demo input, (4) Create our input file usign def, (5) Add tables to our input file.
+
+## Languages
+
+* Language support: French, Dutch, Catalán and Esperanto.
+
+---
+
+## Better table keyword
+
+* Process tables definitions with more than 2 fields.
+
+## info keyword
+
+* Add new keyword called info. Example:
+```
+%map{ :lang => 'en', :context => 'rock, bands', :version => '1'}
+  %info Generic text about music, rock, bands, concerts, etc.
+  %info more...
+```
+* When AI create new question may use (randomly) info text to be included into it. Example:
+```
+Rock music style was created for ....
+
+Definition of [*]: Australian rock band formed by Scottish-born brothers Malcolm and Angus Young.
+
+Select right option:
+a. Led Zepellin
+b. Beatles
+c. ACDC
+d. None
+```
+
+## Code inputs
+
+Let's take a look at the [issues](https://github.com/dvarrui/asker/issues)
+
+Actually we are experimenting with new keywords: code, type, path, features.
+
+Example:
+
+```
+  %code
+    %type ruby
+    %path files/string1.rb
+    %features
+      %row Muestra en pantalla "Hola Mundo!"
+```
+
+Where `type` could be: ruby, python or sql.
+
+> Also bash, math, crontab, fstab, etc.
+
+## More output formats
+
+* Images
+    * Questions with images, sounds or other files embebed.
+    * Embeded images into question texts
+* Work on other export formats (Perhaps Moodle format)
+
+## Etc
+
+* Texts
+    * Concept name drop and fill...
+* Question types
+    * crossword
+    * type hangmann
+* Dictionary
+    * Diccionario de sinónimos, antónimos
+    * Learn about the words or better download dictonary from RAE?
+
+## Quizzer
+
+* Export questions to YAML format then use them with app quizzer to create PDF exams.
+* For example:
+```
+# Create output/funiture-questions.yaml
+asker en/home/furniture.haml
+
+# Create 3 PDF exams with 10 questions every one
+quizzer 3x10 output/furniture-questions.yaml  
+```
+
+## Develop more Tests
+
+* minitest for every class into lib directory
+* Apply rubocop rules to all them.

data/docs/commands.md

@@ -0,0 +1,15 @@
+
+[<<back](../README.md)
+
+# Commands
+
+By now, ASKER run as CLI command.
+
+| Command                 | Description                     |
+| ----------------------- | ------------------------------- |
+| asker                   | Show available functions        |
+| asker version           | Show current version            |
+| asker PATH/TO/INPUTFILE | Create questions for input file |
+| asker file PATH/TO/INPUTFILE | File keyword is optional   |
+| asker check PATH/TO/INPUTFILE | Check HAML file syntax    |
+| asker init              | Create default config.ini file  |

data/docs/contributions.md

@@ -0,0 +1,18 @@
+
+[<< back](../README.md)
+
+# Contributions
+
+If you want to contribute:
+* Talk about this tool with your colleagues.
+* Use this tool.
+* Report bugs.
+* Report us, your ideas for new features.
+* Share with us your own input files.
+* And if you love `ruby`, you can develop with us or work on the issues.
+
+---
+# Contact
+
+* **Email**: `teuton.software@protonmail.com`
+* **Twitter**: `@SoftwareTeuton`

data/docs/history.md

@@ -0,0 +1,40 @@
+
+[<< back](../README.md)
+
+# History
+
+> Some time ago, this project was called "Darts of teacher". We renamed it because "darts" was used. Now, it's called ASKER.
+
+## The problem
+
+Working as a teacher, one of the most boring taks is check the same exercises
+again and again, for every student, and every year.
+
+The tests questions allow us to make activities that are automaticaly checked/resolved by software tools, as for example, Moodle cuestionairs.
+In this case, the teacher will have enough time to waste others tasks, as:
+* Analise results with detail.
+* Read information about others materials.
+* Test new aplications.
+* Develop new tools.
+* Etc.
+
+In resume, applying more new knowledge to improve his work,
+trying new ways of doing his job better, finding or redefining activities or lessons contents. Just finding a better way of teaching. And an easier way of learning for the students.
+
+## Need a new tool
+
+I decide (about 2013) start writing this tool to help me
+with the process of making test questions from input definition files.
+
+With this tool, I only waste time making this input file.
+As a teacher I have this knowledge into my mind, so it will be easy.
+It's the resume, definitions or conceptual entities of the unit
+I'm teaching.
+
+I've been using this tools several years/courses, teaching computer
+science. I have a lot of work to improve it and new features to add.
+It's usefull (for me at least), and hope It'll be for you too.
+
+;-)
+
+David Vargas

data/docs/idea.md

@@ -0,0 +1,44 @@
+
+[<< back](../README.md)
+
+# Basics
+
+> **Disclaimber**
+>
+> I work as a teacher, and I try to do the best I know. But I'm really a programmer. I studied Computer Science at *ULPGC*.
+>
+> The 90% of what I've learned, I must thank to *Open Source* community.
+The other 10%, It's luck and time wasted working.
+
+## Open vs closed problems
+
+The big problem with test questions are that only are usefull to evaluate
+measurable features. So it is useless when we try measure abstract
+features or measure open problems. But I think, we can do it with another approach.
+
+I mean, if we get an open and abstract problem, their resolution will consist on several steps or measurable milestones. So we can transform an open problem, into a lot of closed mini-problems. And we have to focus on the measurable aspects.
+
+Besides, if I *"bomb"* the student with a huge amount of diferent test questions about one concept, probably I could be near of knowing and measuring, the student asimilation of that kownledge.
+
+## Making Questions
+
+The task of creating test questions to solve the previous problem, becames another different problem to be solved. When I had to make manually this test questions, it took me a lot of time. And I need a lot.
+
+And usually when I was making the question number 42, I realise that I forgot the content of the 41 previous. I'm loosing time and it's slow.
+
+## Work once
+
+Finally, I decide to write this tool that help me with the process of
+making test questions from input definition files.
+
+So I only waste time making an input file. But as a teacher I have this
+into my mind and it must be a simple job. Because the inpu file it's just a resumed concepts list about the unit I'm teaching.
+
+I've been using this tools several years/courses, teaching computer
+science. I have a lot of functions to be improved and features to be added.
+But for now, It's usefull (for me at least), and hope it will be for you too.
+;-)
+
+_Thanks!_
+
+David Vargas

data/docs/inputs/README.md

@@ -0,0 +1,39 @@
+
+[<< back](../../README.md)
+
+# Inputs
+
+---
+
+## Text plain editor
+
+How to build our asker input files?
+
+Open a plain text editor and start writting definitions.
+* [Learn about concepts](concepts.md)
+* [Learn about tables](tables.md)
+* [Learn about templates](templates.md)
+* [Learn about code](code.md)
+
+---
+
+## Web editor (On development)
+
+Asker has a web editor to help building our asker input files.
+By now only read, do not write. Sorry! Still is on development.
+
+Looks like this:
+
+![](../images/web-editor.png)
+
+To launch web editor:
+1. `asker editor`
+1. Open web browser and goto URL `localhost:4567`.
+
+---
+
+## More examples
+
+Download our git repository with a lot of examples:
+* `asker donwnload` or
+* `git clone https://github.com/dvarrui/asker-inputs.git`

data/docs/inputs/code.md

@@ -0,0 +1,69 @@
+
+[<< back](README.md)
+
+# Learn code
+
+Now, we are going to learn experimental keywords:
+* code
+
+---
+
+# Concept limits
+
+We have learn about using: map, concept, names, tags, def, table and template keywords. All them are usefull to define concepts.
+
+Commonly we use natural lenguages (en, es, fr, de, etc) to talk about them and Asker DSL is a simpler and structured language version. All languages are similar (verbs, subjects, adjective, etc.), but have their own rules.
+A poem, for example is writting using those rules.
+
+Exists others kind of human creations, that use other definition languages.
+For example, programming languages, file configurations, drawing language, math language, etc,
+
+So we had to create new DSL keyword called `code`.
+
+Let's see.
+
+---
+# Code
+
+## Example
+
+Example, using `code`keyword to define a python program from `files/string.py`file:
+
+```
+%map{ :version => '1', :lang => 'en', :context=>'python, programming, language' }
+
+  %code
+    %type python
+    %path files/string.py
+```
+
+| Param | Description               |
+| ----- | ------------------------- |
+| code  | Define a new code concept |
+| type  | Content type              |
+| path  | Path to content file |
+
+> Experimental type values: python, ruby, javascript, sql
+
+## Full map
+
+Example, using `code`keyword to define several python programs from `files/` folder:
+
+```
+%map{ :version => '1', :lang => 'en', :context=>'python, programming, language' }
+
+  %code
+    %type python
+    %path files/string.py
+
+  %code
+    %type python
+    %path files/array.py
+
+  %code
+    %type python
+    %path files/iterator.py
+```
+
+Example:
+* [python](../examples/code)

data/docs/inputs/concepts.md

@@ -0,0 +1,142 @@
+
+[<< back](README.md)
+
+# Learn basics
+
+To know how to build our asker input files, we need to learn
+main keywords:
+* map
+* concept
+* names
+* tags
+* def
+
+Let's start!.
+
+---
+
+# Text plain editor
+
+* Create a text file, called for example: `demo/furniture.haml`.
+* **map**: Once, at first line, we write keyword `map`. Example:
+
+```ruby
+%map{ :lang => 'en', :context => 'furniture, home', :version => '1'}
+```
+
+| Attribute | Description                                    |
+| --------- | ---------------------------------------------- |
+| lang      | Output texts will be created in English. Valid values: en, es |
+| context   | Comma separated labels that define map content |
+| version   | Input file format version. Valid value: 1 |
+
+This input file will contain concepts about furniture context.
+Use diferents input files to define diferents contexts.
+
+> Use separated contexts is good idea. Sometimes, diferents concept from diferents contexts has the same `names` value. For example:
+> * free as free of charge, costless.
+> * free as in freedom.
+
+* **concept, names, tags**: So we define our first concept:
+
+```
+  %concept
+    %names chair
+    %tags single, seat, leg, backrest
+```
+
+| Param | Description                     |
+| ----- | ------------------------------- |
+| names | Comma separated concept's names |
+| tags  | Comma separated tags that help to identify this concept |
+
+* **def**: Use def keyword to add concept meaning. The `def` content must uniquely identifies our concept. You can use `def` more than once.
+
+```
+  %concept
+    %names chair
+    %tags single, seat, leg, backrest
+    %def Single seat with legs and backrest
+    %def Furniture that is placed around the table to sit
+```
+
+At this time, we may generate questions with:
+
+```bash
+asker demo/furniture.haml
+```
+
+---
+
+# Formats
+
+HAML is a special format. It's necesary write exactly:
+* 0 spaces before map.
+* 2 spaces before concept.
+* 4 spaces before names, tags and def.
+
+It's posible write the same using XML format instead. Take a look:
+
+```xml
+<map lang='en' context='furniture, home' version='1'>
+  <concept>
+    <names>chair</names>
+    <tags>single, seat, leg, backrest</tags>
+    <def>Single seat with legs and backrest</def>
+    <def>Furniture that is placed around the table to sit</def>
+  </concept>
+</map>
+```
+
+Notice that `demo/furniture.haml` is HAML file and  `demo/furniture.xml` a XML file. Both are valid.
+
+> HAML format files are the same as XML format files.
+Internaly HAML files are translated automaticaly to an XML equivalent.
+>
+> Why write into HAML instead of XML? HAML It's easier (for me).
+You don't have to close every tag, only be carefuly with indentation.
+>
+> If you prefer, you could write your input files using XML.
+
+---
+
+# Adding images
+
+Example:
+![](https://www.portobellostreet.es/imagenes_muebles/Muebles-Silla-colonial-Fusta-Bora-Bora.jpg)
+
+**def** can be used with image URL. So we have to find an image that uniquely identifies our concept and write this:
+
+```
+    %def{:type => 'image_url'}https://www.portobellostreet.es/imagenes_muebles/Muebles-Silla-colonial-Fusta-Bora-Bora.jpg
+```
+
+| Attribute | Description  |
+| --------- | ------------ |
+| type      | Content type |
+
+---
+
+# Increase questions number
+
+Adding more concepts will increase questions number generated by ASKER:
+
+```
+  %concept
+    %names couch
+    %tags furniture, seat, two, threee, people, bench, armrest
+
+  %concept
+    %names table
+    %tags furniture, flat, top, leg, surface, work, eat
+
+  %concept
+    %names bed
+    %tags furniture, place, sleep, relax
+```
+
+Examples:
+* [furniture.haml](../examples/home/furniture.haml)
+* [furniture.xml](../examples/home/xml/furniture.xml)
+
+[>> Learn about tables](tables.md)