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: Wed, 18 Aug 2021 15:31:18 +0300 Message-ID: <831r6r53zd.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> 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="34338"; 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 Wed Aug 18 14:33:03 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 1mGKkg-0008gT-0U for ged-emacs-devel@m.gmane-mx.org; Wed, 18 Aug 2021 14:33:02 +0200 Original-Received: from localhost ([::1]:58766 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mGKke-0006Ky-NC for ged-emacs-devel@m.gmane-mx.org; Wed, 18 Aug 2021 08:33:00 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:47008) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mGKj0-0005O0-44 for emacs-devel@gnu.org; Wed, 18 Aug 2021 08:31:18 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:44980) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mGKiz-0005ff-LS; Wed, 18 Aug 2021 08:31:17 -0400 Original-Received: from 84.94.185.95.cable.012.net.il ([84.94.185.95]:1991 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 1mGKiy-0006Ve-MD; Wed, 18 Aug 2021 08:31:17 -0400 In-Reply-To: <6EB979D9-EDD7-4F4B-B3CF-8FDC345F6E42@gmail.com> (message from Yuan Fu on Tue, 17 Aug 2021 20:24:55 -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:272561 Archived-At: > From: Yuan Fu > Date: Tue, 17 Aug 2021 20:24:55 -0700 > Cc: emacs-devel@gnu.org > > > No, please don't use TS-specific chapter names. In the text, you can > > tell that the functions you describe require the tree-sitter library, > > but the chapter and section names should ideally be neutral, so we > > could later add stuff provided by other libraries, like LSP. > > Ok, then can I mention tree-sitter in section titles? The tentative sections are: > > * 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? > How would we later add manual for other tools like LSP? It depends on how different they are. If they are sufficiently similar, we could describe them both in the same sections. > Maybe I should add a tree-sitter section and move all these into tree-sitter’s subsections? Then the structure would be like > > Chapter: Parsing Program Sources > Sections: > - tree-sitter > - Language definitions > - Using parsers > ... > - LSP > - some other tool IMO, this makes the manual harder to use, because one needs to consult two or more sections where ideally one should suffice. I wouldn't worry about this stuff too much at this point, we can always reconsider later. Thanks.