[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Writing manuals
From: |
Yuan Fu |
Subject: |
Re: Writing manuals |
Date: |
Tue, 17 Aug 2021 09:28:53 -0700 |
> 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
- Writing manuals, Yuan Fu, 2021/08/17
- Re: Writing manuals, Eli Zaretskii, 2021/08/17
- Re: Writing manuals,
Yuan Fu <=
- Re: Writing manuals, Eli Zaretskii, 2021/08/17
- Re: Writing manuals, Yuan Fu, 2021/08/17
- Re: Writing manuals, Eli Zaretskii, 2021/08/17
- Re: Writing manuals, Yuan Fu, 2021/08/17
- Re: Writing manuals, Eli Zaretskii, 2021/08/17
- Re: Writing manuals, Yuan Fu, 2021/08/17
- Re: Writing manuals, Eli Zaretskii, 2021/08/18
- Re: Writing manuals, Richard Stallman, 2021/08/18
- Re: Writing manuals, Eli Zaretskii, 2021/08/19
- Re: Writing manuals, Yuan Fu, 2021/08/19