📘 ACE — Full Documentation Guide

ACE is a collection of integrated tools designed to help you understand Arabic verbs, nouns, and Tajweed using:

• ACE Analyzer — ace_main.php Analyzes a root, form, tense, pronoun, and declension.
• ACE Stem Tester — ace_stem_tester.php Tests patterns using build_combined_token().
• Reverse Analyzer — reverse_analyzer_engine.php Start from an Arabic word and work backwards to root/form.
• Dictionary Browser — ace_dictionary.php and ace_dictionary_index.php Browse and search the master dictionary.
• Tajweed Lectures & Practice — lecture_links.php and other practice pages under /ace/tajweed/.

The goal of this Full Guide is to document:

• How the engine builds tokens (Latin + Arabic + IPA)
• How we colorize roots, prefixes, suffixes, and Tajweed letters
• How forms I–X, tenses, and weak verbs are handled
• How dictionary entries are stored and used
• Where each set of rules lives in the file system

The core morphological logic is documented in:

• Morphology Overview
• Forms Explained (I–X)
• Tenses & Categories (1–44)
• Weak Verbs (Hollow / Defective / Assimilated)

2.1 Root Structure

ACE normalizes each root into three radicals: r0, r1, r2. These are colored consistently in the interface.

• Example: ktb → ك ت ب
• Example: qwl → ق و ل (hollow)
• Example: wqy → و ق ي (defective)

2.2 Verb Forms I–X

Each form has a base pattern for: perfect (past), imperfect, participles, and verbal noun (maṣdar). These are implemented via build_combined_token() and documented further in:

• build_combined_token() — Technical Notes
• Stem Tester Documentation

2.3 Weak, Hollow, Defective, Hamzated

Special patterns (e.g. hol11, hol17, def21, mth12, etc.) are handled in build_combined_token() and explained in:

• Hollow Verb Rules
• Defective Verb Rules
• Assimilated Verb Rules
• Hamzated Verb Rules
• Weak Verb Summary

The core “engine” is distributed across:

• Stem Engine Overview
• Latin → Arabic Rendering
• Arabic Rendering (diacritics, sukun, shadda)
• Flowcharts

3.1 build_combined_token()

The function build_combined_token() is the heart of pattern assembly. Given:

build_combined_token($F, $r0, $r1, $r2, $pronIdx, $infl1, $infl2, $tense)

it returns:

• The Latin stem with vowels and duplication
• The imperfect or form prefix (ya-/ta-/na-/ea-/sta- etc.)
• Embedded long vowels (aA, iy, uw)
• Special handling for: Form VIII assimilation, hollow patterns, duplicated radicals, hamzated roots, etc.

Technical notes and examples for each key (e.g. 1-2, 4-7, hol11, def22) are provided in: build_combined_token() Docs .

3.2 Latin → Arabic → IPA

The rendering pipeline is:

1. Latin pattern from build_combined_token() (e.g. yaktubu, eistakbara)
2. Arabic Unicode via latinToArabic(), with rules for: digraphs (sh, th, gh, etc.), long vowels, sukun, and shaddah.
3. IPA via an internal mapping, documented in: Pronunciation Guide and IPA Rules (depending on filenames you use).

3.3 Reverse Analyzer

The reverse analyzer: reverse_analyzer_engine.php works in the opposite direction:

1. Normalize the Arabic or Latin input token.
2. Try to strip known prefixes, particles, and pronoun suffixes.
3. Detect possible roots and forms with pattern matching.
4. Cross-check against dictionary_master_array.

Internal logic and diagrams are documented in: Engine Overview and Analyzer Legend.

ACE uses a for:

• Prefix / stem / suffix
• Root letters (r0, r1, r2)
• Qalqalah, Tafkhīm (heavy letters), and throat letters
• Long vowels in IPA (ā, ī, ū)

Documentation pages:

• Color Legend
• Stem Tester Legend
• Tajweed Rules Overview
• Detailed Tajweed Rules

Tajweed lectures with PDF thumbnails are linked from: Tajweed Lecture Links. You can switch between list / grid view and click any thumbnail to open the PDF.

Dictionary data is centralized in:

• /ace/dictionary_master_array.php

Key pages that use it:

• ace_dictionary.php — browse entry details
• ace_dictionary_index.php — index by root
• ace_main.php — analyzer uses dictionary to:
  • Pull base translations (English & Urdu)
  • Get default form I masdar / participles
  • Derive higher forms via patterns

5.1 dictionary_master_array.php structure

Each entry looks like:

$dictionary[2206] = [
    'id'                   => 2206,
    'root'                 => 'ktb',
    'arabic'               => 'كَتَبَ',
    'english'              => 'to write',
    'urdu'                 => 'لکھنا',
    'vg'                   => 'n',

    // Form I
    'activepast11'         => 'كَتَبَ',
    'activeimperfect12'    => 'يَكْتُبُ',
    'verbalnoun117'        => 'كِتَابَةٌ',
    'activeparticiple115'  => 'كَاتِبٌ',
    'passiveparticiple116' => 'مَكْتُوبٌ',

    // Higher forms (optional)
    'activepast21'         => 'كَتَّبَ',
    'activeimperfect22'    => 'يُكْتِبُ',
    'verbalnoun217'        => 'تَكْتِيبٌ',
];

Helper functions (defined at the bottom of dictionary_master_array.php) include:

• ace_find_dictionary_entry_by_root($root)
• ace_get_dictionary_index_by_root($root)
• ace_get_all_roots()

5.2 Frequency & Qurʼān Search

ACE can link each Latin form (e.g. yaktubu) to an external search page for the Qurʼān database, such as f_search20.php?word=yaktubu, and optionally display counts in the analyzer or stem tester tables.

These functions are usually located in your search helper files (e.g. f_search20.php, f_search_no.php) and connected from:

• Stem Tester Docs
• Tense Documentation

Interface layout, styles, and navigation are controlled by:

• /ace/ace_header.php — horizontal ACE navigation bar
• /ace/ace_footer.php — footer links and credits
• /ace_styles.css & /ace_scripts.js — shared styling & JS
• assets/css/ace_style.css
• assets/css/documentation.css
• assets/css/legend.css
• assets/js/navigation.js

This page uses: .ace-doc-page, .ace-doc-section, .ace-doc-summary-title, .ace-doc-summary-icon, and a collapsible pattern built with <details> and <summary>.

The buttons “Expand All / Collapse All” at the top of this page are wired with a small JavaScript helper (at the bottom of this file) that toggles all <details> elements with data-collapsible="true".

The following rule files were detected in: /ace/documentation/ace_rules/. Click any one to open it in a new tab.

• ace_rule_fractions.php
• ace_rule_number_summary.php
• ace_rule_numbers.php
• ace_rule_ordinals.php
• ace_rules.php
• ace_rules_g2_numbers.php
• ace_rules_g3_quantifers.php
• assimilation_rules.php
• collapsible_rules.php
• conjugation_rules.php
• form_rules.php
• index.php
• ipa_rules.php
• nouns_declension_rules.php
• particles_rules.php
• prefix_suffix_rules.php
• rules_assimilated.php
• rules_defective.php
• rules_doublyweak.php
• rules_hamzated.php
• rules_hollow.php
• rules_numbers_agreement.php
• rules_numbers_cardinal.php
• rules_numbers_ordinal.php
• rules_weak_verbs.php
• tajweed_rules.php
• vowel_rules.php
• weak_verbs_rules.php

Many of these rule pages are linked contextually from other docs:

• Cardinal Numbers Rules
• Ordinal Numbers Rules
• Number System Summary
• Conjugation Rules

For internal architecture, debugging, and future extensions, see the following documentation pages:

• ACE Overview
• Docs Menu & Structure
• Stem Tester Internals
• Latin → Arabic Conversion
• Tense Codes (1–44)

Key guidelines for adding new features:

1. Add new dictionary entries to dictionary_master_array.php using the existing structure (root, arabic, english, urdu, vg, form fields).
2. Extend build_combined_token() if a new pattern type is needed, using switch cases with clear IDs.
3. Prefer using centralized CSS & JS (ace_styles.css, ace_scripts.js) instead of inline styles/scripts, whenever possible.
4. For any specialized behavior (e.g. grid/list toggles, Tajweed thumbnail hover effects, etc.), add small reusable helpers to ace_scripts.js and hook them via data-* attributes in the HTML.