Re: Writing manuals

[Eli Zaretskii <eliz@gnu.org>]

> From: Yuan Fu <casouri@gmail.com>
> Date: Tue, 17 Aug 2021 20:24:55 -0700
> Cc: emacs-devel@gnu.org
> 
> > No, please don't use TS-specific chapter names.  In the text, you can
> > tell that the functions you describe require the tree-sitter library,
> > but the chapter and section names should ideally be neutral, so we
> > could later add stuff provided by other libraries, like LSP.
> 
> Ok, then can I mention tree-sitter in section titles? The tentative sections are:
> 
> * Language definitions::    Loading tree-sitter language definitions.
> * Using parsers::           Introduction to parsers.
> * Accessing nodes::         Accessing syntax nodes.
> * Pattern matching::        Pattern matching with query patterns.
> * Query syntax::            Introducing pattern matching query syntax.
> * Multiple languages::      Parse buffers written in multiple languages.
> * API correspondence::      Correspondence between C API and ELisp API.
> * Parse a string::          Parse a single string.
> 
> They are all tree-sitter specific.

What's wrong with the section names you show above?

> How would we later add manual for other tools like LSP?

It depends on how different they are.  If they are sufficiently
similar, we could describe them both in the same sections.

> Maybe I should add a tree-sitter section and move all these into tree-sitter’s subsections? Then the structure would be like
> 
> Chapter: Parsing Program Sources
> Sections: 
> - tree-sitter
>   - Language definitions
>   - Using parsers
>   ...
> - LSP
> - some other tool

IMO, this makes the manual harder to use, because one needs to consult
two or more sections where ideally one should suffice.

I wouldn't worry about this stuff too much at this point, we can
always reconsider later.

Thanks.