Either that or a REPL shell with heavy diagnostics. Good error messages are very challenging - trying to grok intent to decode where actual error is probably NP-complete.

In a way fasmg/fasm2 are this. Both the macros and calminstructions are more verbose and featureful - from two different perspectives. Much syntax decoration remains to enable/modify some features.

I can't change the documentation for him, his character is in that text and even though it doesn't look like it, that character strongly advertises fasm and it would be 100% wrong for me to change that text. I can rather make him aware that it can be done, and then he will hopefully do it himself.

The way he writes in the documentation is a bit "far-fetched" but I also understand why and it is to advertise that he is a proper and tidy person, which in turn creates an impression on those who download it.

I think that fasm has been around so long that people know who he is, and that the time to shrink the text has come. The old documentation should be put in an archive on the website that people can look back at with a "historical" perspective.

Every year a goal should be set to (First count the words in the documentation) and then have a goal to reduce the number of words by 10% each year. It can be done slowly or it can be done quickly, all up to preference.

1 goal should be emphasized during the text reduction:

The new text must be even more understandable than the old one. Do you get it, the new text is not just supposed to cover everything logically, it's supposed to make the reader UNDERSTAND. When you have provided all the bits for the reader to be able to understand logically, you're not finished, you're also supposed to save his time.

And then it is up to the author to aim to just reduce the NUMBER of words by having a tool that counts the words, and that's it. Every time he makes a tiny change, the goal is to reduce the NUMBER of words.

Any time you make a slight change in the doc, make it a habit to reduce by a couple of words from the text that you will not change (Which leaves you totally free to pick any random text), and then keep the new text as slim as possible.

* Reduce number of words
* New text more clear, more understandable, it can always be improved even if you don't believe it

Regular expressions can be used to replace special word phrases with simpler ones.

Words represents your thoughts, examples represents the world. Too much of your own thoughts is not good unless you can express yourself in one sentence.

Before you know it, it will be reduced to half in size and it is so pleasurable to have a precise manual. When you look up into it, it looks more like the index of another manual, but you understand everything even from that tiny index.

When the manual looks like a fairytale, it has failed. I'm not saying that this particular manual looks like one, but, just making a point. Programming is a STRUCTURED lifestyle, it must be well structured with as little explanation as possible. The explanation can not replace the habits, and when the habits are in place, they will hate the explanation.

The explanation is one-time, the reference is always. So the balance must be 10-90, you must be VERY precise and VERY short.

fasm.pdf -> 50396 wordcount.

See it as a policy, a lifestyle.
Thanks

in fasm1, i cannot see whats wrong with the documentation, i dont know about other assemblers tho. (here assemblers refer to ones made by Tomasz)

i mean it is pretty readable and understandable, perhaps it needs more technical and precise details, or even spitting few words about some internal stuff.

There is nothing wrong with it, we are only going to optimize it.

i dont think i understand how shrinking the docs "optimizes" it, unless this time you mean something different with "optimize", then it is very vague and possibly make the docs useless

Shrinking is one part of it, making it clearer and more understandable is the other part of it.

Optimizes the manual resource, optimized productivity. There is nothing wrong with the manual.

assembly language plus printf() equals "they stopped programming and relied on AI instead."

I like FASM2 because I like to have powerful macros. When a language lacks macros I feel that something is missing. It was well worth it to switch from TASM to FASM2.

As a new FASMite I agree that the FASMG manual can be improved but with more examples and more repetition. I've read it now 3 times and it finally starts to click a bit. I personally think the manual it too short/compressed.

I consider the Borland Turbo Assembler 2.0 User Guide to be excellent and it's 518 pages. That book was, most likely, written by several people though and made by a commercial company. The TASM manual being so long with examples and repetition actually made it a fast easy read.

My point is that shortening a manual does not necessarily mean it's saving any one's time.

I think shortening the User Manual would not be good. A Quick Reference can be short but not a User Manual imo.

Guys, I use a thin C preprocessor abstraction, and I can assemble reasonably simple x86_64 assembly for fasm/gas/nasm.