asciidoctor-moodle 1.0.0.dev

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7cda5ba859d51bb5e75a9e32456dbeb68f0bc692981cd87ceffa38a2e1416592
+  data.tar.gz: 99805f9c1e42aabf270a9259b0b82956cf90688065980f0b1173c81f7a769db8
+SHA512:
+  metadata.gz: ceb40738246d082023478f9c41a679a71d7443a24e1b0bb9ab298eb3fb2b2657d253b7eae3817dcc73bea1afd66735d7065827793a3f1ae2df202fe934d8a3f9
+  data.tar.gz: 70a2864be96d9f85f8ea51ee0b03899a7860f3c92e237a9a83b2a6458b5867a975efdbe5e83dacf9d95a6344288162ab74bb73fe6030db9634f9ecbc5f237748

data/README.adoc

@@ -0,0 +1,412 @@
+[source,asciidoc]
+
+= Asciidoctor Moodle-Question
+ifndef::imagesdir[:imagesdir: images]
+
+:description: README for the Asciidoctor Moodle-Question extension for Asciidoctor, based on Asciidoctor-Question.
+:version: 0.0.1
+
+image:https://img.shields.io/badge/license-MIT-blue.svg[MIT License, link=#copyright]
+
+Asciidoctor Moodle-Question is a set of Asciidoctor extensions that allows you to add questions as multiple choice and gap text and convert them to Moodle XML format. The questions are defined using plain text in your AsciiDoc document.
+
+== Creating a Question
+
+A question is written inside a literal block, which needs at least two attributes.
+
+.Anatomy of a question
+----
+[question, question-type] // <1> <2>
+....                      // <3>
+Question in appropriate syntax
+....
+----
+<1> The first positional attribute in the attribute list specifies that this block is a question.
+<2> The second positional attribute defines the type of this question (mc or gap)
+<3> Place the attribute list directly on top of the delimited literal block (+....+). You can also use an example (+====+) or open block (`--`) as an alternative.
+
+The following question types are available:
+
+I used HTML <p> to format the output in Moodle to fit the tabular's case.
+
+.Resume
+[cols="2,3a,3a",options="header"]
+|===
+|Question type |Input |Output
+
+|mc
+|[source]
+----
+[question, mc]
+....
+Which of these are capitals ?
+
+- [X] Romes
+- [ ] Sydney
+- [X] Paris
+....
+----
+|image::mc.png[]
+
+|gap
+|[source]
+----
+[question, gap]
+....
+<p> If debugging is the process of removing </p>
+<p> software bugs, then programming must be </p>
+<p> the process of __putting them in__. </p>
+- Edsger Dijkstra
+....
+----
+|image::gap.png[]
+
+
+|tf
+|[source]
+----
+[question, TF, True]
+....
+<p> Donald Knuth said : </p>
+<p> "Premature optimization is the 
+root of all evil." </p>
+....
+----
+|image::tf.png[]
+
+|matching
+|[source]
+----
+[question, matching, 
+wrote the first computer programme in the world,
+decrypted Enigma machine's messages, 
+invented the merge sort algorithm]
+....
+Match each author with his contribution ?
+
+- Ada Lovelace :
+
+- Alan Turing :
+....
+----
+|image::match.png[]
+
+|cmc
+|[source]
+----
+[question, CMC, Merge sort algorithm, Bombe]
+====
+John von Neumann's invented
+
+* Merge sort algorithm
+* Quicksort algorithm
+* ShellSort algorithm
+
+<p> 
+Enigma's message machine  was decrypted by
+</p>
+
+- Bombe
+- Decryptma
+- Decrypte's machine
+====
+----
+|image::cmc.png[]
+
+|ordering
+|[source]
+----
+[question, ordering]
+....
+Arrange the layers with the deepest at the bottom:
+
+* VM
+* OS
+* Material
+....
+----
+|image::order.png[]
+
+|ddt
+|[source]
+----
+[question, ddt]
+....
+“Computers are good at *following instructions*,
+ but not at *reading your mind*.” 
+– Donald Knuth, 
+the “father of analysis of algorithms”
+....
+----
+|image::ddt.png[]
+
+|short
+|[source]
+----
+[question, short, Paris, case=case]
+....
+What city is the capital of France ?
+....
+----
+|image::short.png[]
+
+
+
+|num
+|[source]
+----
+[question, num, unit="cm=1,dm=0.1",tolerance=1, ans=4]
+====
+2cm + 2cm =
+====
+----
+|image::numerical.png[]
+
+|mw
+|[source]
+----
+[question, mw]
+....
+“Computers are good at *following instructions*, but not at *reading your mind*.” 
+– Donald Knuth, the “father of analysis of algorithms”
+....
+----
+|image::mw.png[]
+
+
+
+
+|===
+
+=== Generating a Question Document from a Terminal
+
+You can load Asciidoctor question in a terminal using the -r (require) and -b (backend) flags.
+[source]
+----
+asciidoctor -r asciidoctor-moodle -b moodle sample.adoc
+
+----
+
+
+=== Details format
+
+==== +++<u> MC (multiple choice question) : </u>+++ 
+[source]
+----
+[question, mc|MC, shuffle=shuffle] //Used of the named attributes.
+----
+[source]
+----
+[question, mc|MC, shuffle] //Or just set the third attribute.
+----
+ If you want the answers to be shuffle for each try. You can either use 'MC' or 'mc'.
+
+[source]
+----
+- [X] correct1
+- [*] correct2
+- [ ] false
+----
+
+You can either tick the correct(s) answer(s) with X or *.
+
+The question is on 1 point, the point you receive for a good answer is 1/nbCorrectAnswersPossibles.
+
+WARNING: You need space bewteen [ ] if it's false.
+
+==== +++<u>Gap (gap fill question) </u>+++
+
+You gap your text with :
+[source]
+----
+The gap is __here__
+----
+
+You gain 1 point for each gap correctly fill.
+
+==== +++<u>TF (true or false question) </u>+++
+
+You can only write one question by question's block. One point for each question's block.
+
+[cols="2a,2a",options="header"]
+|===
+|Good
+|Bad
+|
+[source]
+----
+[question, TF, true]
+....
+Question to which correct answer is true
+....
+
+[question, TF, false]
+....
+Question to which correct answer is false
+....
+----
+|
+[source]
+----
+[question, TF, true, false]
+....
+Question to which correct answer is true
+
+Question to which correct answer is false
+....
+----
+|===
+
+
+==== +++<u>Matching (matching question)</u>+++
+
+The matching question is based on a pool of questions/text and a pool of answers.
+
+The pool of answers is shared by all the questions/text.
+
+Each questions is linked to a correct answer.
+
+It's represented as a dropdown menu in-line in the text.
+
+[source]
+----
+[question, matching, Answer1, Answer2, Answer3]
+....
+General text need.
+
+- Sentence1 :
+
+- Sentence2 :
+....
+----
+In this exemple the first sentence (Sentence1) match the first argument (Answer1) after 'matching'.
+
+The second second sentence (Sentence2) match the second argument (Answer2) after 'matching'.
+
+Answer3 isn't linked to any sentence but it will still be part of the pool of possible answers. 
+
+TIP: You can use either * or - for listing the sentences.
+
+WARNING: Depending on your Moodle's version you will need at least 2 questions and 3 answers or one answer for each question if there is more than 2 questions, to be imported correctly.
+
+
+
+==== +++<u>CMC (cloze mutliple choice)</u>+++
+Unlike matching questions, each CMC question has it own pool of answers. 
+
+Each questions is linked to a correct answer.
+
+It's represented as a dropdown menu in-line in the text.
+
+You can use either a delimiter or a block list format to write the possible answers.
+
+[cols="2a,2a",options="header"]
+|===
+|List
+|Delimiter
+|
+[source]
+----
+
+[question, CMC, Correct1, Correct2]
+====
+
+Question 1
+
+* False1
+* AlsoFalse1
+* Correct1
+
+Question 2
+
+- Correct2
+- False2
+- AlsoFalse2
+
+====
+----
+|
+[source]
+--
+[question, CMC, Correct1, Correct2]
+====
+
+Question 1
+
+----
+* False1
+* AlsoFalse1
+* Correct1
+----
+Question 2
+
+----
+- Correct2
+- False2
+- AlsoFalse2
+----
+====
+--
+|===
+
+TIP: You can use either * or - to enumerate the answers, whether you are using a List or a delimiter. 
+
+WARNING: For delimiter of a list you can only use ---- or ====, -- won't work. 
+
+WARNING: If you don't have a correct answer for each question, Moodle won't accept your file. 
+
+
+==== +++<u>Ordering</u>+++
+
+You need to list the items in the same order as the correct answer. Moodle will shuffle them.
+
+TIP: You can use either * or - for listing the sentences.
+
+WARNING: Depending on your version of Moodle, you will need at least 2 or 3 items in the list for it to be imported correctly.
+
+==== +++<u>DDT (drag and drop into text) and MW (missing Words)</u>+++
+
+Simply enclose the portion of the text you with to label with asterisks (*).
+
+You can't have more draggable texts (possible answers) than gaps.
+
+WARNING: The text you enclose needs to be on the same line to be imported correctly.
+
+[cols="2a,2a",options="header"]
+|===
+|Good
+|Bad
+|
+[source]
+----
+[question, ddt]
+....
+“Computers are good at *following instructions*, 
+but not at *reading your mind*.” 
+– Donald Knuth, the “father of analysis of algorithms”
+....
+----
+|
+[source]
+--
+[question, ddt]
+....
+“Computers are good at *following 
+instructions,* but not at*reading *your* mind.” 
+– Donald Knuth, the “father of analysis of algorithms”
+....
+--
+|===
+
+==== +++<u>Short (answer)</u>+++
+You can either tag with "Short" or "short".
+
+==== +++<u>Num (Numerical)</u>+++
+You can either tag with "num" or "Num".
+
+If the tolerance is 1 and the answer is 4, then [3, 5] is an interval for a possible answer.
+
+If a student writes the correct answer without the correct unit, they will lose half of the marks.
+
+WARNING: Use coma (,) to separate units, and the dot (.) for decimal.
+

data/asciidoctor-moodle.gemspec

@@ -0,0 +1,36 @@
+begin
+  require_relative 'lib/asciidoctor-moodle/version'
+rescue LoadError
+  require 'asciidoctor-moodle/version'
+end
+
+Gem::Specification.new do |s|
+  s.name = 'asciidoctor-moodle'
+  s.version = Asciidoctor::Moodle::VERSION
+  s.summary = 'Converts AsciiDoc documents to Moodle XML'
+  s.description = 'An Asciidoctor converter that converts AsciiDoc to Moodle XML documents'
+  s.authors = ['Gerson Sunyé', 'Robin Gloaguen']
+  s.email = ['gerson.sunye@gmail.com','robin.gloaguen@hotmail.fr']
+  s.homepage = 'https://github.com/'
+  s.license = 'MIT'
+  s.required_ruby_version = '>= 3.0.0'
+  s.metadata = {
+    'bug_tracker_uri' => 'https://github.com/asciidoctor/asciidoctor-docbook45/issues',
+    'changelog_uri' => 'https://github.com/asciidoctor/asciidoctor-docbook45/blob/master/CHANGELOG.adoc',
+    'mailing_list_uri' => 'http://discuss.asciidoctor.org',
+    'source_code_uri' => 'https://github.com/asciidoctor/asciidoctor-docbook45'
+  }
+
+  # NOTE the logic to build the list of files is designed to produce a usable package even when the git command is not available
+  begin
+    files = (result = `git ls-files -z`.split ?\0).empty? ? Dir['**/*'] : result
+  rescue
+    files = Dir['**/*']
+  end
+  s.files = files.grep %r/^(?:lib\/.+|LICENSE|(?:CHANGELOG|README)\.adoc|\.yardopts|#{s.name}\.gemspec)$/
+  s.require_paths = ['lib']
+
+  s.add_runtime_dependency 'asciidoctor', '>= 2.0.0'
+  s.add_development_dependency 'rake', '~> 12.3.0'
+  s.add_development_dependency 'rspec', '~> 3.8.0'
+end

data/lib/asciidoctor-moodle/cloze_mc/extension.rb

@@ -0,0 +1,134 @@
+require_relative '../extensions'
+
+
+module Asciidoctor
+  module Question
+
+    class ClozeMCBlockProcessor < Extensions::BaseProcessor
+
+      def process(parent, source, tag)
+        
+        docName = parent.attributes['docname']
+        id = tag[:id]
+        size = tag.size
+        answers = Array.new 
+        stringSource= Array.new
+        question = Array.new
+        source.lines.each { |line| stringSource.push line}
+        tag.each { |key, val| answers.push val if key.class==Integer && key>2 && key< size-3} #Récupère les réponses en tag
+       
+        new_parent = Asciidoctor::Block.new parent, :open, {:attributes => {'id' => "#{docName}_question_mc_#{id}"}}
+        blocks = Array.new
+        reader = Asciidoctor::Reader.new(stringSource)
+        answers_block = Asciidoctor::Parser.next_block reader, new_parent 
+
+        #Get the answers from the reader to put them in the tabular 'blocks'
+        while answers_block != nil 
+          blocks.push answers_block
+          answers_block = Asciidoctor::Parser.next_block reader, new_parent 
+        end
+        
+        for i in 0..(blocks.size-1)
+          if blocks[i].class==Asciidoctor::List #Using list bloc
+            ans=""
+            blocks[i].items.each do |item| 
+              ans << item.text
+              ans << "\n"
+            end
+            reader = Asciidoctor::Reader.new(ans)
+            new_block = Asciidoctor::Parser.next_block reader, new_parent 
+            new_block.lines = prepare_answer_lines(answers[(i/2)],  new_block.content)
+            blocks[i] = new_block 
+          else      #Using delimitier
+            next if i % 2 == 0 #There is 1 question follow by 1 answer etc...
+            blocks[i].lines =  prepare_answer_lines(answers[(i/2)],  blocks[i].content)
+          end
+        end
+
+        blocks = prepare_question_lines(blocks,docName,id)
+        new_parent = Asciidoctor::Block.new parent, :open, {:attributes => {'id' => "#{docName}_question_#{id}_mc"}}
+     
+        
+
+        finalstring = ""
+        blocks.each do |bloc|           
+          finalstring << bloc.lines.join("\n")
+        end 
+       
+        reader = Asciidoctor::Reader.new(finalstring)
+        loop do
+          block = Asciidoctor::Parser.next_block reader, new_parent 
+          break if block.nil? 
+          new_parent.blocks.push block
+        end
+        
+        new_parent 
+      end
+
+      def prepare_answer_lines(answer, answerBloc)
+          puts answer 
+      end
+
+    end
+
+    class MOODLEClozeMCBlockProcessor < ClozeMCBlockProcessor
+      
+      def prepare_answer_lines(answer, stringBlock)
+        answer = answer.chomp  # erase ending \n         
+        preAns = "+++ {1:MCS:"
+        
+        postAns = "}+++"
+       
+        stringBlock = stringBlock.each_line.map { |line| line.sub(/(^-|^\*) /, "") }.join 
+        
+        stringBlock = stringBlock.each_line.map do |line|
+        
+          line = line.chomp  
+          if line == answer
+            "~=#{line}"      
+          else
+            "~#{line}"       
+          end
+        end.join(" ")        
+      
+        stringBlock.slice!(0) 
+        stringBlock = "#{preAns}#{stringBlock}#{postAns}"
+        [stringBlock]
+      
+      end
+        
+     
+      def prepare_question_lines(blocks, docName,id)
+      
+        preQuest = " <question type=\"cloze\">
+         <name>
+            <text> #{docName}_question_#{id}_clozemc </text>
+         </name>
+          <questiontext format=\"html\">
+            <text><![CDATA[<p>" 
+        postQuest = " </p>]]></text>
+    </questiontext>
+    <generalfeedback format=\"html\">
+      <text></text>
+    </generalfeedback>
+    <penalty>0.3333333</penalty>
+    <hidden>0</hidden>
+    <idnumber></idnumber>
+  </question>"
+        size = (blocks.size) -1
+
+        
+        
+        blocks[0].lines.prepend("+++")
+        blocks[0].lines.prepend(preQuest)
+        blocks[0].lines.prepend("+++")
+      
+        blocks[size].lines.push("+++")
+        blocks[size].lines.push(postQuest)
+        blocks[size].lines.push("+++")
+        
+        blocks
+      end
+    end
+  end
+end