forked from jkubin/m4root
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathbrief_documentation.txt
428 lines (428 loc) · 13.1 KB
/
brief_documentation.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
# vim:wrap:spell:spelllang=en
This is a generated brief documentation from all source files.
It also shows the possibilities of the M4.
---
File: gfiles/rootb.m4
Author: Josef Kubin
Started: 2018/10/15
Note: https://github.com/jkubin/m4root
Version: 0.0.0
Description: the most general (root) rules for all scripts
Reason: script decomposition; NO repeated information anywhere else
Usage: m4 root.m4 stem.m4 branch.m4 sub_branch.m4 leaf.m4 data.mc > output.file
---
File: gfiles/rulerb.m4
Author: Josef Kubin
Started: 2019/11/16
Note: root
Description: generates a string to shorten another string (by hand) because truncation is hardly acceptable
Reason: computer cannot truncate the string to remain readable
Usage: m4 rootb.m4 rulerb.m4 …
---
File: doc.m4
Author: Josef Kubin
Started: 2020/01/20
Note: m4root
Description: extracts headers from source files and creates brief documentation
Reason: brief documentation is a solution for cryptic short filenames
Usage: m4 doc.m4 …
---
File: lang_cs.m4
Author: Josef Kubin
Started: 2019/07/11
Note: root_cz
Description: the file contains words specific to the generated language
Reason: multilingual targets
---
File: messages/Makefile
Author: Josef Kubin
Started: 2019/11/17
Note: root_cz
Description: the examples show how to generate messages into various target formats requiring modification of special characters
Reason: different target files with specially modified characters for each file
Usage: make h && make
---
File: preproc/Makefile
Author: Josef Kubin
Started: 2019/11/18
Note: root_cz
Description: generic examples how to use M4 as preprocessor
Reason: M4 as preprocessor
Usage: make h && make
---
File: captions.sed
Author: Josef Kubin
Started: 2019/08/25
Note: m4root
Description: the script converts the caption string to the string used for filenames; resulting string is not truncated
Reason: full-length lower case ASCII strings for file names
---
File: if20/kiosk_preproc.m4
Author: Josef Kubin
Started: 2020/02/05
Note: if20
Description:
Reason:
Usage: m4 kiosk_preproc.m4 symbols.mc
---
File: if20/Makefile
Author: Josef Kubin
Started: 2020/02/05
Note: if20
Description:
Reason:
Usage: make h
---
File: refs.m4
Author: Josef Kubin
Started: 2019/12/11
Note: root_cz
Description: tests logic flow (CHAPTER → SECT1 → SECT2) and generates references for anchors
Reason: extracts all IDs from files and create associative pair
---
File: hello_world/Makefile
Author: Josef Kubin
Started: 2019/08/24
Note: root_cz
Description: examples generate several hello world source files
Reason: how to generate files for different computer languages
Usage: make h && make
---
File: gfiles/quotation_marks_vim.sed
Author: Josef Kubin
Started: 2019/10/27
Note: m4root
Description: converts vim iabbrev file for square brackets to iabbrev file for original quotation marks
Reason: keeps consistent 1:1 iabbrev vim file for square brackets with quotation marks
---
File: gfiles/nonprintable_chars.sed
Author: Josef Kubin
Started: 2019/09/22
Note: m4root
Description: converts the root file for square brackets to the root file for nonprintable characters
Reason: root file for nonprintable characters
---
File: gfiles/utf8_chars_skel.sed
Author: Josef Kubin
Started: 2019/10/27
Note: m4root
Description: converts skeleton file for square brackets to skeleton file for UTF-8 characters
Reason: skeleton file for UTF-8 characters
---
File: gfiles/quotation_marks.sed
Author: Josef Kubin
Started: 2019/09/22
Note: m4root
Description: converts the root file for square brackets to the root file for original quotation marks
Reason: root file for original quotation marks
---
File: gfiles/nonprintable_chars_skel.sed
Author: Josef Kubin
Started: 2019/10/27
Note: m4root
Description: converts skeleton file for square brackets to skeleton file for nonprintable characters
Reason: skeleton file for nonprintable characters
---
File: gfiles/utf8_chars_vim.sed
Author: Josef Kubin
Started: 2019/10/27
Note: m4root
Description: converts vim iabbrev file for square brackets to iabbrev file for UTF-8 characters
Reason: keeps consistent 1:1 iabbrev vim file for square brackets with UTF-8 characters
---
File: gfiles/quotation_marks_skel.sed
Author: Josef Kubin
Started: 2019/11/22
Note: m4root
Description: converts skeleton file for square brackets to skeleton file for quotation marks
Reason: skeleton file for quotation marks
---
File: gfiles/utf8_chars.sed
Author: Josef Kubin
Started: 2019/09/22
Note: m4root
Description: converts the root file for square brackets to the root file for UTF-8 characters
Reason: root file for UTF-8 characters
---
File: gfiles/nonprintable_chars_vim.sed
Author: Josef Kubin
Started: 2019/10/27
Note: m4root
Description: converts vim iabbrev file for square brackets to iabbrev file for nonprintable characters
Reason: keeps consistent 1:1 iabbrev vim file for square brackets with nonprintable characters
---
File: gfiles/Makefile
Author: Josef Kubin
Started: 2019/10/26
Note: root_cz
Description: maintains consistent files with square bracket files
Reason: one hand-written file to generate additional files
Usage: make h && make
---
File: ver.m4
Author: Josef Kubin
Started: 2019/12/22
Note: root_cz
Description: the HTML template is under development; to avoid frustrating innocent users a version number is used
Reason: stops document processing if the major version number is different
---
File: toc.m4
Author: Josef Kubin
Started: 2019/08/25
Note: root_cz
Description: definitions of queues; table of content; languages
Reason: source files and their order
---
File: lang.m4
Author: Josef Kubin
Started: 2019/12/30
Note: root_cz
Description: converts LANG_CODE to numeric index and selects desired language item
Reason: selects item from multilingual list
---
File: headings.m4
Author: Josef Kubin
Started: 2019/12/31
Note: root_cz
Description: sets heading item in desired language
Reason: mono/multi-lingual headings
---
File: toc_list.m4
Author: Josef Kubin
Started: 2019/11/29
Note: root_cz
Description: generates the necessary common macros for other M4 scripts
Reason: the order is based on the queue index
---
File: test.m4
Author: Josef Kubin
Started: 2019/07/18
Note: root_cz
Description:
Reason:
---
File: html/files/list.m4
Author: Josef Kubin
Started: 2019/12/15
Note: root_cz
Description: processes one simple macro with files to complex block of html code
Reason: converts list of files from command line to html code
---
File: html/files/main.m4
Author: Josef Kubin
Started: 2019/12/15
Note: root_cz
Description: source files contains M4 keywords and forbidden characters, therefore must be processed
Reason: any input files must be processed first
---
File: html/files/link.m4
Author: Josef Kubin
Started: 2020/01/09
Note: html
Description: inserts source file content with a link and an optional description
Reason: source file, link and description
---
File: html/nav.m4
Author: Josef Kubin
Started: 2019/12/01
Note: root_cz
Description: navigation logic for HTML page; table of content; all parts of the series
Reason: common script for preview and publish
---
File: html/preview.m4
Author: Josef Kubin
Started: 2019/07/11
Note: root_cz
Description: creates preview html page for off-line article development
Reason: preview html file
---
File: html/css.m4
Author: Josef Kubin
Started: 2019/12/24
Note: root_cz
Description: the resulting style sheet is embedded in the web page or can be extracted into a separated file
Reason: here are all CSS rules that are automatically selected into the style sheet
---
File: html/queues.m4
Author: Josef Kubin
Started: 2019/07/11
Note: root_cz
Description: definitions of output queues
Reason: each target file format has a specific queue list
---
File: html/style.m4
Author: Josef Kubin
Started: 2019/12/24
Note: root_cz
Description: creates a style sheet in the reserved namespace
Reason: the style sheet contains only the things that are actually used
---
File: html/block.m4
Author: Josef Kubin
Started: 2019/12/29
Note: root_cz
Description: basic set of block-level elements with a subset of global attributes
Reason: HTML5 block-level elements
---
File: html/publish.m4
Author: Josef Kubin
Started: 2019/12/12
Note: root_cz
Description: creates the final file for CMS (copy and paste); xvim shortcut to copy HTML part: "+yG
Reason: template for CMS
---
File: html/cfg.m4
Author: Josef Kubin
Started: 2019/12/09
Note: root_cz
Description: main configuration for the html template
Reason: one place to configure ALL generated web pages
---
File: html/validate.m4
Author: Josef Kubin
Started: 2019/12/27
Note: root_cz
Description: creates a lightweight page for HTML validator (https://validator.w3.org/#validate_by_upload) and it also seems to be suitable for off-line article development
Reason: develop and test the result before publishing
---
File: html/ent.m4
Author: Josef Kubin
Started: 2020/01/14
Note: html
Description: solution for html entities which must be hidden
Reason: html entities
---
File: html/inline.m4
Author: Josef Kubin
Started: 2019/12/28
Note: root_cz
Description: basic set of inline elements with a subset of global attributes
Reason: HTML5 inline elements
---
File: html/publish.sed
Author: Josef Kubin
Started: 2019/12/22
Note: m4root
Description: convert problematic multi-byte UTF-8 characters (CMS refuses them) to HTML entities
Reason: converts multi-byte UTF-8 characters to HTML entities for Content Management System
---
File: html/process_src.sed
Author: Josef Kubin
Started: 2019/09/01
Note: m4root
Description: the script modifies input source code for use in M4 source code and for resulting HTML page
Reason: every source code must be processed first
---
File: lang_en.m4
Author: Josef Kubin
Started: 2019/07/11
Note: root_cz
Description: the file contains words specific to the generated language
Reason: multilingual targets
---
File: order.m4
Author: Josef Kubin
Started: 2019/11/29
Note: root_cz
Description: (this is a generated file) contains extracted items from the ‘toc.m4’ file for other scripts
Reason: ordered files to generate other files
---
File: intro.mc.html/demo.m4
Author: Josef Kubin
Started: 2020/01/12
Note: intro.mc.html
Description: introductory parts have specific demands for files
Reason: specific file (not for general use)
---
File: intro.mc.html/msg.m4
Author: Josef Kubin
Started: 2019/12/28
Note: root_cz
Description: inserts files for messages; introductory parts have specific demands for files
Reason: specific file (not for general use)
---
File: refs_cs.m4
Author: Josef Kubin
Started: 2019/12/11
Note: root_cz
Description: (this is a generated file) associative memory to linking references, contains captions and ID
Reason: linking links and simple database
---
File: spell.m4
Author: Josef Kubin
Started: 2019/12/23
Note: root_cz
Description: converts inline and block-level elements into a plain text file for checking jargon and typos
Reason: plain text file for spell checking and for suggestions from other people (text can be easily edited)
---
File: asm/Makefile
Author: Josef Kubin
Started: 2019/10/13
Note: root_cz
Description: keeps two ASM files consistent for both Intel and AT&T notation; uses a local .vimrc file with iabbrev-s
Reason: two ASM file formats generated from one metafile
Usage: make h && make
---
File: anchors.sed
Author: Josef Kubin
Started: 2019/08/25
Note: m4root
Description: the script converts a caption string in UTF-8 to HTML anchors; the resulting string is truncated to 32 characters
Reason: truncated lower case ASCII strings for anchors
---
File: aux.m4
Author: Josef Kubin
Started: 2019/12/07
Note: root_cz
Description: auxiliary macros that could not fit elsewhere: CMD(); ROO();
Reason: automate anything you can
---
File: refs_en.m4
Author: Josef Kubin
Started: 2019/12/11
Note: root_cz
Description: (this is a generated file) associative memory to linking references, contains captions and ID
Reason: linking links and simple database
---
File: mk/fhtml.m4
Author: Josef Kubin
Started: 2020/01/05
Note: root_cz
Description: the script creates experimental additional rules extending the handwritten Makefile to generate HTML files
Reason: additional rules by configuration from command line; the rules utilise M4 frozen files to generate HTML files
---
File: mk/html.m4
Author: Josef Kubin
Started: 2019/09/01
Note: root_cz
Description: the script creates additional rules extending the handwritten Makefile to generate HTML files
Reason: additional rules by configuration from command line to generate HTML files
---
File: mk/xml.m4
Author: Josef Kubin
Started: 2020/01/11
Note: mk
Description: the script creates rules for Makefile to generate XML files
Reason: generated XML files
---
File: brackets.sed
Author: Josef Kubin
Started: 2020/01/09
Note: m4root
Description: transforms brackets as HTML entities back to ASCII
Reason: post processing after M4 scripts; simple square brackets allow better reading of the resulting file
---
File: Makefile
Author: Josef Kubin
Started: 2019/10/09
Note: root_cz
Description: this handwritten Makefile automatically creates additional rules for creating target files
Reason: learning M4 using the examples in this series
Usage: make h && make && make
---
File: incl.m4
Author: Josef Kubin
Started: 2019/12/10
Note: root_cz
Description: repeated text patterns for ALL parts should be written here; modified files from the include keyword are invisible for make
Reason: how to avoid include keyword; Note: this is M4 not C!