Like most gnu projects, the manual is very good, the problem is it's a manual and just a reference for looking up specific things, it doesn't really explain how to use m4. I'm not sure if this is by design or lack of effort in that direction.
Take divert for instance like a mentioned above, it's one of the foundations that make m4 good but it's not mentioned until chapter 10 and even then the examples are hard to follow and not particularly good, they could have gone with something more real world:
define(INDEX, 1)
define(BODY, 2)
define(ADD_CHAPTER, heading, text
divert(INDEX)
heading
divert(BODY)
heading
text
)
#guts of the generation go here
ADDCHAPTER('one', 'paragraph one')
ADDCHAPTER('two', 'paragraph two')
undivert(INDEX)
unidvert(BODY)
The syntax there isn't correct, but I think an example like that shows off how and why you'd use this feature more than the examples in the documentation.
Take divert for instance like a mentioned above, it's one of the foundations that make m4 good but it's not mentioned until chapter 10 and even then the examples are hard to follow and not particularly good, they could have gone with something more real world:
The syntax there isn't correct, but I think an example like that shows off how and why you'd use this feature more than the examples in the documentation.