From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Yuan Fu Newsgroups: gmane.emacs.devel Subject: Re: Writing manuals Date: Tue, 17 Aug 2021 09:28:53 -0700 Message-ID: <502702DF-70A7-4FCC-93FD-08E984673832@gmail.com> References: <60B2E271-2E91-4906-940E-425A76ED0DCD@gmail.com> <83czqc715e.fsf@gnu.org> Mime-Version: 1.0 (Mac OS X Mail 14.0 \(3654.60.0.2.21\)) Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="28751"; mail-complaints-to="usenet@ciao.gmane.io" Cc: emacs-devel To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Tue Aug 17 18:30:02 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 1mG1yU-00079T-13 for ged-emacs-devel@m.gmane-mx.org; Tue, 17 Aug 2021 18:30:02 +0200 Original-Received: from localhost ([::1]:47906 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mG1yS-0008NO-Ta for ged-emacs-devel@m.gmane-mx.org; Tue, 17 Aug 2021 12:30:00 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:58178) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mG1xV-0006wo-MI for emacs-devel@gnu.org; Tue, 17 Aug 2021 12:29:01 -0400 Original-Received: from mail-pj1-x102e.google.com ([2607:f8b0:4864:20::102e]:37689) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1mG1xU-0000DT-2L; Tue, 17 Aug 2021 12:29:01 -0400 Original-Received: by mail-pj1-x102e.google.com with SMTP id cp15-20020a17090afb8fb029017891959dcbso6147131pjb.2; Tue, 17 Aug 2021 09:28:56 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=mime-version:subject:from:in-reply-to:date:cc :content-transfer-encoding:message-id:references:to; bh=KMYZXJOZigSH1SflpmDJeZvzxxO5/pqJjlBT+cOrEak=; b=AFghcXyPlD62t57hT7FiHf+8rTrhjp9YWzKGU1kHdA+lVvbVREfW+EUqrrHwAmD8TG b1ZT0I+MSHPA7CxbFBjAvieQKlJMTsbr6AX2hGHDTEqGV5hEYFQcaNajAmmSSL7g6HYr 6kw/l/Jggmf4CRwrd+GgnwclVZwHAFqwnrkHD4Yj/Y7AHqid2/1ULXjhFGU7vt3a/8MH mMF/1q42CbyPedHiXxUp80DN6uGIcbgjDSTfuOdFfIqTvD3RHcIuwCpUQi6GV25qWvQr h4uuwm27cHLuvPpantdVrSrf80UPxzqLFYKiWQCCmONbGAI8O2iuQQbMtw8SfrQoj/wG 9ocg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:subject:from:in-reply-to:date:cc :content-transfer-encoding:message-id:references:to; bh=KMYZXJOZigSH1SflpmDJeZvzxxO5/pqJjlBT+cOrEak=; b=S34588Jg9f/Hyul3NCfcXVOglQe4kdqnHJFgdUKUzZKFEO0q6Vp1xaqDzPvAIqDwl0 QQiIFVgHTwcfqFsQ0g7no0Rv4YattnMKW937Qr67Pp2k96ODfDr+PJTcPvVG4ii2jaI6 f1T6fx97FgoeQus7FBVq2ILSj6irykl6MJ4OdGN9cmgWW0fZfSaRQncZDyb0S8CewNdO L5V/tbVSfVis/7/P/1MRifFXGhMfqahbG8CGKOFBDBLPJ9NfEg+NlMNg0aC3g/0akrMF C0FUI2ZN/9R46ilh4DcViurkubrfJeICpAwd/PhjZKjJNnMmGC2NivSshoo7pc5Sc3pF JRSg== X-Gm-Message-State: AOAM530o9PTxzgVSz+ruNK8Dss18EjQLzudd4SUEO/vE/eKfT0i0RIrY pft4rvxVcY47n4cDoSuqQ+VPubsTh2E= X-Google-Smtp-Source: ABdhPJxVlseglp/K32iFexHuBnDunenJC9m8XB4Fr8maSdKBCJ62M3q6QSLk2qlIrSmqAbpxz+k5nQ== X-Received: by 2002:a63:1542:: with SMTP id 2mr4252816pgv.102.1629217735618; Tue, 17 Aug 2021 09:28:55 -0700 (PDT) Original-Received: from 2603-8000-d900-871b-4c36-40c4-14eb-a734.res6.spectrum.com (2603-8000-d900-871b-4c36-40c4-14eb-a734.res6.spectrum.com. [2603:8000:d900:871b:4c36:40c4:14eb:a734]) by smtp.gmail.com with ESMTPSA id q3sm3997602pgf.18.2021.08.17.09.28.54 (version=TLS1_2 cipher=ECDHE-ECDSA-AES128-GCM-SHA256 bits=128/128); Tue, 17 Aug 2021 09:28:55 -0700 (PDT) In-Reply-To: <83czqc715e.fsf@gnu.org> X-Mailer: Apple Mail (2.3654.60.0.2.21) Received-SPF: pass client-ip=2607:f8b0:4864:20::102e; envelope-from=casouri@gmail.com; helo=mail-pj1-x102e.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action 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:272500 Archived-At: > On Aug 17, 2021, at 4:37 AM, Eli Zaretskii wrote: >=20 >> From: Yuan Fu >> Date: Mon, 16 Aug 2021 23:42:11 -0700 >>=20 >> I want to start writing manuals for tree-sitter api (since I don=E2=80=99= t expect much change in that part) and I have some questions: >>=20 >> 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=E2=80=99s = content?) >=20 > 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). >=20 > 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. >=20 >> 2. How do I refer to some manual node in the doc string? >=20 > This is described in the node "Documentation Tips" of the ELisp > manual. Thanks. >=20 >> 3. Where should I put the tree-sitter node in the manual? >=20 > 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. >=20 >> 4. Any general tips I should know before starting? doc/lispref/README = doesn=E2=80=99t say anything helpful. >=20 > 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