Mercurial > ~dholland > hg > ag > index.cgi

comparison help2html/notes.txt @ 0:13d2b8934445

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import AnaGram (near-)release tree into Mercurial.
author David A. Holland
date Sat, 22 Dec 2007 17:52:45 -0500
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:13d2b8934445
1
2 Notes on HTML version of help.src
3 ---------------------------------
4
5 ----- Overview of structure assumptions and treatment of help.src ------
6
7 (a) The help.src file
8
9 help.src consists of a sequence of topics, each with a title line and
10 a topic body. They are only partly sorted by title line. There may or
11 may not be "blank line"s between the topics. "Blank line"s, however,
12 are necessary to separate some sections in the topic bodies. It was
13 found necessary to disallow extra spaces or tabs in a "blank line",
14 i.e. a blank line is just a newline (lf) char. It turns out Jerry had
15 already found it necessary to remove such extra spaces.
16
17 There must be at least one "blank line" after a title line, preceding
18 the topic body. A topic ends with an "end topic" line starting with
19 "##" beginning in column 1. The end topic line may have some spaces
20 before the terminating newline.
21
22 The final eof line can have leading blanks and be preceded by "blank
23 line"s as above.
24
25
26 (b) Title:
27
28 Title line is one line only, begins in col. 1 with a "lead title char":
29
30 lead title char = char - blank - tab - ',' - bullet - '\n', char=~eof
31
32 Here a "bullet" is a control-G (bell) character, aka 0x7.
33
34 The individual topics in the title are comma-separated. They may have
35 these chars:
36
37 title char = char - ',' - bullet - '\n', where char=~eof
38
39
40 (c) Topic body:
41
42 Inspection of help.src suggested that there were 6 different kinds of
43 paragraphs in a topic body, which were separated by blank lines. The
44 first paragraph was always of type "text" - this turned out to be
45 needed for the parsing. Remaining paragraphs could be text or look
46 like a table, code, or several varieties of list.
47
48 (c1) Text paragraphs
49 The first line of a text paragraph had to begin with a
50
51 lead topic char = char - blank - tab - bullet - '\n', where char=~eof
52
53 or with a single blank followed by a lead topic char. The leading
54 blank seemed to occur only after a preceding table-type section, after
55 a blank line. It seems that Jerry uses this construct for some
56 purpose, but it didn't seem to be necessary for mhh5 parsing.
57
58 Some text paragraphs had code interspersed, not always separated with
59 a newline, and some had a following "table" or list without a blank
60 line as separator.
61
62 (c2) Table paragraphs
63 A paragraph with a tab in col 1 of the first line was assumed to be
64 some sort of table. Sometimes there were several leading tabs.
65 Sometimes there were further sequences of tabs in the rest of the
66 line. Mostly there was just one set of tabs - these were easy to deal
67 with. There are only a couple of cases of several sets of tabs, which
68 correspond to 2 and 3-column tables. As of July 12/01 mhh5 uses the
69 tabs to construct multi-column tables and the contents of the table
70 cells are treated as code.
71
72 A table can occur following a text paragraph, tab list or one-space
73 list without an intervening blank line.
74
75 Treating the whole table as code enclosed in <pre> </pre> tags,
76 removing the leading tabs and any leading spaces, worked very well
77 except for the 2 or 3-column tables.
78
79 (c3) Code paragraphs
80 If a paragraph began with a sequence of 2, 3, 4, 5, 6, 8, or 10 spaces
81 (all these sequences occur in help.src) it is considered a code
82 paragraph and enclosed in <pre> </pre> tags. In this case the leading
83 spaces are preserved.
84
85 (c4) List paragraphs
86 If a paragraph begins with a "bullet" (control-G) character it is
87 deemed to be some sort of list. Sometimes the list items are separated
88 by blank lines and sometimes not. The bullet was variously followed by
89 one space, two spaces, or a tab. The two-spaces version occurs only
90 once in help.src (in part of What's New) and possibly has no
91 significance for Jerry's parsing; maybe it could be eliminated.
92
93 All 3 list types were turned into HTML unordered lists, with the
94 leading bullet and spaces or tab swallowed. Since list topics
95 sometimes were separated with blank lines and sometimes not, it was
96 necessary to keep an AgStack with the current list type on it -
97 actually a multi-valued flag would have been sufficient but the stack
98 might also be useful for tables.
99
100 A one-space list can be followed by a table or code without an
101 intervening blank line and a tab list can be similarly followed by a
102 table.
103
104 ============================================================================
105
106
107 July 1, 2001
108
109 The list2 variation, with 2 leading spaces after the control G instead
110 of 1 as in list1, appears to occur *only* in Wnat's New (not What's
111 New in AnaGram 2.0). There doesn't seem to be any reason for it in
112 terms of how AnaGram online help treats it.
113
114 Internal Error topic has a line of code with a period after it. This
115 looks wrong and also looks wrong in the online help. Period should be
116 removed from help.src.
117
118 Keyword topic - the list here has extra line spacing for the last list
119 items, plus an embedded code example, so spacing doesn't look too
120 good. Possibly the line spacing could be altered in help.src. Also,
121 use of IF and IFF to demonstrate keyword lookahead is not a good
122 choice for HTML as the I looks like a vertical divider in some
123 fonts. Change to EX and EXT or GO and GOO?
124
125 Also, the use of double quotes around "keyword" doesn't look proper in
126 HTML and is probably not good even in help.src. Remove quotes in
127 help.src?
128
129
130 July 3, 2001
131
132 The exit_flag topic has a table which does not seem to be generated in
133 any regular manner and accommodates basically to the default help font
134 used by AnaGram, which is not monospaced. Combinations of spaces and
135 tabs have been used to get alignment:
136
137 AG_RUNNING_CODE(15 char) is preceded by a tab, then 4 spaces and 4 tabs,
138 then = 0:tab and the explanation.
139 AG_SUCCESS_CODE (15 char) - same form as above but 8 space and 4 tabs
140 AG_SYNTAX_ERROR_CODE (20 char) - 3 spaces, 2 tabs
141 AG_REDUCTION_ERROR_CODE (23 char) - 1 space, 1 tab
142 AG_STACK_ERROR_CODE (19 char) - 3 spaces, 3 tabs
143 AG_SEMANTIC_ERROR_CODE (22 char) - 1 space, 2 tabs
144
145 It is desirable to keep the width to a minimum here because it governs
146 the width chosen by the browser for displaying *all* the text.
147 Possible to create a table (ugh) or swallow the spaces and tabs in
148 favor of a single space.
149
150 The What's New topic has an example under Bug Fixes which uses a lot
151 of spaces before the reduction procedure. These make the HTML page too
152 wide - and in the online help, they do not seem to appear at all,
153 probably being replaced with a single space.(?) This is a code
154 paragraph, leading with 8 and 10 spaces, not a table paragraph; hard
155 to see what to do other than change help.src.
156
157
158 July 4, 2001
159
160 mhh5 now inserts links properly. Turns out that some links in help.src
161 include the "s" at the end inside the link if they are plural, even if
162 the help topic is singular. So it is necessary to strip the "s" and
163 test again for a matching topic title.
164
165 Topics still in need of some adjustment are:
166 exit_flag
167 Internal Error
168 Keyword
169 Virtual Production
170 What's New
171 Character Constant
172 Data Type
173 PCB_TYPE
174 Some of these are discussed above. Mostly the problem is use of tabs
175 and spaces in help.src in a way that does not lend itself to general
176 rules to apply to the html.
177
178 Still need to be able to replace <,>, & in help.src with the
179 appropriate entities before creating the html version.
180
181
182 July 12, 2001
183
184 mhh5 now inserts entities and can handle multiple-column tables (as
185 detected by tab sequences in the table lines).
186
187
188 Aug 3, 2001
189
190 mhh5.syn should have some comments inserted at the beginning to
191 mention this notes.txt file and to say what the program does. It
192 should also probably print a comment at the beginning of the html file
193 along the lines of:
194
195 " All the information in this file may also be accessed from within
196 AnaGram using Help Topics on the Help menu. This HTML file is provided
197 because it is sometimes more convenient to read the topics with your
198 browser, and beeause the browser can be used to search the whole file.
199 This is a long file with many links; some older browsers slow to a
200 crawl. Netscape works fine."
201
202 I am holding off on doing this because it means another round of
203 compilation and testing and Jerry has not been available to even look
204 at the output or pass on the above wording.
205
206 Moreover, the output file has not been tested with up-to-date versions
207 of Microsoft Internet Explorer. The old version on Secondo really does
208 slow to a crawl. The file is not really usable; not clear if it could
209 be improved by modifying the HTML if the newer Internet Explorer
210 versions can't deal with it either.
211