Re: Writing manuals

[Yuan Fu <casouri@gmail.com>]

Here is the first page/node of tree-sitter’s manual, do you think the third paragraph is redundant? It basically connects each menu items together, but it also feels like just repeating the menu. And, IIUC nodes are uniquely named in a manual, I think maybe it’s not a good idea to use generic node names like “Language Definition”, “Pattern Matching”, etc, any suggestions?

The tree-sitter library
(@uref{https://tree-sitter.github.io/tree-sitter/}) implements an
incremental parser that supports a wide range of programming
languages.  A tree-sitter parser can generate and update a
@dfn{concrete syntax tree}.  In a syntax tree, text is no longer a
one-dimensional stream but a structured tree of nodes, where each node
representing a piece of text.  Thus a syntax tree can enable
interesting features like precise fontification and indentation,
structured editing, etc.

Apart from tree-sitter, Emacs provides a simple parsing facility for
parsing balanced expressions.  @xref{Parsing Expressions}.

TODO: redundant?
To access the syntax tree of the text in a buffer, we need to first
load a language definition and create a parser with it.  Next, we can
query the parser for specific nodes in the syntax tree.  Then, we can
access various information about the node.  Finally, we can
pattern-match a node with a powerful syntax.  The following sections
explain how to do each of the tasks in detail.  The last section
compares the differences between tree-sitter's C API and the functions
provided by Emacs Lisp, and the correspondence between all
tree-sitter's C functions and their Emacs Lisp counterparts.

@menu
* Language Definitions::   Loading tree-sitter language definitions.
* Using Parser::           Introduction to parsers.
* Retrieving Node::        Retrieving node from syntax tree.
* Accessing Node::         Accessing node information.
* Pattern Matching::       Pattern matching with query patterns.
* Multiple Languages::     Parse text written in multiple languages.
* Tree-sitter C API::      A map from the C API to the ELisp API.
@end menu

Yuan