Rethink macro terminology

[gilch]

"Reader macros" run in the Lissp reader, while "compiler macros" run in the Hissp compiler. Simple, right? Except both of these terms mean something completely different in Common Lisp, so using them might cause confusion.

Common Lisp's "reader macros" get the raw character stream, while Lissp's act during parsing (after lexing), which is more similar to Clojure's tagged literals.

Also, Common Lisp's "compiler macros" are not the same as Common Lisp's "macros". Hissp's "compiler macros" are much like Common Lisp's "macros".

But then what should we do instead? Simply make a note of this in the docs? Name them something else? What? Tags and macros? Parse-time macros and compile-time macros? Lissp macros and Hissp macros? Atom macros and AST macros? That one doesn't seem quite right.

[gilch]

"Reader tags" and "Hissp macros". Maybe "tags" and "macros" for short.

Maybe "Lissp tags", except that sounds like "Lisp tags", which aren't really a thing. Names are hard. "Reader tags" might sound more like Clojure's "tagged literals", which are more similar than Common Lisp's "reader macros".

[mjobuda]

Yes, add a note. The macro stuff is confusing if you're new to it.
Take a critical look at the order in the tutorial assumining you know nothing about macros:
They are explained at https://hissp.readthedocs.io/en/latest/tutorial.html#macros
But it's not the first time they are mentioned. You start with reader macros, inject, qualified reader macros(i still don't know what qualified means) etc etc and then comes the simple explanation of compile time macros. From a didactic perspective for someone that don't know anything about macros it would be way easier to "get it" if you start with the simple exlanation found in the tutorial macro section together with the note on terminology and then go on with the more complex topic of reader macros.
In the tutorial you start with reader macros, then in the section called "macros" you start with a general explanation what macros are and go on with explaining hissp macros. No, no, no. That order makes no sense! If you don't know what macros are you should first get the general definition what a macro is. Then you can go on with the several types of macros in this system and a discussion of the terminology here and how it is different from other lisps. The current order that is now would make eventual sense if this would be a "reference manual". Then since the compilation process starts with the lissp reader you could start from there(and you could even assume that the reader already knows what macros are!). But it is called a tutorial, right? I admit that the puzzling and confusing aspects of this tutorial made it interesting for me and helped the total cognitive process, but I don't think that I am very representative here for the target audience. The terminology is good for me. Eventually lissp macros and hissp macros is also good since it reveals already in the name the scope of these instruments. "Tags" would only add additional confusion. Parse time macros and compile time macros doesn't feel clean to me either(you can call the lissp reader a reader if you wish but somebody else might call it a lissp to hissp compiler and hissp a hissp to python compiler. Recall that python is an interpreted language that gets compiled to interpreted bytecode. Confusing? All macros are done in the compilation step! Does it really make anything easier if you differetiate the compilation steps into parsing and compiling here? parsing is also a compilation step! You already defined in the beginning Lissp as one of possible readers so reader macro and compiler macros are fine. But the order in the tutorial is not ok for me).

[gilch]

Paragraphs, man. Even if it's one per sentence. Or bullets or something. I'm getting lost in the wall of text. I'll try to address these issues in the tutorial, but not before the 0.3 release.

The pieces of the language depend on each other, so it's hard to know what order to present them. I introduced the reader macros first because the compiler macro examples are using templates, which are made with the built-in reader macros ` , ,@ and $#. Those are a prerequisite.

To do it in the other order, I'd have to either split the exposition on the reader macros with just the template ones first, or explain the compiler macros without using templates at all. Maybe in readerless mode? I'd rather keep topics together as much as possible, but I did finally do a bit of topic splitting in the latest quickstart version.

I can add a more explicit definition of qualifiers/qualification/qualified.

I think calling the reader macros "tags" could reduce confusion, because you'd no longer be mixing up reader macros and compiler macros.

[gilch]

I'm trying to remember where I heard the term "fully qualified name", so I can decide how to define it in the docs, but it seems to be a pretty standard programming term already: https://en.wikipedia.org/wiki/Fully_qualified_name, which does fit my usage. I'll go with that sense.