From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: Writing manuals Date: Tue, 17 Aug 2021 14:37:17 +0300 Message-ID: <83czqc715e.fsf@gnu.org> References: <60B2E271-2E91-4906-940E-425A76ED0DCD@gmail.com> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="10924"; mail-complaints-to="usenet@ciao.gmane.io" Cc: emacs-devel@gnu.org To: Yuan Fu Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Tue Aug 17 13:37:54 2021 Return-path: Envelope-to: ged-emacs-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1mFxPm-0002hh-EL for ged-emacs-devel@m.gmane-mx.org; Tue, 17 Aug 2021 13:37:54 +0200 Original-Received: from localhost ([::1]:60434 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mFxPk-0003ic-Pn for ged-emacs-devel@m.gmane-mx.org; Tue, 17 Aug 2021 07:37:52 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:39372) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mFxPG-0002yT-Rh for emacs-devel@gnu.org; Tue, 17 Aug 2021 07:37:22 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:53334) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mFxPG-0006Yy-L9; Tue, 17 Aug 2021 07:37:22 -0400 Original-Received: from 84.94.185.95.cable.012.net.il ([84.94.185.95]:2194 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mFxPG-0007Nv-89; Tue, 17 Aug 2021 07:37:22 -0400 In-Reply-To: <60B2E271-2E91-4906-940E-425A76ED0DCD@gmail.com> (message from Yuan Fu on Mon, 16 Aug 2021 23:42:11 -0700) X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.io gmane.emacs.devel:272483 Archived-At: > From: Yuan Fu > 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.