aboutsummaryrefslogtreecommitdiff
path: root/ctags/man/ctags-faq.7.html
diff options
context:
space:
mode:
Diffstat (limited to 'ctags/man/ctags-faq.7.html')
-rw-r--r--ctags/man/ctags-faq.7.html757
1 files changed, 757 insertions, 0 deletions
diff --git a/ctags/man/ctags-faq.7.html b/ctags/man/ctags-faq.7.html
new file mode 100644
index 0000000..65d4f71
--- /dev/null
+++ b/ctags/man/ctags-faq.7.html
@@ -0,0 +1,757 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
+<title>ctags-faq</title>
+<style type="text/css">
+
+/*
+:Author: David Goodger (goodger@python.org)
+:Id: $Id: html4css1.css 7952 2016-07-26 18:15:59Z milde $
+:Copyright: This stylesheet has been placed in the public domain.
+
+Default cascading style sheet for the HTML output of Docutils.
+
+See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
+customize this style sheet.
+*/
+
+/* used to remove borders from tables and images */
+.borderless, table.borderless td, table.borderless th {
+ border: 0 }
+
+table.borderless td, table.borderless th {
+ /* Override padding for "table.docutils td" with "! important".
+ The right padding separates the table cells. */
+ padding: 0 0.5em 0 0 ! important }
+
+.first {
+ /* Override more specific margin styles with "! important". */
+ margin-top: 0 ! important }
+
+.last, .with-subtitle {
+ margin-bottom: 0 ! important }
+
+.hidden {
+ display: none }
+
+.subscript {
+ vertical-align: sub;
+ font-size: smaller }
+
+.superscript {
+ vertical-align: super;
+ font-size: smaller }
+
+a.toc-backref {
+ text-decoration: none ;
+ color: black }
+
+blockquote.epigraph {
+ margin: 2em 5em ; }
+
+dl.docutils dd {
+ margin-bottom: 0.5em }
+
+object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] {
+ overflow: hidden;
+}
+
+/* Uncomment (and remove this text!) to get bold-faced definition list terms
+dl.docutils dt {
+ font-weight: bold }
+*/
+
+div.abstract {
+ margin: 2em 5em }
+
+div.abstract p.topic-title {
+ font-weight: bold ;
+ text-align: center }
+
+div.admonition, div.attention, div.caution, div.danger, div.error,
+div.hint, div.important, div.note, div.tip, div.warning {
+ margin: 2em ;
+ border: medium outset ;
+ padding: 1em }
+
+div.admonition p.admonition-title, div.hint p.admonition-title,
+div.important p.admonition-title, div.note p.admonition-title,
+div.tip p.admonition-title {
+ font-weight: bold ;
+ font-family: sans-serif }
+
+div.attention p.admonition-title, div.caution p.admonition-title,
+div.danger p.admonition-title, div.error p.admonition-title,
+div.warning p.admonition-title, .code .error {
+ color: red ;
+ font-weight: bold ;
+ font-family: sans-serif }
+
+/* Uncomment (and remove this text!) to get reduced vertical space in
+ compound paragraphs.
+div.compound .compound-first, div.compound .compound-middle {
+ margin-bottom: 0.5em }
+
+div.compound .compound-last, div.compound .compound-middle {
+ margin-top: 0.5em }
+*/
+
+div.dedication {
+ margin: 2em 5em ;
+ text-align: center ;
+ font-style: italic }
+
+div.dedication p.topic-title {
+ font-weight: bold ;
+ font-style: normal }
+
+div.figure {
+ margin-left: 2em ;
+ margin-right: 2em }
+
+div.footer, div.header {
+ clear: both;
+ font-size: smaller }
+
+div.line-block {
+ display: block ;
+ margin-top: 1em ;
+ margin-bottom: 1em }
+
+div.line-block div.line-block {
+ margin-top: 0 ;
+ margin-bottom: 0 ;
+ margin-left: 1.5em }
+
+div.sidebar {
+ margin: 0 0 0.5em 1em ;
+ border: medium outset ;
+ padding: 1em ;
+ background-color: #ffffee ;
+ width: 40% ;
+ float: right ;
+ clear: right }
+
+div.sidebar p.rubric {
+ font-family: sans-serif ;
+ font-size: medium }
+
+div.system-messages {
+ margin: 5em }
+
+div.system-messages h1 {
+ color: red }
+
+div.system-message {
+ border: medium outset ;
+ padding: 1em }
+
+div.system-message p.system-message-title {
+ color: red ;
+ font-weight: bold }
+
+div.topic {
+ margin: 2em }
+
+h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
+h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
+ margin-top: 0.4em }
+
+h1.title {
+ text-align: center }
+
+h2.subtitle {
+ text-align: center }
+
+hr.docutils {
+ width: 75% }
+
+img.align-left, .figure.align-left, object.align-left, table.align-left {
+ clear: left ;
+ float: left ;
+ margin-right: 1em }
+
+img.align-right, .figure.align-right, object.align-right, table.align-right {
+ clear: right ;
+ float: right ;
+ margin-left: 1em }
+
+img.align-center, .figure.align-center, object.align-center {
+ display: block;
+ margin-left: auto;
+ margin-right: auto;
+}
+
+table.align-center {
+ margin-left: auto;
+ margin-right: auto;
+}
+
+.align-left {
+ text-align: left }
+
+.align-center {
+ clear: both ;
+ text-align: center }
+
+.align-right {
+ text-align: right }
+
+/* reset inner alignment in figures */
+div.align-right {
+ text-align: inherit }
+
+/* div.align-center * { */
+/* text-align: left } */
+
+.align-top {
+ vertical-align: top }
+
+.align-middle {
+ vertical-align: middle }
+
+.align-bottom {
+ vertical-align: bottom }
+
+ol.simple, ul.simple {
+ margin-bottom: 1em }
+
+ol.arabic {
+ list-style: decimal }
+
+ol.loweralpha {
+ list-style: lower-alpha }
+
+ol.upperalpha {
+ list-style: upper-alpha }
+
+ol.lowerroman {
+ list-style: lower-roman }
+
+ol.upperroman {
+ list-style: upper-roman }
+
+p.attribution {
+ text-align: right ;
+ margin-left: 50% }
+
+p.caption {
+ font-style: italic }
+
+p.credits {
+ font-style: italic ;
+ font-size: smaller }
+
+p.label {
+ white-space: nowrap }
+
+p.rubric {
+ font-weight: bold ;
+ font-size: larger ;
+ color: maroon ;
+ text-align: center }
+
+p.sidebar-title {
+ font-family: sans-serif ;
+ font-weight: bold ;
+ font-size: larger }
+
+p.sidebar-subtitle {
+ font-family: sans-serif ;
+ font-weight: bold }
+
+p.topic-title {
+ font-weight: bold }
+
+pre.address {
+ margin-bottom: 0 ;
+ margin-top: 0 ;
+ font: inherit }
+
+pre.literal-block, pre.doctest-block, pre.math, pre.code {
+ margin-left: 2em ;
+ margin-right: 2em }
+
+pre.code .ln { color: grey; } /* line numbers */
+pre.code, code { background-color: #eeeeee }
+pre.code .comment, code .comment { color: #5C6576 }
+pre.code .keyword, code .keyword { color: #3B0D06; font-weight: bold }
+pre.code .literal.string, code .literal.string { color: #0C5404 }
+pre.code .name.builtin, code .name.builtin { color: #352B84 }
+pre.code .deleted, code .deleted { background-color: #DEB0A1}
+pre.code .inserted, code .inserted { background-color: #A3D289}
+
+span.classifier {
+ font-family: sans-serif ;
+ font-style: oblique }
+
+span.classifier-delimiter {
+ font-family: sans-serif ;
+ font-weight: bold }
+
+span.interpreted {
+ font-family: sans-serif }
+
+span.option {
+ white-space: nowrap }
+
+span.pre {
+ white-space: pre }
+
+span.problematic {
+ color: red }
+
+span.section-subtitle {
+ /* font-size relative to parent (h1..h6 element) */
+ font-size: 80% }
+
+table.citation {
+ border-left: solid 1px gray;
+ margin-left: 1px }
+
+table.docinfo {
+ margin: 2em 4em }
+
+table.docutils {
+ margin-top: 0.5em ;
+ margin-bottom: 0.5em }
+
+table.footnote {
+ border-left: solid 1px black;
+ margin-left: 1px }
+
+table.docutils td, table.docutils th,
+table.docinfo td, table.docinfo th {
+ padding-left: 0.5em ;
+ padding-right: 0.5em ;
+ vertical-align: top }
+
+table.docutils th.field-name, table.docinfo th.docinfo-name {
+ font-weight: bold ;
+ text-align: left ;
+ white-space: nowrap ;
+ padding-left: 0 }
+
+/* "booktabs" style (no vertical lines) */
+table.docutils.booktabs {
+ border: 0px;
+ border-top: 2px solid;
+ border-bottom: 2px solid;
+ border-collapse: collapse;
+}
+table.docutils.booktabs * {
+ border: 0px;
+}
+table.docutils.booktabs th {
+ border-bottom: thin solid;
+ text-align: left;
+}
+
+h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
+h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
+ font-size: 100% }
+
+ul.auto-toc {
+ list-style-type: none }
+
+</style>
+</head>
+<body>
+<div class="document" id="ctags-faq">
+<span id="ctags-faq-7"></span>
+<h1 class="title">ctags-faq</h1>
+<h2 class="subtitle" id="universal-ctags-faq">Universal Ctags FAQ</h2>
+<table class="docinfo" frame="void" rules="none">
+<col class="docinfo-name" />
+<col class="docinfo-content" />
+<tbody valign="top">
+<tr><th class="docinfo-name">Version:</th>
+<td>5.9.0</td></tr>
+<tr class="manual-group field"><th class="docinfo-name">Manual group:</th><td class="field-body">Universal Ctags</td>
+</tr>
+<tr class="manual-section field"><th class="docinfo-name">Manual section:</th><td class="field-body">7</td>
+</tr>
+</tbody>
+</table>
+<p>This is the Universal Ctags FAQ (Frequently-Asked Questions).
+It is based on <a class="reference external" href="http://ctags.sourceforge.net/faq.html">Exuberant Ctags FAQ</a></p>
+<div class="contents topic" id="contents">
+<p class="topic-title">Contents</p>
+<ul class="simple">
+<li><a class="reference internal" href="#description" id="id2">DESCRIPTION</a><ul>
+<li><a class="reference internal" href="#what-is-the-difference-between-universal-ctags-and-exuberant-ctags" id="id3">What is the difference between Universal Ctags and Exuberant Ctags?</a></li>
+<li><a class="reference internal" href="#how-can-i-avoid-having-to-specify-my-favorite-option-every-time" id="id4">How can I avoid having to specify my favorite option every time?</a></li>
+<li><a class="reference internal" href="#what-are-these-strange-bits-of-text-beginning-with-which-follow-many-of-the-lines-in-the-tag-file" id="id5">What are these strange bits of text beginning with <tt class="docutils literal">;&quot;</tt> which follow many of the lines in the tag file?</a></li>
+<li><a class="reference internal" href="#why-can-t-i-jump-to-class-member" id="id6">Why can't I jump to <tt class="docutils literal"><span class="pre">class::member</span></tt>?</a></li>
+<li><a class="reference internal" href="#why-do-i-end-up-on-the-wrong-line-when-i-jump-to-a-tag" id="id7">Why do I end up on the wrong line when I jump to a tag?</a></li>
+<li><a class="reference internal" href="#how-do-i-jump-to-the-tag-i-want-instead-of-the-wrong-one-by-the-same-name" id="id8">How do I jump to the tag I want instead of the wrong one by the same name?</a></li>
+<li><a class="reference internal" href="#how-can-i-locate-all-references-to-a-specific-function-or-variable" id="id9">How can I locate all references to a specific function or variable?</a></li>
+<li><a class="reference internal" href="#why-does-appending-tags-to-a-tag-file-tag-so-long" id="id10">Why does appending tags to a tag file tag so long?</a></li>
+<li><a class="reference internal" href="#how-should-i-set-up-tag-files-for-a-multi-level-directory-hierarchy" id="id11">How should I set up tag files for a multi-level directory hierarchy?</a></li>
+<li><a class="reference internal" href="#does-universal-ctags-support-unicode-file-names" id="id12">Does Universal Ctags support Unicode file names?</a></li>
+<li><a class="reference internal" href="#why-does-zsh-cause-zsh-no-matches-found-error" id="id13">Why does zsh cause &quot;zsh: no matches found&quot; error?</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#see-also" id="id14">SEE ALSO</a></li>
+<li><a class="reference internal" href="#author" id="id15">AUTHOR</a></li>
+</ul>
+</div>
+<div class="section" id="description">
+<h1><a class="toc-backref" href="#id2">DESCRIPTION</a></h1>
+<!-- TODO: https://github.com/universal-ctags/ctags/issues/2312
+#1421: feature: clean up stale tags when appending (`-a`)
+#2356: can't pre-process the macro but it works with Exuberant Ctags 5.8
+#2540: C/C++：conditional compilation like #ifdef will cause parse errror -->
+<div class="section" id="what-is-the-difference-between-universal-ctags-and-exuberant-ctags">
+<h2><a class="toc-backref" href="#id3">What is the difference between Universal Ctags and Exuberant Ctags?</a></h2>
+<p>Universal Ctags is an unofficial fork of Exuberant Ctags.
+The differences are summarized in ctags-incompatibilities(7) man page.</p>
+<p>The most notable one is that Universal Ctags doesn't read <tt class="docutils literal"><span class="pre">~/.ctags</span></tt> file.
+Instead, it reads <tt class="docutils literal">*.ctags</tt> under <tt class="docutils literal"><span class="pre">~/.ctags.d</span></tt> directory.</p>
+</div>
+<div class="section" id="how-can-i-avoid-having-to-specify-my-favorite-option-every-time">
+<h2><a class="toc-backref" href="#id4">How can I avoid having to specify my favorite option every time?</a></h2>
+<p>Either by setting the environment variable <tt class="docutils literal">CTAGS</tt> to your custom
+options, or putting them into a <tt class="docutils literal"><span class="pre">~/.ctags.d/anyname.ctags</span></tt> file in your home
+directory.</p>
+</div>
+<div class="section" id="what-are-these-strange-bits-of-text-beginning-with-which-follow-many-of-the-lines-in-the-tag-file">
+<h2><a class="toc-backref" href="#id5">What are these strange bits of text beginning with <tt class="docutils literal">;&quot;</tt> which follow many of the lines in the tag file?</a></h2>
+<p>These are <em>extension flags</em>. They are added in order to provide extra
+information about the tag that may be utilized by the editor in order to
+more intelligently handle tags. They are appended to the EX command part of
+the tag line in a manner that provides backwards compatibility with existing
+implementations of the Vi editor. The semicolon is an EX command separator
+and the double quote begins an EX comment. Thus, the extension flags appear
+as an EX comment and should be ignored by the editor when it processes the
+EX command.</p>
+<p>Some non-vi editors, however, implement only the bare minimum of EX commands
+in order to process the search command or line number in the third field of
+the tag file. If you encounter this problem, use the option <tt class="docutils literal"><span class="pre">--format=1</span></tt> to
+generate a tag file without these extensions (remember that you can set the
+CTAGS environment variable to any default arguments you wish to supply). Then
+ask the supplier of your editor to implement handling of this feature of EX
+commands.</p>
+</div>
+<div class="section" id="why-can-t-i-jump-to-class-member">
+<h2><a class="toc-backref" href="#id6">Why can't I jump to <tt class="docutils literal"><span class="pre">class::member</span></tt>?</a></h2>
+<p>Because, by default, ctags only generates tags for the separate identifiers
+found in the source files. If you specify the <tt class="docutils literal"><span class="pre">--extra=+q</span></tt> option, then
+ctags will also generate a second, class-qualified tag for each class member
+(data and function/method) in the form <tt class="docutils literal"><span class="pre">class::member</span></tt> for C++, and in the form
+<tt class="docutils literal">class.method</tt> for Eiffel and Java.</p>
+</div>
+<div class="section" id="why-do-i-end-up-on-the-wrong-line-when-i-jump-to-a-tag">
+<h2><a class="toc-backref" href="#id7">Why do I end up on the wrong line when I jump to a tag?</a></h2>
+<p>By default, ctags encodes the line number in the file where macro (<tt class="docutils literal">#define</tt>)
+tags are found. This was done to remain compatible with the original UNIX
+version of ctags. If you change the file containing the tag without
+rebuilding the tag file, the location of tag in the tag file may no longer
+match the current location.</p>
+<p>In order to avoid this problem, you can specify the option <tt class="docutils literal"><span class="pre">--excmd=p</span></tt>,
+which causes ctags to use a search pattern to locate macro tags. I have
+never uncovered the reason why the original UNIX ctags used line numbers
+exclusively for macro tags, but have so far resisted changing the default
+behavior of Exuberant (and Universal) Ctags to behave differently.</p>
+</div>
+<div class="section" id="how-do-i-jump-to-the-tag-i-want-instead-of-the-wrong-one-by-the-same-name">
+<h2><a class="toc-backref" href="#id8">How do I jump to the tag I want instead of the wrong one by the same name?</a></h2>
+<p>A tag file is simple a list of tag names and where to find them. If there
+are duplicate entries, you often end up going to the wrong one because the
+tag file is sorted and your editor locates the first one in the tag file.</p>
+<p>Standard Vi provides no facilities to alter this behavior. However, Vim
+has some nice features to minimize this problem, primarily by examining all
+matches and choosing the best one under the circumstances. Vim also provides
+commands which allow for selection of the desired matching tag.</p>
+</div>
+<div class="section" id="how-can-i-locate-all-references-to-a-specific-function-or-variable">
+<h2><a class="toc-backref" href="#id9">How can I locate all references to a specific function or variable?</a></h2>
+<p>There are several packages already available which provide this capability.
+Namely, these are: GLOBAL source code tag system, GNU id-utils, cscope,
+and cflow. As of this writing, they can be found in the following locations:</p>
+<ul class="simple">
+<li>GLOBAL: <a class="reference external" href="http://www.gnu.org/software/global">http://www.gnu.org/software/global</a></li>
+<li>id-utils: <a class="reference external" href="http://www.gnu.org/software/idutils/idutils.html">http://www.gnu.org/software/idutils/idutils.html</a></li>
+<li>cscope: <a class="reference external" href="http://cscope.sourceforge.net">http://cscope.sourceforge.net</a></li>
+<li>cflow: <a class="reference external" href="ftp://www.ibiblio.org/pub/Linux/devel/lang/c">ftp://www.ibiblio.org/pub/Linux/devel/lang/c</a></li>
+</ul>
+</div>
+<div class="section" id="why-does-appending-tags-to-a-tag-file-tag-so-long">
+<h2><a class="toc-backref" href="#id10">Why does appending tags to a tag file tag so long?</a></h2>
+<p>Sometimes, in an attempt to build a global tag file for all source files in
+a large source tree of many directories, someone will make an attempt to run
+ctags in append (<tt class="docutils literal"><span class="pre">-a</span></tt>) mode on every directory in the hierarchy. Each time
+ctags is invoked, its default behavior is to sort the tag file once the tags
+for that execution have been added. As the cumulative tag file grows, the sort
+time increases arithmetically.</p>
+<p>The best way to avoid this problem (and the most efficient) is to make
+use of the <tt class="docutils literal"><span class="pre">--recurse</span></tt> (or <tt class="docutils literal"><span class="pre">-R</span></tt>) option of ctags by executing the following
+command in the root of the directory hierarchy (thus running ctags only once):</p>
+<blockquote>
+<pre class="code sh literal-block">
+ctags -R
+</pre>
+</blockquote>
+<p>If you really insist on running ctags separately on each directory, you can
+avoid the sort pass each time by specifying the option <tt class="docutils literal"><span class="pre">--sort=no</span></tt>. Once the
+tag file is completely built, use the sort command to manually sort the
+final tag file, or let the final invocation of ctags sort the file.</p>
+</div>
+<div class="section" id="how-should-i-set-up-tag-files-for-a-multi-level-directory-hierarchy">
+<h2><a class="toc-backref" href="#id11">How should I set up tag files for a multi-level directory hierarchy?</a></h2>
+<p>There are a few ways of approaching this:</p>
+<ol class="arabic simple">
+<li>A local tag file in each directory containing only the tags for source
+files in that directory.</li>
+<li>One single big, global tag file present in the root directory of your
+hierarchy, containing all tags present in all source files in the
+hierarchy.</li>
+<li>A local tag file in each directory containing only the tags for source
+files in that directory, in addition to one single global tag file
+present in the root directory of your hierarchy, containing all
+non-static tags present in all source files in the hierarchy.</li>
+<li>A local tag file in each directory of the hierarchy, each one
+containing all tags present in source files in that directory and all
+non-static tags in every directory below it (note that this implies
+also having one big tag file in the root directory of the hierarchy).</li>
+</ol>
+<p>Each of these approaches has its own set of advantages and disadvantages,
+depending upon your particular conditions. Which approach is deemed best
+depends upon the following factors:</p>
+<ol class="upperalpha">
+<li><p class="first">The ability of your editor to use multiple tag files.</p>
+<p>If your editor cannot make use of multiple tag files (original vi
+implementations could not), then one large tag file is the only way to
+go if you ever desire to jump to tags located in other directories. If
+you never need to jump to tags in another directory (i.e. the source
+in each directory is entirely self-contained), then a local tag file
+in each directory will fit your needs.</p>
+</li>
+<li><p class="first">The time is takes for your editor to look up a tag in the tag file.</p>
+<p>The significance of this factor depends upon the size of your source
+tree and on whether the source files are located on a local or remote
+file system. For source and tag files located on a local file system,
+looking up a tag is not as big a hit as one might first imagine, since
+vi implementations typically perform a binary search on a sorted tag
+file. This may or may not be true for the editor you use. For files
+located on a remote file system, reading a large file is an expensive
+operation.</p>
+</li>
+<li><p class="first">Whether or not you expect the source code to change and the time it
+takes to rebuild a tag file to account for changes to the source code.</p>
+<p>While Universal Ctags is particularly fast in scanning source code
+(around 1-2 MB/sec), a large project may still result in objectionable
+delays if one wishes to keep their tag file(s) up to date on a
+frequent basis, or if the files are located on a remote file system.</p>
+</li>
+<li><p class="first">The presence of duplicate tags in the source code and the ability to
+handle them.</p>
+<p>The impact of this factor is influenced by the following three issues:</p>
+<ol class="arabic">
+<li><p class="first">How common are duplicate tags in your project?</p>
+</li>
+<li><p class="first">Does your editor provide any facilities for dealing with duplicate
+tags?</p>
+<p>While standard vi does not, many modern vi implementations, such
+as Vim have good facilities for selecting the desired match from
+the list of duplicates. If your editor does not support duplicate
+tags, then it will typically send you to only one of them, whether
+or not that is the one you wanted (and not even notifying you that
+there are other potential matches).</p>
+</li>
+<li><p class="first">What is the significance of duplicate tags?</p>
+<p>For example, if you have two tags of the same name from entirely
+isolated software components, jumping first to the match found
+in component B while working in component A may be entirely
+misleading, distracting or inconvenient (to keep having to choose
+which one if your editor provides you with a list of matches).
+However, if you have two tags of the same name for parallel builds
+(say two initialization routines for different hosts), you may
+always want to specify which one you want.</p>
+</li>
+</ol>
+</li>
+</ol>
+<p>Of the approaches listed above, I tend to favor Approach 3. My editor of
+choice is Vim, which provides a rich set of features for handling multiple
+tag files, which partly influences my choice. If you are working with
+source files on a remote file system, then I would recommend either
+Approach 3 or Approach 4, depending upon the hit when reading the global
+tag file.</p>
+<p>The advantages of Approach 3 are many (assuming that your editor has
+the ability to support both multiple tag files and duplicate tags). All
+lookups of tag located in the current directory are fast and the local
+tag file can be quickly and easily regenerated in one second or less
+(I have even mapped a keystroke to do this easily). A lookup of a
+(necessarily non-static) tag found in another directory fails a lookup in
+the local tag file, but is found in the global tag file, which satisfies
+all cross-directory lookups. The global tag file can be automatically
+regenerated periodically with a cron job (and perhaps the local tag files
+also).</p>
+<p>Now I give an example of how you would implement Approach 3. Means of
+implementing the other approaches can be performed in a similar manner.</p>
+<p>Here is a visual representation of an example directory hierarchy:</p>
+<pre class="literal-block">
+project
+`-----misccomp
+| `...
+`-----sysint
+ `-----client
+ | `-----hdrs
+ | `-----lib
+ | `-----src
+ | `-----test
+ `-----common
+ | `-----hdrs
+ | `-----lib
+ | `-----src
+ | `-----test
+ `-----server
+ `-----hdrs
+ `-----lib
+ `-----src
+ `-----test
+</pre>
+<p>Here is a recommended solution (conceptually) to build the tag files:</p>
+<ol class="arabic">
+<li><p class="first">Within each of the leaf nodes (i.e. <tt class="docutils literal">hdrs</tt>, <tt class="docutils literal">lib</tt>, <tt class="docutils literal">src</tt>, <tt class="docutils literal">test</tt>) build a tag
+file using &quot;<tt class="docutils literal">ctags <span class="pre">*.[ch]</span></tt>&quot;. This can be easily be done for the whole
+hierarchy by making a shell script, call it <tt class="docutils literal">dirtags</tt>, containing the
+following lines:</p>
+<blockquote>
+<pre class="code sh literal-block">
+<span class="comment hashbang">#!/bin/sh
+</span><span class="name builtin">cd</span> <span class="name variable">$1</span>
+ctags *
+</pre>
+</blockquote>
+<p>Now execute the following command:</p>
+<blockquote>
+<pre class="code sh literal-block">
+find * -type d -exec dirtags <span class="operator">{}</span> <span class="literal string escape">\;</span>
+</pre>
+</blockquote>
+<p>These tag files are trivial (and extremely quick) to rebuild while
+making changes within a directory. The following Vim key mapping is
+quite useful to rebuild the tag file in the directory of the current
+source file:</p>
+<blockquote>
+<pre class="code text literal-block">
+:nmap ,t :!(cd %:p:h;ctags *.[ch])&amp;&lt;CR&gt;&lt;CR&gt;
+</pre>
+</blockquote>
+</li>
+<li><p class="first">Build the global tag file:</p>
+<blockquote>
+<pre class="code sh literal-block">
+<span class="name builtin">cd</span> ~/project
+ctags --file-scope<span class="operator">=</span>no -R
+</pre>
+</blockquote>
+<p>thus constructing a tag file containing only non-static tags for all
+source files in all descendent directories.</p>
+</li>
+<li><p class="first">Configure your editor to read the local tag file first, then consult
+the global tag file when not found in the local tag file. In Vim,
+this is done as follows:</p>
+<blockquote>
+<pre class="code text literal-block">
+:set tags=./tags,tags,~/project/tags
+</pre>
+</blockquote>
+</li>
+</ol>
+<p>If you wish to implement Approach 4, you would need to replace the
+<tt class="docutils literal">dirtags</tt> script of step 1 with the following:</p>
+<blockquote>
+<pre class="code sh literal-block">
+<span class="comment hashbang">#!/bin/sh
+</span><span class="name builtin">cd</span> <span class="name variable">$1</span>
+ctags *
+<span class="comment single"># Now append the non-static tags from descendent directories
+</span>find * -type d -prune -print <span class="punctuation">|</span> ctags -aR --file-scope<span class="operator">=</span>no -L-
+</pre>
+</blockquote>
+<p>And replace the configuration of step 3 with this:</p>
+<blockquote>
+<pre class="code text literal-block">
+:set tags=./tags;$HOME,tags
+</pre>
+</blockquote>
+<p>As a caveat, it should be noted that step 2 builds a global tag file whose
+file names will be relative to the directory in which the global tag file
+is being built. This takes advantage of the Vim <tt class="docutils literal">tagrelative</tt> option,
+which causes the path to be interpreted a relative to the location of the
+tag file instead of the current directory. For standard vi, which always
+interprets the paths as relative to the current directory, we need to
+build the global tag file with absolute path names. This can be
+accomplished by replacing step 2 with the following:</p>
+<blockquote>
+<pre class="code sh literal-block">
+<span class="name builtin">cd</span> ~/project
+ctags --file-scope<span class="operator">=</span>no -R <span class="literal string backtick">`</span><span class="name builtin">pwd</span><span class="literal string backtick">`</span>
+</pre>
+</blockquote>
+</div>
+<div class="section" id="does-universal-ctags-support-unicode-file-names">
+<h2><a class="toc-backref" href="#id12">Does Universal Ctags support Unicode file names?</a></h2>
+<!-- MEMO: from https://github.com/universal-ctags/ctags/issues/1837 -->
+<p>Yes, Unicode file names are supported on unix-like platforms (Linux, macOS,
+Cygwin, etc.).</p>
+<p>However, on Windows, you need to use Windows 10 version 1903 or later to use
+Unicode file names. (This is an experimental feature, though.) On older versions
+on Windows, Universal Ctags only support file names represented in the current
+code page. If you still want to use Unicode file names on them, use Cygwin or
+MSYS2 version of Universal Ctags as a workaround.</p>
+</div>
+<div class="section" id="why-does-zsh-cause-zsh-no-matches-found-error">
+<h2><a class="toc-backref" href="#id13">Why does zsh cause &quot;zsh: no matches found&quot; error?</a></h2>
+<!-- MEMO: from https://github.com/universal-ctags/ctags/issues/2842 -->
+<p>zsh causes error on the following cases;</p>
+<blockquote>
+<pre class="code sh literal-block">
+ctags --extra<span class="operator">=</span>+* ...
+ctags --exclude<span class="operator">=</span>foo/* ...
+</pre>
+</blockquote>
+<p>This is the 2nd most significant incompatibility <em>feature</em> of zsh.</p>
+<p>Cited from &quot;Z-Shell Frequently-Asked Questions&quot;, &quot;<a class="reference external" href="http://zsh.sourceforge.net/FAQ/zshfaq02.html">2.1: Differences from sh and
+ksh</a>&quot;;</p>
+<blockquote>
+... The next most classic difference is that unmatched glob patterns cause
+the command to abort; set <tt class="docutils literal">NO_NOMATCH</tt> for those.</blockquote>
+<p>You may add &quot;<tt class="docutils literal">setopt nonomatch</tt>&quot; on your <tt class="docutils literal"><span class="pre">~/.zshrc</span></tt>. Or you can escape glob
+patterns with backslash;</p>
+<blockquote>
+<pre class="code sh literal-block">
+ctags --extra<span class="operator">=</span>+<span class="literal string escape">\*</span> ...
+ctags --exclude<span class="operator">=</span>foo/<span class="literal string escape">\*</span> ...
+</pre>
+</blockquote>
+<p>Or quote them;</p>
+<blockquote>
+<pre class="code sh literal-block">
+ctags <span class="literal string single">'--extra=+*'</span> ...
+ctags <span class="literal string single">'--exclude=foo/*'</span> ...
+</pre>
+</blockquote>
+</div>
+</div>
+<div class="section" id="see-also">
+<h1><a class="toc-backref" href="#id14">SEE ALSO</a></h1>
+<p>The official Universal Ctags web site at:</p>
+<p><a class="reference external" href="https://ctags.io/">https://ctags.io/</a></p>
+<p>ctags(1), tags(5)</p>
+</div>
+<div class="section" id="author">
+<h1><a class="toc-backref" href="#id15">AUTHOR</a></h1>
+<p>This FAQ is based on <a class="reference external" href="http://ctags.sourceforge.net/faq.html">Exuberant Ctags FAQ</a> by
+Darren Hiebert and <a class="reference external" href="mailto:vberthoux&#64;users.sourceforge.net">vberthoux&#64;users.sourceforge.net</a></p>
+<p>Universal Ctags project: <a class="reference external" href="https://ctags.io/">https://ctags.io/</a></p>
+</div>
+</div>
+</body>
+</html>