Re: Writing manuals

[Eli Zaretskii]

> From: Yuan Fu <casouri@gmail.com>
> Date: Mon, 16 Aug 2021 23:42:11 -0700
> 
> I want to start writing manuals for tree-sitter api (since I don’t expect 
> much change in that part) and I have some questions:
> 
> 1. It seems that I need to write description for each function again, apart 
> from the doc string that I already wrote.  Any tips to make it easier? (I 
> imagine in many cases I can just copy the doc string’s content?)

If you are going to just copy the doc strings, the value of the manual
will not be high, perhaps not even high enough to justify a manual.  A
good manual doesn't repeat doc strings, it (a) describes the APIs in
more detail, preferably with useful examples; and (b) includes textual
"glue" between the API descriptions that facilitates reading the
manual by a person who needs to study the API for the first time (as
opposed to use it as a reference).

IOW, a good manual should have a meaningful introduction and overview
chapters, and should describe the APIs in some logical order, with
"continuity" text that tells a story, not just lists the functions and
variables one by one.

> 2. How do I refer to some manual node in the doc string?

This is described in the node "Documentation Tips" of the ELisp
manual.

> 3. Where should I put the tree-sitter node in the manual?

You mean, in the ELisp manual?  I think each group of APIs should be
described where it belongs: the fontification-related APIs where
font-lock is described, indentation-related APIs where indentation
facilities are documented, etc.

> 4. Any general tips I should know before starting? doc/lispref/README doesn’t 
> say anything helpful.

General tips about using Texinfo are in the Texinfo manual, they are
not specific to Emacs.  If you have more specific questions, please
ask them.