From drew.adams@oracle.com Fri Apr 24 13:36:43 2009 Received: (at submit) by emacsbugs.donarmstrong.com; 24 Apr 2009 20:36:44 +0000 X-Spam-Checker-Version: SpamAssassin 3.2.5-bugs.debian.org_2005_01_02 (2008-06-10) on rzlab.ucr.edu X-Spam-Level: X-Spam-Bayes: score:0.5 Bayes not run. spammytokens:Tokens not available. hammytokens:Tokens not available. X-Spam-Status: No, score=0.1 required=4.0 tests=FOURLA autolearn=no version=3.2.5-bugs.debian.org_2005_01_02 Received: from fencepost.gnu.org (fencepost.gnu.org [140.186.70.10]) by rzlab.ucr.edu (8.13.8/8.13.8/Debian-3) with ESMTP id n3OKaecx017316 for ; Fri, 24 Apr 2009 13:36:42 -0700 Received: from mx10.gnu.org ([199.232.76.166]:33583) by fencepost.gnu.org with esmtp (Exim 4.67) (envelope-from ) id 1LxS8W-0002RT-9v for emacs-pretest-bug@gnu.org; Fri, 24 Apr 2009 16:36:40 -0400 Received: from Debian-exim by monty-python.gnu.org with spam-scanned (Exim 4.60) (envelope-from ) id 1LxS8U-0000Y4-Di for emacs-pretest-bug@gnu.org; Fri, 24 Apr 2009 16:36:39 -0400 Received: from acsinet11.oracle.com ([141.146.126.233]:28941) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1LxS8T-0000XJ-Ro for emacs-pretest-bug@gnu.org; Fri, 24 Apr 2009 16:36:38 -0400 Received: from acsinet15.oracle.com (acsinet15.oracle.com [141.146.126.227]) by acsinet11.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n3OKabfr004280 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Fri, 24 Apr 2009 20:36:39 GMT Received: from acsmt707.oracle.com (acsmt707.oracle.com [141.146.40.85]) by acsinet15.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n3OKaY3Z007222 for ; Fri, 24 Apr 2009 20:36:35 GMT Received: from dradamslap1 (/98.210.250.59) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Fri, 24 Apr 2009 13:36:31 -0700 From: "Drew Adams" To: Subject: 23.0.92; Emacs manual, node Tags Date: Fri, 24 Apr 2009 13:36:31 -0700 Message-ID: <007501c9c51c$5a6c8f70$0200a8c0@us.oracle.com> MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Mailer: Microsoft Office Outlook 11 X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.3350 thread-index: AcnFHFnAuMj4HXmHR3enNlA/LJiJYw== X-Source-IP: acsinet15.oracle.com [141.146.126.227] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A010204.49F222D3.0046:SCFMA922111,ss=1,fgs=0 X-detected-operating-system: by monty-python.gnu.org: GNU/Linux 2.6 (newer, 1) The first sentence of this node doesn't sound right to me. At least it's not clear what is meant. "A "tags table" is a description of how a multi-file program is broken up into files." A multi-file program? What program would that be? There is no further mention of this. I don't understand this sentence, and I cannot imagine how it describes what a tags table is. Also confusing is the part that starts "When a file parsed by `etags' is generated from a different source file, like a C file generated from a Cweb source file,..." To understand this (and I don't), a reader needs to already understand what `etags' is and what its parsing amounts to, and s?he needs to know what Cweb is (I don't). Not to mention that it is mysterious what is meant by "a different source file" - different from what? One cannot understand this text without knowing how tags work, the role of "source files" in that, and so on. IOW, this doesn't help; it confuses. In GNU Emacs 23.0.92.1 (i386-mingw-nt5.1.2600) of 2009-03-30 on SOFT-MJASON Windowing system distributor `Microsoft Corp.', version 5.1.2600 configured using `configure --with-gcc (3.4)' From eliz@gnu.org Sat Apr 25 00:23:43 2009 Received: (at 3101-done) by emacsbugs.donarmstrong.com; 25 Apr 2009 07:23:43 +0000 X-Spam-Checker-Version: SpamAssassin 3.2.5-bugs.debian.org_2005_01_02 (2008-06-10) on rzlab.ucr.edu X-Spam-Level: X-Spam-Bayes: score:0.5 Bayes not run. spammytokens:Tokens not available. hammytokens:Tokens not available. X-Spam-Status: No, score=-3.0 required=4.0 tests=HAS_BUG_NUMBER autolearn=ham version=3.2.5-bugs.debian.org_2005_01_02 Received: from mtaout5.012.net.il (mtaout5.012.net.il [84.95.2.13]) by rzlab.ucr.edu (8.13.8/8.13.8/Debian-3) with ESMTP id n3P7NcbR005859 for <3101-done@emacsbugs.donarmstrong.com>; Sat, 25 Apr 2009 00:23:40 -0700 Received: from conversion-daemon.i_mtaout5.012.net.il by i_mtaout5.012.net.il (HyperSendmail v2004.12) id <0KIN00B00B4PEC00@i_mtaout5.012.net.il> for 3101-done@emacsbugs.donarmstrong.com; Sat, 25 Apr 2009 10:23:32 +0300 (IDT) Received: from HOME-C4E4A596F7 ([77.127.175.232]) by i_mtaout5.012.net.il (HyperSendmail v2004.12) with ESMTPA id <0KIN00DN8B78QNN4@i_mtaout5.012.net.il>; Sat, 25 Apr 2009 10:23:32 +0300 (IDT) Date: Sat, 25 Apr 2009 10:23:34 +0300 From: Eli Zaretskii Subject: Re: bug#3101: 23.0.92; Emacs manual, node Tags In-reply-to: <007501c9c51c$5a6c8f70$0200a8c0@us.oracle.com> X-012-Sender: halo1@inter.net.il To: Drew Adams , 3101-done@debbugs.gnu.org Reply-to: Eli Zaretskii Message-id: <83skjxfb7t.fsf@gnu.org> References: <007501c9c51c$5a6c8f70$0200a8c0@us.oracle.com> > From: "Drew Adams" > Date: Fri, 24 Apr 2009 13:36:31 -0700 > Cc: > > The first sentence of this node doesn't sound right to me. At least > it's not clear what is meant. > > "A "tags table" is a description of how a multi-file > program is broken up into files." > > A multi-file program? What program would that be? There is no further > mention of this. I don't understand this sentence, and I cannot > imagine how it describes what a tags table is. I changed this to A @dfn{tags table} is a description of how program's sources are broken up into individual source files. I hope this is more clear. > Also confusing is the part that starts "When a file parsed by `etags' > is generated from a different source file, like a C file generated > from a Cweb source file,..." To understand this (and I don't), a > reader needs to already understand what `etags' is and what its > parsing amounts to, and s?he needs to know what Cweb is (I don't). Not > to mention that it is mysterious what is meant by "a different source > file" - different from what? The text reads now Each entry in the tags table records the name of a tag, the name of the file that the tag is defined in (implicitly), and the position in that file of the tag's definition. If the file is a generated file, its tags reference the originating source file. Examples of generated files include C files generated from Cweb source files or from a Yacc parser or Lex scanner definitions, @file{.i} preprocessed C files, and Fortran files produced by preprocessing @file{.fpp} source files. OK? From drew.adams@oracle.com Sat Apr 25 11:38:39 2009 Received: (at 3101-done) by emacsbugs.donarmstrong.com; 25 Apr 2009 18:38:39 +0000 X-Spam-Checker-Version: SpamAssassin 3.2.5-bugs.debian.org_2005_01_02 (2008-06-10) on rzlab.ucr.edu X-Spam-Level: X-Spam-Bayes: score:0.5 Bayes not run. spammytokens:Tokens not available. hammytokens:Tokens not available. X-Spam-Status: No, score=-3.0 required=4.0 tests=HAS_BUG_NUMBER autolearn=ham version=3.2.5-bugs.debian.org_2005_01_02 Received: from acsinet11.oracle.com (acsinet11.oracle.com [141.146.126.233]) by rzlab.ucr.edu (8.13.8/8.13.8/Debian-3) with ESMTP id n3PIcaDx029921 for <3101-done@emacsbugs.donarmstrong.com>; Sat, 25 Apr 2009 11:38:37 -0700 Received: from acsinet15.oracle.com (acsinet15.oracle.com [141.146.126.227]) by acsinet11.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n3PIcXDY007530 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Sat, 25 Apr 2009 18:38:35 GMT Received: from acsmt703.oracle.com (acsmt703.oracle.com [141.146.40.81]) by acsinet15.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n3PIcTeu010534; Sat, 25 Apr 2009 18:38:30 GMT Received: from dradamslap1 (/98.210.250.59) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Sat, 25 Apr 2009 18:38:24 +0000 From: "Drew Adams" To: "'Eli Zaretskii'" , <3101-done@debbugs.gnu.org> References: <007501c9c51c$5a6c8f70$0200a8c0@us.oracle.com> <83skjxfb7t.fsf@gnu.org> Subject: RE: bug#3101: 23.0.92; Emacs manual, node Tags Date: Sat, 25 Apr 2009 11:38:28 -0700 Message-ID: <000e01c9c5d5$06d83b70$0200a8c0@us.oracle.com> MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Mailer: Microsoft Office Outlook 11 In-Reply-To: <83skjxfb7t.fsf@gnu.org> Thread-Index: AcnFdsNK4CO05iYbR6WKf6OOOjs+xQAXIxcQ X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.3350 X-Source-IP: acsmt703.oracle.com [141.146.40.81] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A010202.49F358A3.0139:SCFMA4539814,ss=1,fgs=0 > > The first sentence of this node doesn't sound right to me. At least > > it's not clear what is meant. > > > > "A "tags table" is a description of how a multi-file > > program is broken up into files." > > > > A multi-file program? What program would that be? There is > no further > > mention of this. I don't understand this sentence, and I cannot > > imagine how it describes what a tags table is. > > I changed this to > > A @dfn{tags table} is a description of how program's sources are > broken up into individual source files. > > I hope this is more clear. Not really; well, maybe a little. "Sources" is not clear, to me at least - I don't know what you mean by that. Do you mean the source code for a program? Is this saying that program X might be defined using multiple source files, and the tags table records this; that is, it records which source files define program X? If so, let's just say that. If not, what is meant? If it's not easy to express the concept in words, then perhaps adding a simple "for instance" will help understanding. > > Also confusing is the part that starts "When a file parsed > > by `etags' is generated from a different source file, like a > > C file generated from a Cweb source file,..." To understand > > this (and I don't), a reader needs to already understand what > > `etags' is and what its parsing amounts to, and s?he needs to > > know what Cweb is (I don't). Not to mention that it is > > mysterious what is meant by "a different source file" - > > different from what? > > The text reads now > > Each entry in the tags table records the name of a tag, > the name of the file that the tag is defined in (implicitly), Why "implicitly"? How so? Is it always implicit? Or is "implicit" meant to refer to the case of generated files? > and the position in that file of the tag's definition. If > the file is a generated file, its tags reference the > originating source file. Examples of generated > files include C files generated from Cweb source files or > from a Yacc parser or Lex scanner definitions, That doesn't parse well, for me. Do you mean "from a Yacc parser or from Lex scanner definitions" or "from Yacc parser or Lex scanner definitions" or perhaps "from a Yacc parser or a Lex scanner"? > @file{.i} preprocessed C files, and Fortran files produced by > preprocessing @file{.fpp} source files. > > OK? From eliz@gnu.org Sat Apr 25 14:16:38 2009 Received: (at 3101-done) by emacsbugs.donarmstrong.com; 25 Apr 2009 21:16:38 +0000 X-Spam-Checker-Version: SpamAssassin 3.2.5-bugs.debian.org_2005_01_02 (2008-06-10) on rzlab.ucr.edu X-Spam-Level: X-Spam-Bayes: score:0.5 Bayes not run. spammytokens:Tokens not available. hammytokens:Tokens not available. X-Spam-Status: No, score=-2.9 required=4.0 tests=FOURLA,HAS_BUG_NUMBER autolearn=ham version=3.2.5-bugs.debian.org_2005_01_02 Received: from mtaout3.012.net.il (mtaout3.012.net.il [84.95.2.7]) by rzlab.ucr.edu (8.13.8/8.13.8/Debian-3) with ESMTP id n3PLGXMN008964 for <3101-done@emacsbugs.donarmstrong.com>; Sat, 25 Apr 2009 14:16:35 -0700 Received: from conversion-daemon.i_mtaout3.012.net.il by i_mtaout3.012.net.il (HyperSendmail v2004.12) id <0KIO00B00DIR0E00@i_mtaout3.012.net.il> for 3101-done@emacsbugs.donarmstrong.com; Sun, 26 Apr 2009 00:16:27 +0300 (IDT) Received: from HOME-C4E4A596F7 ([77.127.175.232]) by i_mtaout3.012.net.il (HyperSendmail v2004.12) with ESMTPA id <0KIO00D3NDREGBS0@i_mtaout3.012.net.il>; Sun, 26 Apr 2009 00:16:27 +0300 (IDT) Date: Sun, 26 Apr 2009 00:16:29 +0300 From: Eli Zaretskii Subject: Re: bug#3101: 23.0.92; Emacs manual, node Tags In-reply-to: <000e01c9c5d5$06d83b70$0200a8c0@us.oracle.com> X-012-Sender: halo1@inter.net.il To: Drew Adams Cc: 3101-done@debbugs.gnu.org Reply-to: Eli Zaretskii Message-id: <83d4b0fn82.fsf@gnu.org> References: <007501c9c51c$5a6c8f70$0200a8c0@us.oracle.com> <83skjxfb7t.fsf@gnu.org> <000e01c9c5d5$06d83b70$0200a8c0@us.oracle.com> > From: "Drew Adams" > Date: Sat, 25 Apr 2009 11:38:28 -0700 > > > A @dfn{tags table} is a description of how program's sources are > > broken up into individual source files. > > > > I hope this is more clear. > > Not really; well, maybe a little. I could use a bit more encouraging. > > Each entry in the tags table records the name of a tag, > > the name of the file that the tag is defined in (implicitly), > > Why "implicitly"? How so? Is it always implicit? Or is "implicit" meant to refer > to the case of generated files? Hey, I didn't write that. I'm just trying to clarify what you said was unclear. Next attempt: A @dfn{tag} is a named subunit of a program or of a document. In program source code, tags are syntactic elements of the program: functions, subroutines, data types, macros, etc. In a document, tags are chapters, sections, appendices, etc. A @dfn{tags table} records the names of the tags extracted from the source code of a certain program or from a certain document. Each tag is listed together with the file name on which it is defined, and the position of the tag in that file. Tags extracted from generated files reference the original file from which they were generated, rather than the file from which these tags were extracted. Examples of generated files include C files generated from Cweb source files, from a Yacc parser, or from Lex scanner definitions; @file{.i} preprocessed C files; and Fortran files produced by preprocessing @file{.fpp} source files. Tags tables are produced by scanning a document or the source code of a program with a special program called @samp{etags}, and stored in files called @dfn{tags table files}. The conventional name for a tags table file is @file{TAGS}. Emacs uses the information recorded in tags tables in commands that search or replace through multiple files: these commands use the names of the source files recorded in the tags table to know which files to search. Other commands, such as @kbd{M-.}, which finds the definition of a function, use the recorded information about the function names and positions to find the source file and the position within that file where the function is defined. From drew.adams@oracle.com Sat Apr 25 14:56:20 2009 Received: (at 3101-done) by emacsbugs.donarmstrong.com; 25 Apr 2009 21:56:20 +0000 X-Spam-Checker-Version: SpamAssassin 3.2.5-bugs.debian.org_2005_01_02 (2008-06-10) on rzlab.ucr.edu X-Spam-Level: X-Spam-Bayes: score:0.5 Bayes not run. spammytokens:Tokens not available. hammytokens:Tokens not available. X-Spam-Status: No, score=-2.9 required=4.0 tests=FOURLA,HAS_BUG_NUMBER autolearn=ham version=3.2.5-bugs.debian.org_2005_01_02 Received: from acsinet12.oracle.com (acsinet12.oracle.com [141.146.126.234]) by rzlab.ucr.edu (8.13.8/8.13.8/Debian-3) with ESMTP id n3PLuHPJ019462 for <3101-done@emacsbugs.donarmstrong.com>; Sat, 25 Apr 2009 14:56:18 -0700 Received: from acsinet15.oracle.com (acsinet15.oracle.com [141.146.126.227]) by acsinet12.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n3PLu712014263 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Sat, 25 Apr 2009 21:56:09 GMT Received: from acsmt707.oracle.com (acsmt707.oracle.com [141.146.40.85]) by acsinet15.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n3PLuBAX017744; Sat, 25 Apr 2009 21:56:13 GMT Received: from dradamslap1 (/98.210.250.59) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Sat, 25 Apr 2009 14:56:06 -0700 From: "Drew Adams" To: "'Eli Zaretskii'" Cc: <3101-done@debbugs.gnu.org> References: <007501c9c51c$5a6c8f70$0200a8c0@us.oracle.com> <83skjxfb7t.fsf@gnu.org> <000e01c9c5d5$06d83b70$0200a8c0@us.oracle.com> <83d4b0fn82.fsf@gnu.org> Subject: RE: bug#3101: 23.0.92; Emacs manual, node Tags Date: Sat, 25 Apr 2009 14:56:09 -0700 Message-ID: <001401c9c5f0$a63a47b0$0200a8c0@us.oracle.com> MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Mailer: Microsoft Office Outlook 11 In-Reply-To: <83d4b0fn82.fsf@gnu.org> Thread-Index: AcnF60RDVyIRymVFS3anQyaJtvWuAAAADW3w X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.3350 X-Source-IP: acsmt707.oracle.com [141.146.40.85] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A010201.49F386F8.00FA:SCFMA4539814,ss=1,fgs=0 > > > A @dfn{tags table} is a description of how program's > > > sources are broken up into individual source files. > > > > > > I hope this is more clear. > > > > Not really; well, maybe a little. > > I could use a bit more encouraging. Sorry. Just trying to be honest, thinking that will help the most. > > > Each entry in the tags table records the name of a tag, > > > the name of the file that the tag is defined in (implicitly), > > > > Why "implicitly"? How so? Is it always implicit? Or is > > "implicit" meant to refer to the case of generated files? > > Hey, I didn't write that. I'm just trying to clarify what you said > was unclear. Hm. It won't help much for me to argue, but that is what you wrote. You wrote it directly after you wrote "The text reads now" (which I assumed you meant after your corrections). All I meant was that I don't understand what is meant by "(implicitly)" here. > Next attempt: > > A @dfn{tag} is a named subunit of a program or of a document. In > program source code, tags are syntactic elements of the program: > functions, subroutines, data types, macros, etc. In a > document, tags are chapters, sections, appendices, etc. Sounds good. I tend to think of them as *definitions* of functions, subroutines... Dunno if that helps. > A @dfn{tags table} records the names of the tags > extracted from the source code of a certain program > or from a certain document. Each tag > is listed together with the file name on which it is > defined, and the position of the tag in that file. OK, but from what was said above, the tag is the whole syntactic element (e.g. whole function definition or chapter), not just the function name or chapter title. Is the whole function definition or chapter listed/included in the tags table? The tag "name" wasn't introduced. I think it might help to say that a tag name, file, and position are used to represent source content (which I think you're calling a tag), and these are recorded in the tags table as a tag entry (which is what I've always thought of as the tag). I don't really know which the "tag" is - is it the referenced source content (definition or section), which I think is what you're saying, or is it the entry in the tags table, which is used to used to reference (look up) that content? I've always thought of the "tag" as the index entry (name, but also file and position), not the indexed content, but maybe that's wrong. Whatever the terminology, I think we have an index, I, whose entries, E, are used to look up content, C, in the source files. That is the way I would present it: index, index entry, indexed content. I = the tags table E = what I've always called the tags C = what I think you're calling the tags > Tags extracted from generated files > reference the original file "file" or "files"? (dunno) > from which they "They" = the files, not the tags, but this took me a while to parse. Better to just say "the files". > were generated, rather than the file "rather than the generated files" > from which these tags were extracted. Examples of > generated files include C files generated from Cweb source > files, from a Yacc parser, or from Lex scanner definitions; @file{.i} > preprocessed C files; and Fortran files produced by preprocessing > @file{.fpp} source files. > > Tags tables are produced by scanning a document or the source > code of a program with a special program called @samp{etags}, Lose "special". > and stored in files called @dfn{tags table files}. The > conventional name for a tags table file is @file{TAGS}. Good. I think tags files are the same thing as tags table files, and users will see the term "tags file" as well as "tags table file", so you might want to mention it in passing, as being a synonym. > Emacs uses the information recorded in tags tables in > commands that search or replace through multiple files: "multiple source files" > these commands use the names of the source files recorded > in the tags table to know which files to search. Other > commands, such as @kbd{M-.}, which finds the definition > of a function, use the recorded information about the > function names and positions to find the source file and > the position within that file where the function is defined. Good. If my comments above help, great. If not, please ignore them and go with whatever you think is best. I think you understand my feedback now, which is all I can ask for. Thanks for working on this, Eli. From eliz@gnu.org Sun Apr 26 11:07:00 2009 Received: (at 3101-done) by emacsbugs.donarmstrong.com; 26 Apr 2009 18:07:01 +0000 X-Spam-Checker-Version: SpamAssassin 3.2.5-bugs.debian.org_2005_01_02 (2008-06-10) on rzlab.ucr.edu X-Spam-Level: X-Spam-Bayes: score:0.5 Bayes not run. spammytokens:Tokens not available. hammytokens:Tokens not available. X-Spam-Status: No, score=-2.9 required=4.0 tests=FOURLA,HAS_BUG_NUMBER autolearn=ham version=3.2.5-bugs.debian.org_2005_01_02 Received: from mtaout7.012.net.il (mtaout7.012.net.il [84.95.2.19]) by rzlab.ucr.edu (8.13.8/8.13.8/Debian-3) with ESMTP id n3QI6uVG026389 for <3101-done@emacsbugs.donarmstrong.com>; Sun, 26 Apr 2009 11:06:57 -0700 Received: from conversion-daemon.i-mtaout7.012.net.il by i-mtaout7.012.net.il (HyperSendmail v2007.08) id <0KIP00J00ZBY6500@i-mtaout7.012.net.il> for 3101-done@emacsbugs.donarmstrong.com; Sun, 26 Apr 2009 21:06:50 +0300 (IDT) Received: from HOME-C4E4A596F7 ([77.127.175.232]) by i-mtaout7.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0KIP009HDZNCZMR0@i-mtaout7.012.net.il>; Sun, 26 Apr 2009 21:06:49 +0300 (IDT) Date: Sun, 26 Apr 2009 21:06:52 +0300 From: Eli Zaretskii Subject: Re: bug#3101: 23.0.92; Emacs manual, node Tags In-reply-to: <001401c9c5f0$a63a47b0$0200a8c0@us.oracle.com> X-012-Sender: halo1@inter.net.il To: Drew Adams Cc: 3101-done@debbugs.gnu.org Reply-to: Eli Zaretskii Message-id: <833abvffwj.fsf@gnu.org> References: <007501c9c51c$5a6c8f70$0200a8c0@us.oracle.com> <83skjxfb7t.fsf@gnu.org> <000e01c9c5d5$06d83b70$0200a8c0@us.oracle.com> <83d4b0fn82.fsf@gnu.org> <001401c9c5f0$a63a47b0$0200a8c0@us.oracle.com> > From: "Drew Adams" > Cc: <3101-done@emacsbugs.donarmstrong.com> > Date: Sat, 25 Apr 2009 14:56:09 -0700 > > > Next attempt: > > > > A @dfn{tag} is a named subunit of a program or of a document. In > > program source code, tags are syntactic elements of the program: > > functions, subroutines, data types, macros, etc. In a > > document, tags are chapters, sections, appendices, etc. > > Sounds good. I tend to think of them as *definitions* of functions, > subroutines... Dunno if that helps. Let's try this one: A @dfn{tag} is a reference to a subunit in a program or in a document. In program source code, tags reference syntactic elements of the program: functions, subroutines, data types, macros, etc. In a document, tags reference chapters, sections, appendices, etc. Each tag specifies the file name on which the corresponding subunit is defined, and the position of the subunit's definition in that file. A @dfn{tags table} records the tags extracted by scanning the source code of a certain program or a certain document. Tags extracted from generated files reference subunits in the original files, rather than the generated files that were scanned during tag extraction. Examples of generated files include C files generated from Cweb source files, from a Yacc parser, or from Lex scanner definitions; @file{.i} preprocessed C files; and Fortran files produced by preprocessing @file{.fpp} source files. To produce tags tables, you use the @samp{etags} command, submitting it a document or the source code of a program. @samp{etags} writes the tags to files called @dfn{tags table files}, or @dfn{tags file} in short. The conventional name for a tags file is @file{TAGS}. Emacs uses the information recorded in tags tables in commands that search or replace through multiple source files: these commands use the names of the source files recorded in the tags table to know which files to search. Other commands, such as @kbd{M-.}, which finds the definition of a function, use the recorded information about the function names and positions to find the source file and the position within that file where the function is defined. From drew.adams@oracle.com Sun Apr 26 11:20:28 2009 Received: (at 3101-done) by emacsbugs.donarmstrong.com; 26 Apr 2009 18:20:29 +0000 X-Spam-Checker-Version: SpamAssassin 3.2.5-bugs.debian.org_2005_01_02 (2008-06-10) on rzlab.ucr.edu X-Spam-Level: X-Spam-Bayes: score:0.5 Bayes not run. spammytokens:Tokens not available. hammytokens:Tokens not available. X-Spam-Status: No, score=-2.9 required=4.0 tests=FOURLA,HAS_BUG_NUMBER autolearn=ham version=3.2.5-bugs.debian.org_2005_01_02 Received: from acsinet12.oracle.com (acsinet12.oracle.com [141.146.126.234]) by rzlab.ucr.edu (8.13.8/8.13.8/Debian-3) with ESMTP id n3QIKP5i029728 for <3101-done@emacsbugs.donarmstrong.com>; Sun, 26 Apr 2009 11:20:26 -0700 Received: from acsinet15.oracle.com (acsinet15.oracle.com [141.146.126.227]) by acsinet12.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n3QIKHHu015889 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Sun, 26 Apr 2009 18:20:18 GMT Received: from acsmt701.oracle.com (acsmt701.oracle.com [141.146.40.71]) by acsinet15.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n3QIKMhS024400; Sun, 26 Apr 2009 18:20:23 GMT Received: from dradamslap1 (/98.210.250.59) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Sun, 26 Apr 2009 11:20:16 -0700 From: "Drew Adams" To: "'Eli Zaretskii'" Cc: <3101-done@debbugs.gnu.org> References: <007501c9c51c$5a6c8f70$0200a8c0@us.oracle.com> <83skjxfb7t.fsf@gnu.org> <000e01c9c5d5$06d83b70$0200a8c0@us.oracle.com> <83d4b0fn82.fsf@gnu.org> <001401c9c5f0$a63a47b0$0200a8c0@us.oracle.com> <833abvffwj.fsf@gnu.org> Subject: RE: bug#3101: 23.0.92; Emacs manual, node Tags Date: Sun, 26 Apr 2009 11:20:23 -0700 Message-ID: <001e01c9c69b$ab13ec90$0200a8c0@us.oracle.com> MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Mailer: Microsoft Office Outlook 11 In-Reply-To: <833abvffwj.fsf@gnu.org> Thread-Index: AcnGmc0Y4PM7rWozTWm1Emx41NACBwAACHIg X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.3350 X-Source-IP: acsmt701.oracle.com [141.146.40.71] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A010202.49F4A5E2.002D:SCFMA4539814,ss=1,fgs=0 Good. A few ignorable nits, below. > Let's try this one: > > A @dfn{tag} is a reference to a subunit in a program or in a > document. In program source code, tags reference syntactic elements > of the program: functions, subroutines, data types, macros, > etc. In a document, tags reference chapters, sections, appendices, > etc. Each tag specifies the file name on which I would say "in which", but that might be a yank/brit difference - dunno. And the tag is not in the file name, but in the file, so: Each tag specifies the name of the file in which... > the corresponding subunit is > defined, and the position of the subunit's definition in that file. We haven't introduced definitions of subunits. (I tend to think of program (not document) subunits as definitions, but it's not about the definitions _of the subunits_, I think.) That should be just "position of the subunit in that file". > A @dfn{tags table} records the tags extracted by scanning > the source code of a certain program or a certain document. Tags > extracted from generated files reference subunits in the original > files, rather than in > the generated files that were scanned during tag > extraction. Examples of generated files include C files generated > from Cweb source files, from a Yacc parser, or from Lex scanner > definitions; @file{.i} preprocessed C files; and Fortran files > produced by preprocessing @file{.fpp} source files. > > To produce tags tables, To produce a tags table, (Unless you can create (and typically do create) more than one at once, using etags.) > you use the @samp{etags} command, > submitting it a document or the source code of a program. > @samp{etags} writes the tags to a tags table in a @dfn{tags table file}, (Connect the notion of tags table with that of tags file.) > files called @dfn{tags table files}, > or @dfn{tags file} in short. The conventional name for a tags file > is @file{TAGS}. > > Emacs uses the information recorded in tags tables in > commands that search or replace through multiple source files: > these commands use the names of the source files recorded in > the tags table to know which files to search. Other commands, > such as @kbd{M-.}, which finds the definition of a function, > use the recorded information about the function names and > positions to find the source file and the position > within that file where the function is defined. Great. Thanks for clearing everything up. From eliz@gnu.org Sun Apr 26 12:02:30 2009 Received: (at 3101-done) by emacsbugs.donarmstrong.com; 26 Apr 2009 19:02:30 +0000 X-Spam-Checker-Version: SpamAssassin 3.2.5-bugs.debian.org_2005_01_02 (2008-06-10) on rzlab.ucr.edu X-Spam-Level: X-Spam-Bayes: score:0.5 Bayes not run. spammytokens:Tokens not available. hammytokens:Tokens not available. X-Spam-Status: No, score=-2.9 required=4.0 tests=FOURLA,HAS_BUG_NUMBER autolearn=ham version=3.2.5-bugs.debian.org_2005_01_02 Received: from mtaout1.012.net.il (mtaout1.012.net.il [84.95.2.1]) by rzlab.ucr.edu (8.13.8/8.13.8/Debian-3) with ESMTP id n3QJ2QGa008806 for <3101-done@emacsbugs.donarmstrong.com>; Sun, 26 Apr 2009 12:02:28 -0700 Received: from conversion-daemon.i-mtaout1.012.net.il by i-mtaout1.012.net.il (HyperSendmail v2007.08) id <0KIQ0040027CZD00@i-mtaout1.012.net.il> for 3101-done@emacsbugs.donarmstrong.com; Sun, 26 Apr 2009 22:02:14 +0300 (IDT) Received: from HOME-C4E4A596F7 ([77.127.175.232]) by i-mtaout1.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0KIQ007VG27BB190@i-mtaout1.012.net.il>; Sun, 26 Apr 2009 22:02:00 +0300 (IDT) Date: Sun, 26 Apr 2009 22:02:03 +0300 From: Eli Zaretskii Subject: Re: bug#3101: 23.0.92; Emacs manual, node Tags In-reply-to: <001e01c9c69b$ab13ec90$0200a8c0@us.oracle.com> X-012-Sender: halo1@inter.net.il To: Drew Adams Cc: 3101-done@debbugs.gnu.org Reply-to: Eli Zaretskii Message-id: <83zle3dys4.fsf@gnu.org> References: <007501c9c51c$5a6c8f70$0200a8c0@us.oracle.com> <83skjxfb7t.fsf@gnu.org> <000e01c9c5d5$06d83b70$0200a8c0@us.oracle.com> <83d4b0fn82.fsf@gnu.org> <001401c9c5f0$a63a47b0$0200a8c0@us.oracle.com> <833abvffwj.fsf@gnu.org> <001e01c9c69b$ab13ec90$0200a8c0@us.oracle.com> > From: "Drew Adams" > Cc: <3101-done@emacsbugs.donarmstrong.com> > Date: Sun, 26 Apr 2009 11:20:23 -0700 > > > A @dfn{tag} is a reference to a subunit in a program or in a > > document. In program source code, tags reference syntactic elements > > of the program: functions, subroutines, data types, macros, > > etc. In a document, tags reference chapters, sections, appendices, > > etc. Each tag specifies the file name on which > > I would say "in which", but that might be a yank/brit difference - dunno. I worked around that pitfall, see below. > And the tag is not in the file name, but in the file, so: > > Each tag specifies the name of the file in which... > > > the corresponding subunit is > > defined, and the position of the subunit's definition in that file. > > We haven't introduced definitions of subunits. (I tend to think of program (not > document) subunits as definitions, but it's not about the definitions _of the > subunits_, I think.) > > That should be just "position of the subunit in that file". It now reads Each tag specifies the name of the file where the corresponding subunit is defined, and the position of that definition in the file. I don't think we need to define what is a subunit, as the examples should convey the idea. Trying to define every term in sight leads to unreadable documents, in my experience. > > A @dfn{tags table} records the tags extracted by scanning > > the source code of a certain program or a certain document. Tags > > extracted from generated files reference subunits in the original > > files, rather than > > in > > > the generated files that were scanned during tag extraction. I preferred to remove "subunits" altogether here: Tags extracted from generated files reference the original files, rather than the generated files that were scanned during tag extraction. > > To produce tags tables, > > To produce a tags table, Right. > > you use the @samp{etags} command, > > submitting it a document or the source code of a program. > > @samp{etags} writes the tags to > > a tags table in a @dfn{tags table file}, > > (Connect the notion of tags table with that of tags file.) To produce a tags table, you use the @samp{etags} command, submitting it a document or the source code of a program. @samp{etags} writes the tags to a @dfn{tags table file}, or @dfn{tags file} in short. The conventional name for a tags file is @file{TAGS}. From drew.adams@oracle.com Sun Apr 26 12:16:54 2009 Received: (at 3101-done) by emacsbugs.donarmstrong.com; 26 Apr 2009 19:16:54 +0000 X-Spam-Checker-Version: SpamAssassin 3.2.5-bugs.debian.org_2005_01_02 (2008-06-10) on rzlab.ucr.edu X-Spam-Level: X-Spam-Bayes: score:0.5 Bayes not run. spammytokens:Tokens not available. hammytokens:Tokens not available. X-Spam-Status: No, score=-3.0 required=4.0 tests=HAS_BUG_NUMBER autolearn=ham version=3.2.5-bugs.debian.org_2005_01_02 Received: from acsinet12.oracle.com (acsinet12.oracle.com [141.146.126.234]) by rzlab.ucr.edu (8.13.8/8.13.8/Debian-3) with ESMTP id n3QJGpTX013633 for <3101-done@emacsbugs.donarmstrong.com>; Sun, 26 Apr 2009 12:16:52 -0700 Received: from rgminet15.oracle.com (rcsinet15.oracle.com [148.87.113.117]) by acsinet12.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n3QJGfbl000628 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Sun, 26 Apr 2009 19:16:42 GMT Received: from acsmt700.oracle.com (acsmt700.oracle.com [141.146.40.70]) by rgminet15.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n3QJGfCG019742; Sun, 26 Apr 2009 19:16:42 GMT Received: from dradamslap1 (/98.210.250.59) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Sun, 26 Apr 2009 12:16:40 -0700 From: "Drew Adams" To: "'Eli Zaretskii'" Cc: <3101-done@debbugs.gnu.org> References: <007501c9c51c$5a6c8f70$0200a8c0@us.oracle.com> <83skjxfb7t.fsf@gnu.org> <000e01c9c5d5$06d83b70$0200a8c0@us.oracle.com> <83d4b0fn82.fsf@gnu.org> <001401c9c5f0$a63a47b0$0200a8c0@us.oracle.com> <833abvffwj.fsf@gnu.org> <001e01c9c69b$ab13ec90$0200a8c0@us.oracle.com> <83zle3dys4.fsf@gnu.org> Subject: RE: bug#3101: 23.0.92; Emacs manual, node Tags Date: Sun, 26 Apr 2009 12:16:48 -0700 Message-ID: <002001c9c6a3$8c9a2150$0200a8c0@us.oracle.com> MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Mailer: Microsoft Office Outlook 11 In-Reply-To: <83zle3dys4.fsf@gnu.org> Thread-Index: AcnGocaO7kr9E4NYRO+Fx1t0wrAPPwAAbnLw X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.3350 X-Source-IP: acsmt700.oracle.com [141.146.40.70] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A090206.49F4B31A.00FB:SCFMA4539814,ss=1,fgs=0 Looks good. Thx. From unknown Mon Aug 18 17:57:52 2025 Received: (at fakecontrol) by fakecontrolmessage; To: internal_control@debbugs.gnu.org From: $requester Subject: Internal Control Message-Id: bug archived. Date: Mon, 25 May 2009 14:24:16 +0000 User-Agent: Fakemail v42.6.9 # A New Hope # A log time ago, in a galaxy far, far away # something happened. # # Magically this resulted in the following # action being taken, but this fake control # message doesn't tell you why it happened # # The action: # bug archived. thanks # This fakemail brought to you by your local debbugs # administrator