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: Thu, 19 Aug 2021 19:10:01 +0300 Message-ID: <83lf4x1kme.fsf@gnu.org> References: <60B2E271-2E91-4906-940E-425A76ED0DCD@gmail.com> <83czqc715e.fsf@gnu.org> <502702DF-70A7-4FCC-93FD-08E984673832@gmail.com> <83tujo56oj.fsf@gnu.org> <83o89v6hsd.fsf@gnu.org> <83eear5vys.fsf@gnu.org> <6EB979D9-EDD7-4F4B-B3CF-8FDC345F6E42@gmail.com> <831r6r53zd.fsf@gnu.org> 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="32701"; 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 Thu Aug 19 18:11:13 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 1mGkdN-0008Fm-Jv for ged-emacs-devel@m.gmane-mx.org; Thu, 19 Aug 2021 18:11:13 +0200 Original-Received: from localhost ([::1]:46236 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mGkdM-0008KC-3R for ged-emacs-devel@m.gmane-mx.org; Thu, 19 Aug 2021 12:11:12 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:51916) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mGkcX-0007Yi-Jf for emacs-devel@gnu.org; Thu, 19 Aug 2021 12:10:21 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:52070) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mGkcX-00060D-Ay; Thu, 19 Aug 2021 12:10:21 -0400 Original-Received: from 84.94.185.95.cable.012.net.il ([84.94.185.95]:4470 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 1mGkcV-0005l2-Sp; Thu, 19 Aug 2021 12:10:21 -0400 In-Reply-To: (message from Yuan Fu on Thu, 19 Aug 2021 08:59:32 -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:272679 Archived-At: > From: Yuan Fu > Date: Thu, 19 Aug 2021 08:59:32 -0700 > Cc: Emacs Devel > > >> * Language definitions:: Loading tree-sitter language definitions. > >> * Using parsers:: Introduction to parsers. > >> * Accessing nodes:: Accessing syntax nodes. > >> * Pattern matching:: Pattern matching with query patterns. > >> * Query syntax:: Introducing pattern matching query syntax. > >> * Multiple languages:: Parse buffers written in multiple languages. > >> * API correspondence:: Correspondence between C API and ELisp API. > >> * Parse a string:: Parse a single string. > >> > >> They are all tree-sitter specific. > > > > What's wrong with the section names you show above? > > Nothing wrong, just that if we want to add manual for other parsing tools, there could be clashes in title: maybe LSP returns syntax nodes, too, but “Accessing nodes” section is all about tree-sitter nodes. But we’ll worry about that later, as you suggested. My idea is to put the documentation of other APIs for the same purpose in the same section, so there shouldn't be a clash, because there won't be multiple sections describing similar facilities, there will be just one. > Another problem I discovered when writing the manual is that, my explanation of the query syntax is similar to the official documentation of tree-sitter. Will there by copyright concerns? I’ve written the section describing query syntax, and I’ll write another section describing the grammar definition, these two sections will be similar to their tree-sitter official documentation counterparts, because they cover exactly the same thing. Well, I can only suggest to use different wording. Since you are describing Lisp interfaces, some phrases will be different by necessity, and others because we have a certain style when we describe APIs (you should be able to pick up that style by looking in the existing descriptions in the manual). > Perhaps it is best if you can see what I’ve write and compare that with the official documentation. I (force) pushed the latest code to GitHub. I put the manual in parsing.texi. The section describing the query syntax is (elisp)Parsing Program Source > Pattern matching. The official documentation is at https://tree-sitter.github.io/tree-sitter/using-parsers#pattern-matching-with-queries What is the URL for parsing.texi? I don't think I have it. Thanks.