> Of course, the manual itself is really very good!
I actually don't agree with this. It's really good as a "user guide", but it's not the best as a "reference manual". It does not always clearly define terms, it freely mixes technical terms and hand-waving language, the writing style tends toward an "expository prose" that makes it hard to find specific pieces of information. In general, it could do with some reorganization using the Diátaxis principles: https://diataxis.fr/
It does have pretty good indices, and the quick reference is very helpful. However the HTML version (can't speak for the others) needs a lot more anchors, to make it easy to cross-link to individual elements, rather than just to chapter headings.
Huh. I actually thought the manual was great, but you make excellent points that I happen to agree with.
I'm very comfortable with the manual now, when I need to look something up, but that's because I've spent years looking things up in it, so I have a fairly good idea where to find things. Even so, it's sometimes confusing, e.g. where to find the definition of automatic variables like `$@`, `$^` and the like? When I started learning Make I remember it being infuriatingly hard to find the entry about a topic of interest.
While the manual is great (as are most of GNU's major works!) compared to most of the software ecosystem [1], you're quite right that it can still improve a lot.
[1] It's kind of amazing how even a company like Apple can have some pretty underwhelming documentation, see today's post about ExtensionKit https://news.ycombinator.com/item?id=33409558
I actually don't agree with this. It's really good as a "user guide", but it's not the best as a "reference manual". It does not always clearly define terms, it freely mixes technical terms and hand-waving language, the writing style tends toward an "expository prose" that makes it hard to find specific pieces of information. In general, it could do with some reorganization using the Diátaxis principles: https://diataxis.fr/
It does have pretty good indices, and the quick reference is very helpful. However the HTML version (can't speak for the others) needs a lot more anchors, to make it easy to cross-link to individual elements, rather than just to chapter headings.