home *** CD-ROM | disk | FTP | other *** search
/ BURKS 2 / BURKS_AUG97.ISO / BURKS / LANGUAGE / ADA / LOVELACE / formatmk.txt < prev    next >
Text File  |  1996-10-01  |  8KB  |  196 lines
  1. Mklesson is a program which generates a large number of HTML files from
  2. a single lesson input file, which makes tutorials MUCH easier to create and
  3. modify.
  4.  
  5. For mklesson to work its input file must be in the correct format, termed
  6. a `lesson' format (also called an `.les' format).
  7. This document describes that format.
  8. An '.les' file is in an extended form of HTML that is then transformed
  9. by mklesson into normal HTML.
  10.  
  11. To help you out, I've created a blank lesson file called 'blank.les'.
  12. Simply copy that file into lessonNUMBER.les (where NUMBER is the number
  13. of your lesson) and edit it!
  14.  
  15. All of these HTML extensions must begin at the BEGINNING of a text line
  16. and must not continue onto later lines.
  17.  
  18. The format of a comment is:
  19. <COMMENT Text>
  20.  
  21. An .les file starts with a header; here's an example of such a header:
  22.  
  23. <TUTOR NAME="Lovelace">
  24. <LESSON NUMBER=1>
  25. <AUTHOR NAME="David A. Wheeler" EMAIL="mailto:wheeler@ida.org">
  26. <AUTHOR ADDRESS="David A. Wheeler (wheeler@ida.org)">
  27.  
  28. The "author address" section is what's used at the end of a section
  29. in the "address" section, and you can use it to create a link
  30. to somewhere else (like a resume).  See my Lovelace lesson files
  31. for examples.
  32.  
  33. The lesson header is followed by a lesson body, which contains
  34. one or more sections.  Each section begins with a section command like:
  35.  
  36. <SECTION NAME="Simple Program">
  37.  
  38. This is followed by HTML text, and then optionally by a question.
  39. Here's an example of a question:
  40.  
  41. <QUESTION Type=Multiple-Choice>
  42. What is the name of the new procedure defined above?
  43. <CHOICES>
  44. <CHOICE ANS=1>Text_IO
  45. <CHOICE ANS=2>Hello
  46. <CHOICE ANS=3>Put_Line
  47. </CHOICES>
  48. <ANSWER ANS=2>
  49. <RESPONSES>
  50. <WHEN ANS=1>
  51. No, sorry. Text_IO is the name of a predefined library
  52. unit that provides us with operations to perform
  53. basic text input and output.
  54. <WHEN ANS=2>
  55. Right, `Hello' is the name of the procedure defined.
  56. <WHEN ANS=3>
  57. No, sorry. Put_Line is the name of a predefined procedure
  58. that prints text.
  59. </RESPONSES>
  60.  
  61.  
  62. The responses are optional; if a choice or the entire response section
  63. is omitted, default responses will be generated.
  64.  
  65. If there is no question, some text will be inserted
  66. that permits the user to go on to the next section.
  67.  
  68. The generator assumes that each lesson has at least 2 sections.
  69. (otherwise it's not clear if the sole section should be named the "final" one
  70. or not).
  71.  
  72. If you want to include non-HTML text from other files (say, source code),
  73. you'll probably want to use the <TEXT FILE="x"> command.
  74. This command will insert the contents of the named file at that point.
  75. It will also automatically perform the substitutions necessary to
  76. keep it as legal HTML (the characters &, <, and > aren't legal otherwise).
  77. You can also include an optional FONT=PRE inside the command,
  78. which will automatically put the entire contents in a fixed-width font.
  79. For example, if you want to include Ada source program from file hello.ads:
  80. <TEXT FONT=PRE FILE="hello.ads">
  81.  
  82. The "TEXT" command takes an optional "TEMPLATE=X" value. If the value is
  83. given, the contents of "X.head" are inserted, then the file contents
  84. (converted to HTML), then "X.tail" is inserted. This is useful, for example,
  85. if you want the text to be the default for a form to be filled out.
  86. See the Lovelace tutorial for an example of how to use this (it's used
  87. to permit users to press a button and compile programs they're viewing).
  88.  
  89. Here are a few little nitpicks and details:
  90. + The very first section (1-1) is somewhat special.  If a user decides
  91.   to skip the quiz and go to the next section, they will link to
  92.   the special file "skip1-1.html".  This file is where you can chide
  93.   the user to take the quiz, but permit them to move on.
  94.   I've included the skip1-1.html file for Lovelace; you will want to
  95.   modify it for your own program.
  96.  
  97. + The standard "template" file uses graphic files:
  98.   up.gif (point up), previous.gif (point left), next.gif (point right),
  99.   and tinyhome.gif (an icon representing your home page).
  100.   The tinyhome.gif file included in the distribution is for Lovelace;
  101.   you should replace this with an image representing your tutorial.
  102.   If you don't want graphics at all, copy the file txttemp into the
  103.   file template; txttemp contains a template that doesn't use any graphics.
  104.  
  105. + Mklesson doesn't automatically create the "master outline" file
  106.   nor the tutorial home page; you'll have to do that some other way.
  107.  
  108. + The <TEXT FILE="x"> command does _NOT_ substitute the double-quote (")
  109.   character.  Technically the double-quote character is supposed to be
  110.   substituted, but at least one browser (Windows Mosaic 2.0 alpha 2)
  111.   can't display the substitution correctly. All the browsers I have available
  112.   handle bare double-quote characters correctly.
  113.  
  114. + A recent feature is support for "books".  If you invoke mklesson with a
  115.   "-b" option, the variable "BOOK" is set. You can use this in
  116.   <IFDEF BOOK> expressions.
  117.  
  118. + Mklesson doesn't have many size limitations, but if you want the
  119.   results to work on MS-DOS machines you'll be limited
  120.   by MS-DOS's rediculous filename size limitations (8+3 character maximum).
  121.   For such machines, there can be up to 999 lessons.
  122.   Lessons 1-9     can have up to 999 sections each,
  123.   lessons 10-99   can have up to 99 sections each, and
  124.   lessons 100-999 can have up to 9 sections each.
  125.   This assumes that there are no more than 9 possible responses to
  126.   a specific quiz question.
  127.   This limitation is because of the way filenames are generated by mklesson;
  128.   this doesn't apply to systems which permit longer filenames.
  129.   If MS-DOS machines may use your files, you might want to consider using
  130.   the "-s" option, which generates "short" filename extensions
  131.   (.htm instead of .html).
  132.  
  133. Here is a BNF of the les file format. In this BNF,
  134.    !p!   means p is a nonterminal,
  135.    [q]   means q is optional,
  136.    {r}*  means r repeats 0 or more times
  137.    {s}+  means s repeats 1 or more times
  138.    ;     is a BNF comment
  139.    ::=   defines a nonterminal
  140.  
  141.  
  142. !lesfile! ::= !header!
  143.               {!body!}+
  144.  
  145. !header! ::= <TUTOR NAME="name_of_tutor_system">
  146.              <LESSON NUMBER=number_of_lesson>
  147.              <AUTHOR NAME="name" ADDRESS="email_address">
  148.              [<PREVIOUS_LESSON LOCATION="URL_of_directory/">]
  149.              [<NEXT_LESSON LOCATION="URL_of_directory/">]
  150.              [<TUTOR_HOME_PAGE HREF="URL">]
  151.              [<MASTER_OUTLINE HREF="URL">]
  152.  
  153.  
  154. !body! ::= <SECTION NAME="section_name">
  155.            section_text_as_HTML
  156.            [!quiz!]
  157.            [</SECTION>]
  158.  
  159. !section_text_as_HTML! ::=  { HTML_text |
  160.            <TEXT [FONT=PRE] [TEMPLATE=X] FILE="filename"> |
  161.            ifdef
  162.            }*
  163.  
  164. !ifdef! ::= <IFDEF BOOK>
  165.             HTML_text_to_include_if_this_is_a_book
  166.             <ELSE>
  167.             HTML_text_to_include_if_this_is_NOT_a_book
  168.             <ENDIF>
  169.  
  170.   ; Each section generates a file named:
  171.   ;   "s" + lesson_number + "-" section_number + ".html"
  172.   ;   (section_number is replaced with the text "last" for the last section)
  173.   ; The header is generated from section.head, the tail from section.tail, by
  174.   ; substituting various variables in section.head and section.tail.
  175.  
  176. !quiz! ::= <QUESTION [Type=Multiple-Choice]>
  177.            question_text_as_HTML?
  178.            <CHOICES>
  179.            {choice_clause!}+
  180.            </CHOICES>
  181.            <ANSWER ANS=the_answer>
  182.            [!responses!]
  183.  
  184. !choice_clause! ::= <CHOICE [ANS=number]> choice_text_as_HTML
  185.  
  186. !responses! ::= <RESPONSES>
  187.                 {!when_clause!}+
  188.                 </RESPONSES>
  189.  
  190. !when_clause! ::= <WHEN ANS=number>
  191.                   response_text_as_HTML
  192.  
  193. !when_clause! ::= <WHEN CORRECT>
  194.                   response_text_as_HTML
  195.  
  196.