Re: Writing manuals

[Yuan Fu <casouri@gmail.com>]

> On Aug 17, 2021, at 4:37 AM, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> 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.

Ah, got it. I know how to write it now.

> 
>> 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.

Thanks.

> 
>> 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.

I was referring to tree-sitter API, i.e., wrappers of tree-sitter functions. They are the functions that I expect to not change much. Font-lock and indent API are still undecided for the most part. So where should I put the manual of tree-sitter functions? In that node I will talk about what can tree-sitter do and how to use the parser and parse-tree, 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.

Ok.

Yuan