home *** CD-ROM | disk | FTP | other *** search
/ Solo Programadores 22 / SOLO_22.iso / docs / lovelace / formatmk.txt < prev    next >
Encoding:
Text File  |  1995-11-21  |  6.6 KB  |  174 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. Here are a few little nitpicks and details:
  83. + The very first section (1-1) is somewhat special.  If a user decides
  84.   to skip the quiz and go to the next section, they will link to
  85.   the special file "skip1-1.html".  This file is where you can chide
  86.   the user to take the quiz, but permit them to move on.
  87.   I've included the skip1-1.html file for Lovelace; you will want to
  88.   modify it for your own program.
  89.  
  90. + The standard "template" file uses graphic files:
  91.   up.gif (point up), previous.gif (point left), next.gif (point right),
  92.   and tinyhome.gif (an icon representing your home page).
  93.   The tinyhome.gif file included in the distribution is for Lovelace;
  94.   you should replace this with an image representing your tutorial.
  95.   If you don't want graphics at all, copy the file txt-temp into the
  96.   file template; txt-temp contains a template that doesn't use any graphics.
  97.  
  98. + Mklesson doesn't automatically create the "master outline" file
  99.   nor the tutorial home page; you'll have to do that some other way.
  100.  
  101. + The <TEXT FILE="x"> command does _NOT_ substitute the double-quote (")
  102.   character.  Technically the double-quote character is supposed to be
  103.   substituted, but at least one browser (Windows Mosaic 2.0 alpha 2)
  104.   can't display the substitution correctly. All the browsers I have available
  105.   handle bare double-quote characters correctly.
  106.  
  107. + Mklesson doesn't have many size limitations, but if you want the
  108.   results to work on MS-DOS machines you'll be limited
  109.   by MS-DOS's rediculous filename size limitations (8+3 character maximum).
  110.   For such machines, there can be up to 999 lessons.
  111.   Lessons 1-9     can have up to 999 sections each,
  112.   lessons 10-99   can have up to 99 sections each, and
  113.   lessons 100-999 can have up to 9 sections each.
  114.   This assumes that there are no more than 9 possible responses to
  115.   a specific quiz question.
  116.   This limitation is because of the way filenames are generated by mklesson;
  117.   this doesn't apply to systems which permit longer filenames.
  118.   If MS-DOS machines may use your files, you might want to consider using
  119.   the "-s" option, which generates "short" filename extensions
  120.   (.htm instead of .html).
  121.  
  122. Here is a BNF of the les file format. In this BNF,
  123.    !p!   means p is a nonterminal,
  124.    [q]   means q is optional,
  125.    {r}*  means r repeats 0 or more times
  126.    {s}+  means s repeats 1 or more times
  127.    ;     is a BNF comment
  128.    ::=   defines a nonterminal
  129.  
  130.  
  131. !lesfile! ::= !header!
  132.               {!body!}+
  133.  
  134. !header! ::= <TUTOR NAME="name_of_tutor_system">
  135.              <LESSON NUMBER=number_of_lesson>
  136.              <AUTHOR NAME="name" ADDRESS="email_address">
  137.              [<PREVIOUS_LESSON LOCATION="URL_of_directory/">]
  138.              [<NEXT_LESSON LOCATION="URL_of_directory/">]
  139.              [<TUTOR_HOME_PAGE HREF="URL">]
  140.              [<MASTER_OUTLINE HREF="URL">]
  141.  
  142.  
  143. !body! ::= <SECTION NAME="section_name">
  144.            section_text_as_HTML
  145.            [!quiz!]
  146.            [</SECTION>]
  147.  
  148.   ; Each section generates a file named:
  149.   ;   "s" + lesson_number + "-" section_number + ".html"
  150.   ;   (section_number is replaced with the text "last" for the last section)
  151.   ; The header is generated from section.head, the tail from section.tail, by
  152.   ; substituting various variables in section.head and section.tail.
  153.  
  154. !quiz! ::= <QUESTION [Type=Multiple-Choice]>
  155.            question_text_as_HTML?
  156.            <CHOICES>
  157.            {choice_clause!}+
  158.            </CHOICES>
  159.            <ANSWER ANS=the_answer>
  160.            [!responses!]
  161.  
  162. !choice_clause! ::= <CHOICE [ANS=number]> choice_text_as_HTML
  163.  
  164. !responses! ::= <RESPONSES>
  165.                 {!when_clause!}+
  166.                 </RESPONSES>
  167.  
  168. !when_clause! ::= <WHEN ANS=number>
  169.                   response_text_as_HTML
  170.  
  171. !when_clause! ::= <WHEN CORRECT>
  172.                   response_text_as_HTML
  173.  
  174.