@need 3200

@node Customizing the inventory Naming Conventions
@appendix Customizing the inventory Naming Conventions

In @ref{Project Tree Inventories}, you learned how the @code{tla
inventory} command classifies files within a project tree using a set
of naming conventions.   This appendix explains how you can customize
those naming conventions.

@need 3200

@section When to Customize Naming Conventions

It's best to make customizations to the naming conventions of a
project at the outset: before you @code{import} your first revision.


If you @emph{must} make changes later, then it's @emph{@strong{essential}} that your
changes do not change the classification of files already in the
latest revision(s) of your project at the time you make the change
(otherwise, you are likely to experience perplexing and undesirable
behavior).




@need 3200

@section How to Customize Naming Conventions

You should begin by reviewing the naming convention algorithm in
@strong{The arch Naming Conventions} in @ref{Project Tree Inventories}.  You can modify that algorithm by
changing the regular expression used for each category test.


You can customize naming conventions by modifying the file
@code{./@{arch@}/=tagging-method} in your project trees.  That file is created
by the @code{id-tagging-method} command and initially, it contains a single
line which names the id tagging method (@code{names}, @code{explicit}, @code{tagline}
(or the now deprecated, but popular in some older projects, including
arch itself, @code{implicit})).


In particular, @code{=tagging-method} can contain blank lines and comments
(lines beginning with @geindex #
@dfn{#}) and directives, one per line.  The
permissible directives are:

@example
@group
        tagline
        implicit
        explicit
        names
                specify the id tagging method to use for this tree
@end group
@group
@end group
@end example
@example
@group
        exclude RE
        junk RE
        backup RE
        precious RE
        unrecognized RE
        source RE
                specify a regular expression to use for the indicated
                category of files.
@end group
@group
@end group
@end example

Regular expressions are specified in Posix ERE syntax (the same syntax
used by @geindex egrep
@dfn{egrep}, @geindex grep -E
@dfn{grep -E}, and @geindex awk
@dfn{awk}) and have default values which
implement the naming conventions described in @strong{The arch Naming Conventions} in @ref{Project Tree Inventories}.


A given regexp directive can occur more than once, in which case the 
regexps are concatenated as alternatives.   Thus, for example:

@example
@group
        source  .*\.c$
        source  .*\.h$
@end group
@group
@end group
@end example

@noindent
is equivalent to:

@example
@group
        source (.*\.c$)|(.*\.h$)
@end group
@group
@end group
@end example



@need 3200

@section Per-Directory Regexps

@geindex .arch-inventory



A source directory can contain a @code{.arch-inventory} file.


@code{.arch-inventory} files can contain regexp declarations just like
those in =tagging-method (i.e., one for @code{excludes}, one for
@code{junk}, etc.)   Let's call these the @geindex dir-local regexps
@dfn{dir-local regexps}.
The @code{=tagging-method} regexps are the @geindex global regexps
@dfn{global regexps}.


While traversing a tree, each file is classified-by-name as follows.
the steps which are changed by @code{.arch-inventory} are marked with
@code{[*]}:

@example
@group
        0) "." and ".." remain excluded files, no matter what.
@end group
@group
@end group
@end example
@example
@group
   [*]  1) if excluded files are being omitted from the inventory,
           and either the dir-local or global regexp, the file
           is excluded
@end group
@group
@end group
@end example
@example
@group
        2) if the file is a control file, it is source
@end group
@group
@end group
@end example
@example
@group
        3) if the file falls into one of the "mandatory categories"
           (",," and "++" files) it is categorized as junk or 
           precious respectively.
@end group
@group
@end group
@end example
@example
@group
   [*]  4) the dir-local (only) regexps are tried in the usual order:
           junk, backup, precious, unrecognized, source.  If the file
           matches, it is suitably categorized.
@end group
@group
@end group
@end example
@example
@group
        5) the global regexps are tried in the same order.
@end group
@group
@end group
@end example
@example
@group
        6) otherwise the file is unrecognized.
@end group
@group
@end group
@end example






