13 make targets that awk the same source

[u/ekipan85]

https://github.com/ekipan/nictoforth

Repo linked above, or just the Makefile (and permalink), r/Forth post.

$ make words
2+ 2u/ and invert 0= + drop dup swap >r r> >in
dp sp@ rp@ @ ! key emit line lex find execute abort
quit head, , ] compile, ; exit immediate ;
$

I needed a word list for my hobby Forth's README. I realized I could just about grep them from my assembly source, so I added a bit more structure to the comments and did it.

Later, stricken with overcommenting dread, I got the idea to awk the comments away. Felt good to read. Luckily the source was structured enough to survive as quite readable, IMO anyway.

Then I formalized them as targets. Currently:

words:    # compact list of the implemented forth words. [!]
    @awk '/--/ && !/^;|^interp/ {print $$3}' $(SRC) | xargs -n 12 ||:

glossary: # labels that implement words, with stack effects.
    @awk '/--/' $(SRC) ||:

terse:    # just the code, no asides.
    @echo '; see $(SRC) for notes [5c] [6b] etc.'
    @awk '/--$$/; !/^;/; $(DESIGN)' $(SRC) | cat -s ||:

Then I, uh, got carried away.

$ make help # awks Makefile itself.
## nictoforth is an x86 bootsector forth that: (...)

## target files you can make: (...)

## development phonies: (...)

## these phonies filter slices of the source:
words:    # compact list of the implemented forth words. [!]
teaser1:  # the interpreter routine. the heart of a forth. [!]
teaser2:  # the bootstrap. *terrifying* and heavily documented.
design:   # example, memory map, registers, control flow. [!]
reading:  # source format conventions.
glossary: # labels that implement words, with stack effects.
names:    # all labels, variables, macros.
skel:     # control flow: labels, jumps, calls, rets. [!]
terse:    # just the code, no asides.
notes:    # anchored note contents, tricky highlights.
doc:      # the main comment text, no code.
xrefs:    # inventory cross-ref anchors, for maintenance.
help:     # this list. [!] marks important targets.

## try:
##  $ make words # or teaser1 or design or ...
##  $ make skel | bat -l nasm # or: | less
##  $ make terse >o/terse.asm
$

Yeahhhh this is way way over-engineered for purpose. But damn it was fun to write.

Makefile link again.

Have a poke through, see if you can pluck anything. Obviously generating docs is not new, but have you ever given this many views of the same source? Would you find these targets useful if you wanted to come up to speed on the project?

The Forth itself is currently 496 bytes of x86.

---

Per the "more than a small portion" bit in rule 4, I'm confident I can leave out the AI disclaimer. It's my hobby project, the working and the thinking are the fun part, but: I did consult with AI, out of curiosity. First time touching the things. If you care, search the README for "LLM", I have a whole damn rant.

Unfortunately I'm pretty ignorant of alternatives per rule 8, at least as far as doc generating goes. I'm just a hobbyist. For Forths, though, I talk a lot about Milliforth, Sectorforth, durexForth, Miniforth, DuskOS (check the Tumble Forth blog, it's how I fell into this rabbit hole!). Those first two are my direct ancestors.

[u/AutoModerator]

Every new subreddit post is automatically copied into a comment for preservation.

User: ekipan85, Flair: Command Line Interface, Post Media Link, Title: 13 make targets that awk the same source

$ make words
2+ 2u/ and invert 0= + drop dup swap >r r> >in
dp sp@ rp@ @ ! key emit line lex find execute abort
quit head, , ] compile, ; exit immediate ;
$

I needed a word list for my hobby Forth's README. I realized I could just about grep them from my assembly source, so I added a bit more structure to the comments and did it.

Later, stricken with overcommenting dread, I got the idea to awk the comments away. Felt good to read. Luckily the source was structured enough to survive as quite readable, IMO anyway.

Then I formalized them as targets. Currently:

words:    # compact list of the implemented forth words. [!]
    @awk '/--/ && !/^;|^interp/ {print $$3}' $(SRC) | xargs -n 12 ||:

glossary: # labels that implement words, with stack effects.
    @awk '/--/' $(SRC) ||:

terse:    # just the code, no asides.
    @echo '; see $(SRC) for notes [5c] [6b] etc.'
    @awk '/--$$/; !/^;/; $(DESIGN)' $(SRC) | cat -s ||:

Then I, uh, got carried away.

$ make help # awks Makefile itself.
## nictoforth is an x86 bootsector forth that: (...)

## target files you can make: (...)

## development phonies: (...)

## these phonies filter slices of the source:
words:    # compact list of the implemented forth words. [!]
teaser1:  # the interpreter routine. the heart of a forth. [!]
teaser2:  # the bootstrap. *terrifying* and heavily documented.
design:   # example, memory map, registers, control flow. [!]
reading:  # source format conventions.
glossary: # labels that implement words, with stack effects.
names:    # all labels, variables, macros.
skel:     # control flow: labels, jumps, calls, rets. [!]
terse:    # just the code, no asides.
notes:    # anchored note contents, tricky highlights.
doc:      # the main comment text, no code.
xrefs:    # inventory cross-ref anchors, for maintenance.
help:     # this list. [!] marks important targets.

## try:
##  $ make words # or teaser1 or design or ...
##  $ make skel | bat -l nasm # or: | less
##  $ make terse >o/terse.asm
$

Yeahhhh this is way way over-engineered for purpose. But damn it was fun to write.

Repo, Makefile main/permalink, r/Forth post.

Have a poke through, see if you can pluck anything. Obviously generating docs is not new, but have you ever given this many views of the same source? Would you find these targets useful if you wanted to come up to speed on the project?

The Forth itself is currently 496 bytes of x86.

Per the "more than a small portion" bit in rule 4, I'm confident I can leave out the AI disclaimer. It's my hobby project, the working and the thinking are the fun part, but: I did consult with AI, out of curiosity. First time touching the things. If you care, search the README for "LLM," I have a whole damn rant.

Unfortunately I'm pretty ignorant of alternatives per rule 8, at least as far as doc generating goes. I'm just a hobbyist. For Forths, though, I talk a lot about Milliforth, Sectorforth, durexForth, Miniforth, DuskOS (check the Tumble Forth blog, it's how I fell into this rabbit hole!). Those first two are my direct ancestors.

I am a bot, and this action was performed automatically. Please contact the moderators of this subreddit if you have any questions or concerns.