Metadata-Version: 2.1
Name: z3c.recipe.tag
Version: 1.0
Summary: Generate ctags from eggs for development.
Home-page: https://github.com/zopefoundation/z3c.recipe.tag
Author: Ignas Mikalajūnas and the Zope Community
Maintainer: Paul Carduner
Maintainer-email: zope-dev@zope.dev
License: ZPL 2.1
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Zope Public License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Framework :: Buildout
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Text Editors :: Emacs
Classifier: Topic :: Utilities
Requires-Python: >=3.7
License-File: LICENSE.rst
Requires-Dist: setuptools
Requires-Dist: zc.buildout (>=3.0)
Requires-Dist: zc.recipe.egg
Provides-Extra: test
Requires-Dist: zope.testing ; extra == 'test'
Requires-Dist: zope.testrunner ; extra == 'test'

==============
z3c.recipe.tag
==============

|buildstatus|_

.. contents::

Introduction
------------

This recipe generates a TAGS database file that can be used with a
number of different editors to quickly look up class and function
definitions in your package's source files and egg dependencies.

Dependencies
------------

Before running a tags enabled buildout, you must install the
appropriate command line tag generation tools: exuberant-ctags and
id-utils.  In Ubuntu, you can install these with apt-get::

  $ sudo apt-get install exuberant-ctags id-utils

On a Mac, download and install ``port`` from http://www.macports.org/ and then
install ctags and idutils in this way::

  $ sudo port install ctags idutils

How to use this recipe
----------------------

With Buildout
.............

Suppose you have an egg called ``MyApplication``.  To use this recipe with
buildout, you would add the following to the ``buildout.cfg`` file::

  [tags]
  recipe = z3c.recipe.tag
  eggs = MyApplication

This produces a script file in the ``bin/`` directory which you can
then run like this::

  $ ./bin/tags

By default, this script produces three files in the directory from
which you ran the script:

- a ctags file called ``TAGS`` for use by emacs,
- a ctags file called ``tags`` for use by vi, and
- an idutils file called ``ID`` for use by id-utils (gid, lid).

You can then use these files in your editor of choice.

Optionally, you can select which files to build.  The following is the output
of ``./bin/tags --help``::

    usage: build_tags [options]

    options:
      -h, --help            show this help message and exit
      -l LANGUAGES, --languages=LANGUAGES
                            ctags comma-separated list of languages. defaults to
                            ``-JavaScript``
      -e, --ctags-emacs     flag to build emacs ctags ``TAGS`` file
      -v, --ctags-vi        flag to build vi ctags ``tags`` file
      -b, --ctags-bbedit    flag to build bbedit ctags ``tags`` file
      -i, --idutils         flag to build idutils ``ID`` file

If you'd like to set command line options by default (e.g. to limit
building to ctags-vi by default) you can pass the ``default`` option in
your buildout.cfg::

  [tags]
  recipe = z3c.recipe.tag
  eggs = MyApplication
  default = ['-v']

With virtualenv
...............

You can use this with `virtualenv
<https://pypi.python.org/pypi/virtualenv>`__ too::

  my_venv/bin/pip install z3c.recipe.tag
  my_venv/bin/build_tags

this will build a tags file for all the packages installed in that virtualenv.

With Paver
..........

If you are using `Paver
<http://www.blueskyonmars.com/projects/paver/>`_ and already have
z3c.recipe.tag installed, then all you have to do is add this line to
your ``pavement.py`` file::

  import z3c.recipe.tag

And then run the ``z3c.recipe.tag.tags`` task from the command line::

  $ paver z3c.recipe.tag.tags

Additional Resources
--------------------

For additional information on using tags tables with different editors
see the following websites:

- **Emacs**: http://www.gnu.org/software/emacs/manual/html_node/emacs/Tags.html

  - to jump to the location of a tag, type ``M-x find-tag`` and the
    name of the tag.  Or use ``M-.`` to jump to the tag matching the token
    the cursor is currently on.  The first time you do this, you will
    be prompted for the location of the TAGS file.

- **VIM**: http://vimdoc.sourceforge.net/htmldoc/tagsrch.html

- **BBEdit**: http://pine.barebones.com/manual/BBEdit_9_User_Manual.pdf
  Chapter 14, page 324

For more information on ctags, visit http://ctags.sourceforge.net/

(BBEdit_ is a Macintosh text editor.)

.. _BBEdit: http://barebones.com/products/bbedit/

For more information about GNU id-utils (basically a local text
indexing/search engine; think of it as a very fast version of ``grep
-w``), see the `id-utils manual
<http://www.gnu.org/software/idutils/manual/idutils.html>`__.

.. |buildstatus| image:: https://github.com/zopefoundation/z3c.recipe.tag/workflows/tests/badge.svg
.. _buildstatus: https://github.com/zopefoundation/z3c.recipe.tag/actions?query=workflow%3Atests


=======
CHANGES
=======

1.0 (2023-02-09)
----------------

- Drop support for Python < 3.7.

- Add support for Python 3.7 up to 3.11.

- Require ``zc.buildout >= 3``.


0.8 (2014-10-20)
----------------

- Add --tag-relative option to support relative tag generation.


0.7 (2013-03-22)
----------------

- Support and require zc.buildout 2.0.

- Add supported Python version (3.6, 2.7, 3.2, 3.3) classifiers to
  setup.py


0.6 (2012-09-07)
----------------

- Update manifest to allow package generation fron non-VCS export. Counters the
  0.5 "brown bag" release.


0.5 (2012-09-06)
----------------

- Exclude Python import statements by default from showing up as tags.

- Add 'defaults' option to allow adding default command line options (e.g. to
  set '-v' by default)


0.4.1 (2012-01-11)
------------------

* Skip nonexistent sys.path directories to avoid ctags warnings.


0.4.0 (2010-08-29)
------------------

* Support new script features from zc.buildout 1.5 and higher.  This version
  requires zc.buildout 1.5 or higher.

* Also index Mako and HTML files with id-utils.


0.3.0 (2009-08-16)
------------------

* Add support for using this recipe as a `paver <http://www.blueskyonmars.com/projects/paver/>`_ task.

* Also index Javascript, CSS and ReStructuredText files with id-utils.

* Define a default entry point for zc.buildout, so you can simply say::

    [ctags]
    recipe = z3c.recipe.tag


0.2.0 (2008-08-28)
------------------

* Allow command-line choices for what files to build, and what languages ctags
  should parse.  (Note that the default behavior of running ``./bin/tags``
  is the same as previous releases.)

* Support the Mac OS X packaging system "macports" (exuberant ctags is
  ``ctags-exuberant`` in Ubuntu and ``ctags`` in macports).

* Support creating BBEdit-style ctags files.

* Small changes for development (use bootstrap external, set svn:ignore)

0.1.0 (2008-03-16)
------------------

- Initial release.

  * buildout recipe for generating ctags of eggs used.
