GNU bug report logs -
#3101
23.0.92; Emacs manual, node Tags
Previous Next
To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 3101 in the body.
You can then email your comments to 3101 AT debbugs.gnu.org in the normal way.
Toggle the display of automated, internal messages from the tracker.
Report forwarded
to
bug-submit-list <at> lists.donarmstrong.com, Emacs Bugs <bug-gnu-emacs <at> gnu.org>:
bug#3101; Package
emacs.
(Fri, 24 Apr 2009 20:45:03 GMT)
Full text and
rfc822 format available.
Acknowledgement sent
to
"Drew Adams" <drew.adams <at> oracle.com>:
New bug report received and forwarded. Copy sent to
Emacs Bugs <bug-gnu-emacs <at> gnu.org>.
(Fri, 24 Apr 2009 20:45:03 GMT)
Full text and
rfc822 format available.
Message #5 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):
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)'
Reply sent
to
Eli Zaretskii <eliz <at> gnu.org>:
You have taken responsibility.
(Sat, 25 Apr 2009 07:30:05 GMT)
Full text and
rfc822 format available.
Notification sent
to
"Drew Adams" <drew.adams <at> oracle.com>:
bug acknowledged by developer.
(Sat, 25 Apr 2009 07:30:05 GMT)
Full text and
rfc822 format available.
Message #10 received at 3101-done <at> emacsbugs.donarmstrong.com (full text, mbox):
> From: "Drew Adams" <drew.adams <at> oracle.com>
> 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?
Message #11 received at 3101-done <at> emacsbugs.donarmstrong.com (full text, mbox):
> > 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?
Message #12 received at 3101-done <at> emacsbugs.donarmstrong.com (full text, mbox):
> From: "Drew Adams" <drew.adams <at> oracle.com>
> 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.
Message #13 received at 3101-done <at> emacsbugs.donarmstrong.com (full text, mbox):
> > > 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.
Message #14 received at 3101-done <at> emacsbugs.donarmstrong.com (full text, mbox):
> From: "Drew Adams" <drew.adams <at> oracle.com>
> Cc: <3101-done <at> 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.
Message #15 received at 3101-done <at> emacsbugs.donarmstrong.com (full text, mbox):
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.
Message #16 received at 3101-done <at> emacsbugs.donarmstrong.com (full text, mbox):
> From: "Drew Adams" <drew.adams <at> oracle.com>
> Cc: <3101-done <at> 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}.
Message #17 received at 3101-done <at> emacsbugs.donarmstrong.com (full text, mbox):
Looks good. Thx.
bug archived.
Request was from
Debbugs Internal Request <help-debbugs <at> gnu.org>
to
internal_control <at> emacsbugs.donarmstrong.com.
(Mon, 25 May 2009 14:24:16 GMT)
Full text and
rfc822 format available.
This bug report was last modified 16 years and 89 days ago.
Previous Next
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.