Overview

Relevant source files

• doc/builtin.jax
• doc/eval.jax
• doc/options.jax
• doc/tags-ja
• doc/terminal.jax
• doc/version9.jax

Purpose and Scope

The vimdoc-ja repository provides Japanese translations of Vim's comprehensive help documentation. This system consists of structured help files (.jax format) and a centralized tag index that enables Vim's built-in help navigation system to work seamlessly in Japanese. This overview covers the repository structure, the tag-based indexing mechanism, and how the documentation clusters map to Vim's major subsystems.

For detailed information about specific documentation systems:

• Tag indexing and navigation: see Tag Index and Central Reference System
• Help system implementation: see Help System and Navigation
• Vim9 scripting features: see Vim9 Script and Modern Features

Sources: doc/tags-ja1-100 Architecture Diagrams 1-2

Repository Structure

File Organization

The vimdoc-ja repository follows a standardized structure where all documentation resides in the doc/ directory:

doc/
├── tags-ja          # Central tag index (649.49 importance score)
├── eval.jax         # Expression evaluation (293.42 importance)
├── options.jax      # Option reference (290.14 importance)
├── version9.jax     # Vim 9.x changes (142.46 importance)
├── builtin.jax      # Built-in functions (132.74 importance)
├── motion.jax       # Cursor movement
├── change.jax       # Text manipulation
├── pattern.jax      # Search patterns
└── [120+ other .jax files]

File Naming Convention:

• .jax extension: Japanese documentation files (corresponds to .txt in English Vim docs)
• tags-ja: Japanese tag index (corresponds to tags in English)

The importance scores reflect edit frequency and cross-reference density, indicating how central each file is to the documentation system.

Sources: doc/tags-ja1 doc/eval.jax1 doc/options.jax1

Documentation File Format

Each .jax file follows Vim's help file structure:

*filename.txt*    For Vim バージョン 9.1.  Last change: [date]

            VIM リファレンスマニュアル    by Bram Moolenaar

[Title line]                                    *tag-name*

Content with inline tags: |tag-reference|

Sources: doc/eval.jax1-10 doc/options.jax1-10

Tag-Based Navigation System

The tags-ja Index File

The tags-ja file is the backbone of Vim's help system, mapping help tags to their locations across all documentation files. This file uses the ctags format with UTF-8 encoding.

Index Structure:

tag_name    file_path    search_pattern

File Format Diagram:

Sources: doc/tags-ja1-100

Tag Categories and Naming Conventions

The tag index organizes entries by category:

Category	Pattern	Example	Target File
Special symbols	!, $, %, etc.	! → change.jax	Various
Options	'option-name'	'encoding' → options.jax	options.jax
Ex commands	:command	:set → options.jax	Varies
Functions	function()	eval() → builtin.jax	builtin.jax
Variables	v:varname	v:version → eval.jax	eval.jax
Modes	mode-key	i_CTRL-X → insert.jax	Varies

Sources: doc/tags-ja1-500 doc/options.jax44-65

Tag Reference System

Navigation Flow:

Example Tag Entries:

$HOME           options.jax     /*$HOME*
'encoding'      options.jax     /*'encoding'*
:set            options.jax     /*:set*
eval()          builtin.jax     /*eval()*

Sources: doc/tags-ja7-65 doc/options.jax544

Documentation Architecture

Hierarchical Organization

The documentation follows a layered architecture where tags-ja serves as the universal index, and documentation files are organized by functional area:

Sources: Architecture Diagram 1, doc/tags-ja1-100 doc/eval.jax1-50

Cross-Reference System

Documentation files extensively cross-reference each other using inline tag notation |tag-name|. This creates a hyperlinked knowledge graph:

Cross-Reference Pattern:

See |:set| for setting options.
The |eval()| function evaluates expressions.
Variables are explained in |variables|.

When a user navigates to a tag reference (e.g., by pressing CTRL-] on |:set|), Vim:

1. Searches tags-ja for the tag :set
2. Finds entry: :set options.jax /*:set*
3. Opens options.jax
4. Searches for pattern /*:set*
5. Positions cursor at the match

Sources: doc/eval.jax9-20 doc/options.jax44-65

Major Documentation Clusters

Core Systems Overview

The documentation is organized into five major functional clusters:

Sources: Architecture Diagrams 1-2

Cluster Importance Metrics

The importance scores (based on cross-reference density and edit frequency) reveal the centrality of each cluster:

Cluster	Key Files	Avg Importance	Role
Documentation Index	tags-ja	649.49	Universal entry point
Scripting Engine	eval.jax, builtin.jax	213.08	Enable customization
Configuration	options.jax, map.jax	223.57	Control behavior
Core Editing	motion.jax, change.jax	142.00	Basic operations
Text Intelligence	syntax.jax, spell.jax	133.50	Advanced features

The tags-ja file's exceptionally high importance (649.49) confirms its role as the linchpin of the entire documentation system.

Sources: Architecture Diagram 1, File importance scores

Documentation Coverage Map

System-to-File Mapping:

Sources: Architecture Diagrams 1-3

Key Documentation Entry Points

Most Referenced Documentation Files:

1. tags-ja (649.49) - All help navigation starts here
2. eval.jax (293.42) - Expression evaluation, variables, data types
3. options.jax (290.14) - Complete option reference with :set syntax
4. version9.jax (142.46) - Vim9 script features and changes
5. builtin.jax (132.74) - All built-in function signatures

Common Navigation Patterns:

• User types :help :set → tags-ja → options.jax:44
• User types :help eval → tags-ja → eval.jax:7
• User types :help 'encoding' → tags-ja → options.jax:251
• User types :help function-list → tags-ja → builtin.jax:12

Sources: doc/tags-ja1-100 doc/eval.jax1-50 doc/options.jax1-100 doc/version9.jax1-60 doc/builtin.jax1-25

Integration with Vim's Help System

The vimdoc-ja repository integrates directly with Vim's built-in help system through:

1. Runtime Path Integration: Files in doc/ are automatically indexed when in 'runtimepath'
2. Language Selection: :set helplang=ja causes Vim to prefer tags-ja over tags
3. Tag Precedence: Japanese tags take precedence when helplang includes ja
4. Fallback Mechanism: If a tag isn't found in tags-ja, Vim falls back to English tags

This architecture enables seamless bilingual documentation support while maintaining complete compatibility with Vim's existing help infrastructure.

Sources: doc/tags-ja1 doc/options.jax398-400