Writing manuals

Writing manuals

[Yuan Fu]

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?)

2. How do I refer to some manual node in the doc string?

3. Where should I put the tree-sitter node in the manual?

4. Any general tips I should know before starting? doc/lispref/README doesn’t say anything helpful.

Yuan

Re: Writing manuals

[Eli Zaretskii]

> 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.

> 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.

Re: Writing manuals

[Yuan Fu]

> 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

Re: Writing manuals

[Eli Zaretskii]

> From: Yuan Fu <casouri@gmail.com>
> Date: Tue, 17 Aug 2021 09:28:53 -0700
> Cc: emacs-devel <emacs-devel@gnu.org>
> 
> >> 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.

I'm not sure I see the difference.  We have syntax-ppss
etc. documented in the ELisp manual; how are TS-related APIs
different?

Re: Writing manuals

[Yuan Fu]

> On Aug 17, 2021, at 10:20 AM, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> From: Yuan Fu <casouri@gmail.com>
>> Date: Tue, 17 Aug 2021 09:28:53 -0700
>> Cc: emacs-devel <emacs-devel@gnu.org>
>> 
>>>> 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.
> 
> I'm not sure I see the difference.  We have syntax-ppss
> etc. documented in the ELisp manual; how are TS-related APIs
> different?

It certainly should be in the ELisp manual, I mean which node should I put tree-sitter API’s under? Text?

Yuan

Re: Writing manuals

[Eli Zaretskii]

> From: Yuan Fu <casouri@gmail.com>
> Date: Tue, 17 Aug 2021 11:10:06 -0700
> Cc: emacs-devel@gnu.org
> 
> > I'm not sure I see the difference.  We have syntax-ppss
> > etc. documented in the ELisp manual; how are TS-related APIs
> > different?
> 
> It certainly should be in the ELisp manual, I mean which node should I put tree-sitter API’s under? Text?

No, "Text" is for other stuff.  I think a separate chapter, something
like "Parsing Program Source".  As long as you are talking about
general-purpose parsing functions, not their use for font-lock etc.

Re: Writing manuals

[Yuan Fu]

> On Aug 17, 2021, at 11:35 AM, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> From: Yuan Fu <casouri@gmail.com>
>> Date: Tue, 17 Aug 2021 11:10:06 -0700
>> Cc: emacs-devel@gnu.org
>> 
>>> I'm not sure I see the difference.  We have syntax-ppss
>>> etc. documented in the ELisp manual; how are TS-related APIs
>>> different?
>> 
>> It certainly should be in the ELisp manual, I mean which node should I put tree-sitter API’s under? Text?
> 
> No, "Text" is for other stuff.  I think a separate chapter, something
> like "Parsing Program Source".  As long as you are talking about
> general-purpose parsing functions, not their use for font-lock etc.

Ok, I would name it “Parsing Program Source with Tree-sitter”, because it isn’t a generic parsing facility, but really a tree-sitter integration.

Another question, do I need to @vindex a variable every time I mention it, or I only need to @vindex it once, at where I explain the variable?

Yuan

Re: Writing manuals

[Eli Zaretskii]

> From: Yuan Fu <casouri@gmail.com>
> Date: Tue, 17 Aug 2021 13:08:52 -0700
> Cc: emacs-devel@gnu.org
> 
> > No, "Text" is for other stuff.  I think a separate chapter, something
> > like "Parsing Program Source".  As long as you are talking about
> > general-purpose parsing functions, not their use for font-lock etc.
> 
> Ok, I would name it “Parsing Program Source with Tree-sitter”, because it isn’t a generic parsing facility, but really a tree-sitter integration.

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.

> Another question, do I need to @vindex a variable every time I mention it, or I only need to @vindex it once, at where I explain the variable?

The latter.  The other places, if they are in another node, should
have a cross-reference to that single description.

Re: Writing manuals

[Yuan Fu]

> On Aug 17, 2021, at 7:26 PM, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> From: Yuan Fu <casouri@gmail.com>
>> Date: Tue, 17 Aug 2021 13:08:52 -0700
>> Cc: emacs-devel@gnu.org
>> 
>>> No, "Text" is for other stuff.  I think a separate chapter, something
>>> like "Parsing Program Source".  As long as you are talking about
>>> general-purpose parsing functions, not their use for font-lock etc.
>> 
>> Ok, I would name it “Parsing Program Source with Tree-sitter”, because it isn’t a generic parsing facility, but really a tree-sitter integration.
> 
> 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. How would we later add manual for other tools like LSP? 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

Yuan

Re: Writing manuals

[Eli Zaretskii]

> From: Yuan Fu <casouri@gmail.com>
> 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.

Re: Writing manuals

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > How would we later add manual for other tools like LSP?

Please ask me before writing something about LSP for a GNU manual.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Writing manuals

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Date: Wed, 18 Aug 2021 22:35:25 -0400
> Cc: casouri@gmail.com, emacs-devel@gnu.org
> 
> Please ask me before writing something about LSP for a GNU manual.

Could you please tell a few more details?  What are the aspects of LSP
that are problematic and/or require to ask you about?  We are talking
about LSP all the time, so some references to it could easily enough
"sneak" into our documentation without anyone paying attention.  We
need to understand the issue in more detail to DTRT here.

Thanks.

Re: Writing manuals

[Yuan Fu]

> On Aug 18, 2021, at 5:31 AM, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> From: Yuan Fu <casouri@gmail.com>
>> 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?

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.

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.

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


Yuan

Re: Writing manuals

[Eli Zaretskii]

> From: Yuan Fu <casouri@gmail.com>
> Date: Thu, 19 Aug 2021 08:59:32 -0700
> Cc: Emacs Devel <emacs-devel@gnu.org>
> 
> >> * 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.

Re: Writing manuals

[Fu Yuan]

[-- Attachment #1: Type: text/plain, Size: 3091 bytes --]



> 在 2021年8月19日，上午9:10，Eli Zaretskii <eliz@gnu.org> 写道：
> 
> 
>> 
>> From: Yuan Fu <casouri@gmail.com>
>> Date: Thu, 19 Aug 2021 08:59:32 -0700
>> Cc: Emacs Devel <emacs-devel@gnu.org>
>> 
>>>> * 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.

Ok
> 
>> 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).

For ELisp functions, definitely, and I wasn’t talking about that part. For query syntax and language definition syntax, because I and tree-sitter doc are talking about the exact same thing, it is harder. I certainly rephrased, and I tried to come up with different examples. I’m just not sure if that is enough (INAL).
> 
>> 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.

I have it on “ts” branch.

https://github.com/casouri/emacs/blob/ts/doc/lispref/parsing.texi

Thanks

Yuan

[-- Attachment #2: Type: text/html, Size: 5987 bytes --]

Re: Writing manuals

[Eli Zaretskii]

> From: Fu Yuan <casouri@gmail.com>
> Date: Thu, 19 Aug 2021 09:29:28 -0700
> Cc: emacs-devel@gnu.org
> 
>  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.
> 
> I have it on “ts” branch.
> 
> https://github.com/casouri/emacs/blob/ts/doc/lispref/parsing.texi

Thanks, I don't see an issue with your text, it's quite different from
the TS docs.

Re: Writing manuals

[Yuan Fu]

Here is the first page/node of tree-sitter’s manual, do you think the third paragraph is redundant? It basically connects each menu items together, but it also feels like just repeating the menu. And, IIUC nodes are uniquely named in a manual, I think maybe it’s not a good idea to use generic node names like “Language Definition”, “Pattern Matching”, etc, any suggestions?

The tree-sitter library
(@uref{https://tree-sitter.github.io/tree-sitter/}) implements an
incremental parser that supports a wide range of programming
languages.  A tree-sitter parser can generate and update a
@dfn{concrete syntax tree}.  In a syntax tree, text is no longer a
one-dimensional stream but a structured tree of nodes, where each node
representing a piece of text.  Thus a syntax tree can enable
interesting features like precise fontification and indentation,
structured editing, etc.

Apart from tree-sitter, Emacs provides a simple parsing facility for
parsing balanced expressions.  @xref{Parsing Expressions}.

TODO: redundant?
To access the syntax tree of the text in a buffer, we need to first
load a language definition and create a parser with it.  Next, we can
query the parser for specific nodes in the syntax tree.  Then, we can
access various information about the node.  Finally, we can
pattern-match a node with a powerful syntax.  The following sections
explain how to do each of the tasks in detail.  The last section
compares the differences between tree-sitter's C API and the functions
provided by Emacs Lisp, and the correspondence between all
tree-sitter's C functions and their Emacs Lisp counterparts.

@menu
* Language Definitions::   Loading tree-sitter language definitions.
* Using Parser::           Introduction to parsers.
* Retrieving Node::        Retrieving node from syntax tree.
* Accessing Node::         Accessing node information.
* Pattern Matching::       Pattern matching with query patterns.
* Multiple Languages::     Parse text written in multiple languages.
* Tree-sitter C API::      A map from the C API to the ELisp API.
@end menu

Yuan

Re: Writing manuals

[Eli Zaretskii]

> From: Yuan Fu <casouri@gmail.com>
> Date: Fri, 3 Sep 2021 22:35:40 -0700
> Cc: emacs-devel@gnu.org
> 
> Here is the first page/node of tree-sitter’s manual, do you think the third paragraph is redundant?

No, I think it provides a useful overview of the process, and is
concise enough not to get in the way.  Good job!

> And, IIUC nodes are uniquely named in a manual, I think maybe it’s not a good idea to use generic node names like “Language Definition”, “Pattern Matching”, etc

Why not?  Once again, if we ever support other similar libraries, we
should strive to have similar facilities described in the same nodes,
not in separate nodes.

Re: Writing manuals

[Yuan Fu]

> On Sep 4, 2021, at 12:33 AM, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> From: Yuan Fu <casouri@gmail.com>
>> Date: Fri, 3 Sep 2021 22:35:40 -0700
>> Cc: emacs-devel@gnu.org
>> 
>> Here is the first page/node of tree-sitter’s manual, do you think the third paragraph is redundant?
> 
> No, I think it provides a useful overview of the process, and is
> concise enough not to get in the way.  Good job!

Thank you for your kind words :-)

> 
>> And, IIUC nodes are uniquely named in a manual, I think maybe it’s not a good idea to use generic node names like “Language Definition”, “Pattern Matching”, etc
> 
> Why not?  Once again, if we ever support other similar libraries, we
> should strive to have similar facilities described in the same nodes,
> not in separate nodes.

Not general in that sense, but in the sense that some other Emacs feature unrelated to parsing could need that name. For example, pcase is a kind of “Pattern Matching”, an input method could have a “Language Definition”.

Yuan

Re: Writing manuals

[Eli Zaretskii]

> From: Yuan Fu <casouri@gmail.com>
> Date: Sat, 4 Sep 2021 08:48:36 -0700
> Cc: emacs-devel@gnu.org
> 
> >> And, IIUC nodes are uniquely named in a manual, I think maybe it’s not a good idea to use generic node names like “Language Definition”, “Pattern Matching”, etc
> > 
> > Why not?  Once again, if we ever support other similar libraries, we
> > should strive to have similar facilities described in the same nodes,
> > not in separate nodes.
> 
> Not general in that sense, but in the sense that some other Emacs feature unrelated to parsing could need that name. For example, pcase is a kind of “Pattern Matching”, an input method could have a “Language Definition”.

I wouldn't worry about that, at least not now.  "Pattern", "matching",
"language", etc. are terms that are overloaded many times, and if we'd
worry about this, we'd be unable to come up with useful node names.
But you could say "Pattern Matching with Nodes" and "Programming
Language Definitions" instead, if you think that's better.

Re: Writing manuals

[Yuan Fu]

> On Sep 5, 2021, at 7:30 AM, John Yates <john@yates-sheets.org> wrote:
> 
> As I read this I feel there is an introductory paragraph missing.
> 
> Clearly there is a, potentially growing, collection of technologies
> for deriving the concrete syntax of the text in a buffer.  An opening
> paragraph would present the general concept of concrete syntax and
> then enumerate the available offerings.  The only details provided at
> this point would be how one might choose between those offerings.
> 
> /John

I’ll add an introductory paragraph, thanks for the suggestion :-)

Yuan