Get rid of RL_API doc generator, more tab excising

The comments in %a-lib.c were structurally analyzed to produce a text file for documentation of the RL_API that nobody has probably ever actually read (at least not in many years). It used an ad-hoc parsing technique when there is now a much better C-language parser from @codebybrett. (Also, as basically none of the RL_API routines are being kept as they were, the arbitrary restrictions on the comment blocks for the format was really just in the way.) If documentation is desired, it should be done as an extension of the current source analysis parser. This will be more appropriate when the RL_API has been stabilized. This also adds to %common.r an override of `tab` which causes an error, to try and prevent putting tab characters in the files that the tools generate. (They can still use tab escapes in strings or other means, but this cuts down on the cases...hopefully eliminated eventually.) Also macro++ changed to PROCEDURE for correct bootstrap.
metaeducation · Nov 19, 2016 · 9150008 · 9150008
1 parent bca655a
commit 9150008
Show file tree

Hide file tree

Showing 8 changed files with 54 additions and 122 deletions.
diff --git a/.gitignore b/.gitignore
@@ -64,9 +64,6 @@ src/include/reb-lib.h
 src/include/reb-types.h
 src/include/tmp-*
 
-src/tools/reb-lib-doc.txt
-src/reb-lib-doc.txt
-
 #################
 ## Eclipse
 #################

diff --git a/src/tools/common.r b/src/tools/common.r
@@ -30,6 +30,10 @@ do %r2r3-future.r
 
 spaced-tab: rejoin [space space space space]
 
+tab-char: #"^-" ;-- only GNU Makefiles require this...
+tab: does [
+    fail "Don't generate files with tabs in them, use SPACED-TAB"
+]
 
 to-c-name: function [
     {Take a Rebol value and transliterate it as a (likely) valid C identifier.}

diff --git a/src/tools/make-boot.r b/src/tools/make-boot.r
@@ -122,7 +122,7 @@ up-word: func [w] [
 out: make string! 100000
 emit: proc [data] [repend out data]
 
-emit-enum: proc [word] [emit [tab to-c-name word "," newline]]
+emit-enum: proc [word] [emit [spaced-tab to-c-name word "," newline]]
 
 emit-line: proc [prefix word cmt /var /define /code /decl /up1 /local str][
 
@@ -597,8 +597,8 @@ for-each [cat msgs] boot-errors [
     ]
 ]
 
-emit ["#define RS_MAX" tab n lf]
-emit ["#define RS_SIZE" tab length out lf]
+emit ["#define RS_MAX" space n newline]
+emit ["#define RS_SIZE" space length out newline]
 boot-strings: to-binary code
 
 ;-- Generate Canonical Words (must follow datatypes above!) ------------------
@@ -724,7 +724,7 @@ make-obj-defs: proc [obj prefix depth /selfless /local f] [
     for-each field words-of obj [
         emit-line prefix field blank
     ]
-    emit [tab uppercase join prefix "MAX^/"]
+    emit [spaced-tab uppercase join prefix "MAX^/"]
     emit "};^/^/"
 
     if depth > 1 [
@@ -789,15 +789,15 @@ emit ["enum event_types {" newline]
 for-each field ob/view/event-types [
     emit-line "EVT_" field blank
 ]
-emit [tab "EVT_MAX^/"]
+emit [spaced-tab "EVT_MAX^/"]
 emit "};^/^/"
 
 emit ["enum event_keys {" newline]
 emit-line "EVK_" "NONE" blank
 for-each field ob/view/event-keys [
     emit-line "EVK_" field blank
 ]
-emit [tab "EVK_MAX^/"]
+emit [spaced-tab "EVK_MAX^/"]
 emit "};^/^/"
 
 write inc/reb-evtypes.h out

diff --git a/src/tools/make-headers.r b/src/tools/make-headers.r
@@ -324,19 +324,19 @@ make-arg-enums: func [word] [
 
     ; Argument numbers:
     emit-out ["enum act_" word "_arg {"]
-    emit-out [tab "ARG_" uword "_0,"]
-    for-each w args [emit-out [tab "ARG_" uword "_" w ","]]
-    emit-out [tab "ARG_" uword "_MAX"]
+    emit-out [spaced-tab "ARG_" uword "_0,"]
+    for-each w args [emit-out [spaced-tab "ARG_" uword "_" w ","]]
+    emit-out [spaced-tab "ARG_" uword "_MAX"]
     emit-out "};^/"
 
     ; Argument bitmask:
     n: 0
     emit-out ["enum act_" word "_mask {"]
     for-each w args [
-        emit-out [tab "AM_" uword "_" w " = 1 << " n ","]
+        emit-out [spaced-tab "AM_" uword "_" w " = 1 << " n ","]
         n: n + 1
     ]
-    emit-out [tab "AM_" uword "_MAX"]
+    emit-out [spaced-tab "AM_" uword "_MAX"]
     emit-out "};^/"
 
     repend output-buffer ["#define ALL_" uword "_REFS ("]

diff --git a/src/tools/make-host-ext.r b/src/tools/make-host-ext.r
@@ -93,7 +93,7 @@ emit-file: func [
     src: source
     while [src: find src set-word!] [
         if all [
-            <no-export> <> first back src
+            <no-export> != first back src
             find [command func function funct] src/2
         ][
             append exported-words to-word src/1
@@ -106,27 +106,36 @@ emit-file: func [
         insert exports exported-words
     ]
 
-    for-each word words [emit [tab "CMD_" prefix #"_" replace/all form-name word "'" "_LIT"  ",^/"]]
-    emit [tab "CMD_MAX" newline]
-    emit "};^/^/"
+    for-each word words [
+        emit [
+            spaced-tab
+            "CMD_" prefix #"_" replace/all form-name word "'" "_LIT"  ","
+            newline
+        ]
+    ]
+    emit [spaced-tab "CMD_MAX" newline]
+    emit ["};" newline newline]
 
     if src: select source to-set-word 'words [
-        emit ["enum " name "_words {^/"]
-        emit [tab "W_" prefix "_0,^/"]
-        for-each word src [emit [tab "W_" prefix #"_" form-name word ",^/"]]
-        emit [tab "W_MAX" newline]
-        emit "};^/^/"
+        emit ["enum " name "_words {" newline]
+        emit [spaced-tab "W_" prefix "_0," newline]
+        for-each word src [
+            emit [spaced-tab "W_" prefix #"_" form-name word "," newline]
+        ]
+        emit [spaced-tab "W_MAX" newline]
+        emit ["};" newline newline]
     ]
 
-    emit "#ifdef INCLUDE_EXT_DATA^/"
+    emit ["#ifdef INCLUDE_EXT_DATA" newline]
     code: append trim/head mold/only/flat source newline
     append code to-char 0 ; null terminator may be required
     emit [
-        "const unsigned char RX_" name "[] = {^/"
+        "const unsigned char RX_" name "[] = {" newline
         binary-to-c to-binary code
-        "};^/^/"
+        "};" newline
+        newline
     ]
-    emit "#endif^/"
+    emit ["#endif" newline]
 
     write rejoin [output-dir/include %/ file %.h] out
 

diff --git a/src/tools/make-make.r b/src/tools/make-make.r
@@ -335,7 +335,7 @@ macro+: procedure [
 ]
 
 
-macro++: function ['name obj [object!]] [
+macro++: procedure ['name obj [object!]] [
     out: make string! 10
     for-each n words-of obj [
         all [
@@ -458,11 +458,11 @@ emit-file-deps/dir os-specific-objs %os/
 ; tabs at the last minute--so this Rebol source file doesn't need to have
 ; actual tab characters in it.
 ;
-if find output tab [
-    print copy/part find output tab 100
-    fail "tab character discovered in makefile prior to space=>tab conversion"
+if find output tab-char [
+    print copy/part find output tab-char 100
+    fail "tab character discovered in makefile prior to space=>tab conversion"
 ]
-replace/all output spaced-tab tab
+replace/all output spaced-tab tab-char
 
 write outdir/makefile output
 print ["Created:" outdir/makefile]
diff --git a/src/tools/make-os-ext.r b/src/tools/make-os-ext.r
@@ -120,10 +120,11 @@ emit-proto: proc [
         fn.name.upper: uppercase copy fn.name
         fn.name.lower: lowercase copy fn.name
 
-        append host-lib-instance reduce [tab fn.name "," newline]
+        append host-lib-instance reduce [spaced-tab fn.name "," newline]
 
         append host-lib-struct reduce [
-            tab fn.declarations "(*" fn.name.lower ")" pos.lparen ";" newline
+            spaced-tab fn.declarations "(*" fn.name.lower ")" pos.lparen ";"
+            newline
         ]
 
         args: count pos.lparen #","

diff --git a/src/tools/make-reb-lib.r b/src/tools/make-reb-lib.r
@@ -52,13 +52,11 @@ xlib-buffer: make string! 20000
 rlib-buffer: make string! 1000
 mlib-buffer: make string! 1000
 dlib-buffer: make string! 1000
-comments-buffer: make string! 1000
 xsum-buffer: make string! 1000
 
-emit:  func [d] [append repend xlib-buffer d newline]
+emit: func [d] [append repend xlib-buffer d newline]
 emit-rlib: func [d] [append repend rlib-buffer d newline]
 emit-dlib: func [d] [append repend dlib-buffer d newline]
-emit-comment: func [d] [append repend comments-buffer d newline]
 emit-mlib: proc [d /nol] [
     repend mlib-buffer d
     if not nol [append mlib-buffer newline]
@@ -85,42 +83,6 @@ in-sub: func [text pattern /local position] [
     ]
 ]
 
-gen-doc: func [name proto text] [
-    replace/all text "**" "  "
-    replace/all text "/*" "  "
-    replace/all text "*/" "  "
-    trim text
-    append text newline
-
-    insert find text "Arguments:" "^/:"
-    bb: beg: find/tail text "Arguments:"
-    insert any [find bb "notes:" tail bb] newline
-    while [
-        all [
-            beg: find beg " - "
-            positive? offset-of beg any [find beg "notes:" tail beg]
-        ]
-    ][
-        insert beg </tt>
-        insert find/tail/reverse beg newline {<br><tt class=word>}
-        beg: find/tail beg " - "
-    ]
-
-    beg: insert bb { - } ;<div style="white-space: pre;">}
-    remove find beg newline
-    remove/part find beg "<br>" 4 ; extra <br>
-
-    remove find text "^/Returns:"
-    in-sub text "Returns:"
-    in-sub text "Notes:"
-
-    insert text reduce [
-        ":Function: - " <tt class=word> proto </tt>
-        "^/^/:Summary: - "
-    ]
-    emit-comment ["===" name newline newline text]
-]
-
 pads: func [start col] [
     str: copy ""
     col: col - offset-of start tail start
@@ -159,12 +121,12 @@ emit-proto: proc [
         comment-text: proto-parser/notes
         encode-lines comment-text {**} { }
 
-        emit-mlib ["/*^/**^-" proto "^/**^/" comment-text "*/" newline]
-
-        ; !!! Documentation of RL_Api is currently a low priority.
-        ;
-        comment [
-            gen-doc fn.name proto comment-text
+        emit-mlib [
+            "/*" newline
+            "**" space space proto newline
+            "**" newline
+            comment-text
+            "*/" newline
         ]
 
         proto-count: proto-count + 1
@@ -181,50 +143,11 @@ process: func [file] [
     proto-parser/process data
 ]
 
-write-if: proc [file data] [
-    if data != attempt [to string! read file][
-        print ["UPDATE:" file]
-        write file data
-    ]
-]
-
 ;-----------------------------------------------------------------------------
 
 emit-rlib {
 typedef struct rebol_ext_api ^{}
 
-emit-comment [{Host/Extension API
-
-=r3
-
-=*Updated for A} ver/3 { on } now/date {
-
-=*Describes the functions of reb-lib, the REBOL API (both the DLL and extension library.)
-
-=!This document is auto-generated and changes should not be made within this wiki.
-
-=note WARNING: PRELIMINARY Documentation
-
-=*This API is under development and subject to change. Various functions may be moved, removed, renamed, enhanced, etc.
-
-Also note: the formatting of this document will be enhanced in future revisions.
-
-=/note
-
-==Concept
-
-The REBOL API provides common API functions needed by the Host-Kit and also by
-REBOL extension modules. This interface is commonly referred to as "reb-lib".
-
-There are two methods of linking to this code:
-
-*Direct calls as you would use functions within any DLL.
-
-*Indirect calls through a set of macros (that use a structure pointer to the library.)
-
-==Functions
-}]
-
 ;-----------------------------------------------------------------------------
 
 process reb-lib
@@ -287,7 +210,7 @@ xlib-buffer
 }
 ]
 
-write-if reb-ext-lib out
+write reb-ext-lib out
 
 ;-----------------------------------------------------------------------------
 
@@ -300,9 +223,7 @@ dlib-buffer
 }
 ]
 
-write-if reb-ext-defs out
-
-write-if output-dir/reb-lib-doc.txt comments-buffer
+write reb-ext-defs out
 
 ;ask "Done"
 print "   "