بِسْمِ اللّٰهِ الرَّحْمٰنِ الرَّحِيْمِ

Proofreading Workbench & Publishing Guide

An end-to-end interactive manual explaining in-place editing, dual-tier save architecture, automated rebuilds, and multi-format synchronization across all volumes.

0 Everyday Quick-Start Guide (No Technical Experience Needed)

New to digital proofreading or looking for simple step-by-step instructions? Follow these 5 plain-English steps to browse, search, proofread, and print any of the 81 volumes without touching code or terminal commands.

📚
Step 1: Opening Any Book

On the Main Portal, click Tafsīr-e-Ṣiddīqī (32) or Classical Treatises (49), or pick any book from the Fast Jump menu. Choose 📘 Bilingual Edition to read Urdu & English side-by-side, 📖 Urdu Edition for pure Urdu, or 🔍 Proofreading Workbench to compare against the original scanned page.

🔎
Step 2: Searching All 81 Books

Click the green 🔎 Search Corpus button at the top of any page (or press Ctrl + K on Windows / ⌘ + K on Mac). Type any word in English, Urdu, Farsi, Arabic (no vowel marks needed), or a Qur’an number like 2:255. Click Open in Bilingual or Open in Workbench to jump directly to that exact paragraph.

✍️
Step 3: Fixing a Word in 3 Clicks

Inside the Workbench, look at the Left column (original scanned page — use 135% / 175% buttons to zoom in). Click directly on any wrong word in the Middle (Urdu) or Right (English) box, type your correction, and click anywhere outside. Your fix saves automatically in your browser!

Button Name What It Does (In Simple Terms) Who Can Use It?
✏️ Edit in Box Lets you type corrections directly inside Urdu & English paragraphs or leave a note for reviewers. Admin & Editor (Locked for Viewer so nothing is changed by accident)
✓ Mark Page as Verified Puts a green checkmark on the current page once you finish checking every line against the left scan. Admin & authorized Editor
💾 Save Saves your work in your browser session (and writes directly to disk if the local server is running). Users with Save permission
📥 Export JSON / 📄 Markdown Downloads a complete copy of the book’s master data or Markdown file to your computer’s Downloads folder. Users with Export permission (can be restricted separately from Edit/Save)
🖨️ Print / PDF Opens your browser’s Print / Save as PDF dialog to print clean reading pages or create a PDF booklet. Users with Print / PDF permission
🛡️ Understanding Roles & The Admin Console (Admin vs. Editor vs. Viewer)

Notice the user badge in the top-right corner of every page (e.g., 👤 Chief Administrator · 🛡️ Admin). Click it anytime to see what you are allowed to do on the current book, or click 🛡️ Admin Console (ADMIN_CONSOLE.html) if you are an Administrator to:

  • Add individual scholars, proofreaders, or guest readers.
  • Assign Admin, Editor, Viewer, or Restricted roles for one specific book (Per-Item), for several checked books / a whole collection (Multi-Item Batch), or for all 81 books at once (Global).
  • Turn individual buttons (Edit, Verify ✓, Save 💾, Export 📥, Print 🖨️) ON or OFF per person or per book.
  • Click 🎭 Act As User to immediately preview how the library looks for that person.

1 System Architecture & Core Concept

The entire publication pipeline is governed by a Single Source of Truth: the {Volume}_Tafseer_Siddiqi_Master.json database.

Every manuscript page, Qur'anic verse, classical Urdu exegesis block, poetic couplet, and academic English translation exists in this structured master file. When you edit in the workbench, your changes update this master database, which then synchronously compiles all reader editions:

🏛️
Single Source of Truth

The Master JSON holds all verified text, verse identifiers, waqf metadata, editorial flags, and verification checkmarks.

🛠️
Interactive Workbench

A specialized 3-pane editorial workbench with synchronized scan viewing, raw OCR diff inspector, and live in-place editing.

⚡
Instant Rebuilding

Saving from the workbench triggers background recompilation, updating both HTML readers and Markdown files in under 2 seconds.

2 The 3-Pane Workbench Interface

The workbench provides an ergonomic three-column environment designed to eliminate eye fatigue and guarantee absolute textual fidelity:

📖 Tafseer Siddiqi Workbench — 3-Pane Ergonomic Layout ● Synchronized Panes
Left Pane (33%) — Manuscript Scan
📜

High-Resolution Scan

Lithograph Osmania Edition
Zoom: Fit, 135%, 175%, 220%

Center Pane (34%) — Classical Urdu

بِسْمِ اللّٰهِ الرَّحْمٰنِ الرَّحِيْمِ ط ﴿۱﴾

تفسیر: اصل اس مسئلہ میں یہ ہے کہ وہ امور جو اصول و اغراض دین کے خلاف ہیں وہ قابلِ ترک ہیں۔۔۔

[contenteditable="true"]
Right Pane (33%) — Academic English

In the name of Allah, Most Gracious, Ever Merciful ﴿1﴾

Commentary: The fundamental rule in this matter is that practices contradicting the essential objectives of faith...

[contenteditable="true"]
🔍 Bottom Drawer: Raw OCR Diff Inspector

Click the ✨ Highlight Fixes vs OCR button in the top toolbar to toggle the diff inspector. Any word corrected from raw DocAI or UOCR will be highlighted in golden yellow, allowing you to quickly spot what OCR originally misread.

3 How In-Place Editing Works

Every block in both the Urdu and English panes is directly editable:

  1. Click & Type: Click anywhere inside an Urdu commentary block or English translation block. A subtle gold focus border highlights the active card.
  2. Live Auto-Save on Blur: Whenever you click away or navigate to another card or page, the workbench instantly updates its internal database and commits the change to browser localStorage. The status badge will display "Local Saved ✓".
  3. Flagging for AI Re-Translation: If you change the Urdu meaning and want the English translation regenerated, click the ⚑ Flag for AI button on that card. It turns amber and records an editorial flag in the Master JSON.
  4. Marking as Verified: Once you have audited every block on a manuscript page against the left scan, check the Mark Page as Verified box at the top. The progress counter (e.g. 39 / 39 Verified) will update automatically.

4 The Two-Tier Save & Export Architecture

The workbench implements a fail-safe dual-persistence model to guarantee that your edits are never lost:

🛡️
Tier 1: Browser LocalStorage

Frequency: Instantaneous on every card blur.

Scope: Browser memory keyed uniquely per volume (e.g., tafseer_siddiqi_surahfatiha_workbench_v1).

Protection: Survives tab closures, browser reboots, and sudden power outages.

💾
Tier 2: Disk Sync & Auto-Rebuild

Frequency: When you click "Save & Export" or press Ctrl+S.

Scope: Writes JSON directly to disk and invokes build_edition.py.

Result: Immediately regenerates all 4 HTML & Markdown reader files.

⚡ When Do Changes Show Up in Other Versions?

As soon as you click Save & Export while workbench_server.py is running:

  • The Master JSON is updated on disk within milliseconds.
  • The compiler rebuilds the Bilingual HTML and Classical Urdu HTML files in ~1.5 seconds.
  • The Markdown files are re-generated synchronously.
  • To see your changes: Simply refresh your continuous reader browser tab (Ctrl+R or Cmd+R)!

5 Edition Synchronization Matrix

Target Edition File Name Sync Mechanism How to View Changes
Master Database {Volume}_Tafseer_Siddiqi_Master.json Direct file write via POST /api/save-master Inspect in text editor or Git diff
Bilingual HTML Reader {Volume}_Tafseer_Siddiqi_Bilingual.html Recompiled by build_edition.py Refresh browser tab (Ctrl+R)
Classical Urdu Reader {Volume}_Tafseer_Siddiqi.html Recompiled by build_edition.py Refresh browser tab (Ctrl+R)
Academic Markdown {Volume}_Tafseer_Siddiqi_Bilingual.md Re-written with GitHub Flavored Markdown Open in VS Code, Obsidian, or GitHub
Urdu Markdown {Volume}_Tafseer_Siddiqi.md Re-written with classical RTL Markdown Open in any Markdown viewer
Print / PDF Edition Generated via browser print (Ctrl+P) Rendered from continuous HTML Press Ctrl+P in the reader edition

6 Running the Universal Local Server

The repository includes a lightweight Python server (workbench_server.py) that enables zero-friction auto-saving and instant compilation across all 32 volumes.

1. Starting the Server

Open your macOS terminal and run:

cd /Users/atifali/Projects/Tafseer
python3 workbench_server.py
# Or optionally specify a custom port:
# python3 workbench_server.py 8080

2. Terminal Output Confirmation

========================================================================
  📖 TAFSEER SIDDIQI PUBLISHING & PROOFREADING WORKBENCH SERVER
========================================================================
  Status:             ONLINE  (Port 8000)
  Portal:             http://localhost:8000/index.html
  Help & User Guide:  http://localhost:8000/WORKBENCH_HELP.html
------------------------------------------------------------------------
  Muqaddimah:         http://localhost:8000/Muqadama_Proofreading_Workbench.html
  Surah Fatiha:       http://localhost:8000/SurahFatiha_Proofreading_Workbench.html
  Para 1:             http://localhost:8000/Para1_Proofreading_Workbench.html
  Para 2:             http://localhost:8000/Para2_Proofreading_Workbench.html
  Para 3:             http://localhost:8000/Para3_Proofreading_Workbench.html
========================================================================

3. Recommended 2-Tab Scholar Workflow

Tab 1: Editorial Workbench

Keep the workbench open at http://localhost:8000/SurahFatiha_Proofreading_Workbench.html. Perform your page-by-page checks and press Ctrl+S.

Tab 2: Continuous Reader

Keep the reader open at http://localhost:8000/SurahFatiha_Tafseer_Siddiqi_Bilingual.html. Press Ctrl+R to instantly see the published result.

7 Keyboard Shortcuts & Pro Tips

Previous Page ◀ Left Arrow
Next Page ▶ Right Arrow
Save & Export Ctrl + S
Mac Save & Export Cmd + S
Exit Active Field Esc
Print / Save PDF Ctrl + P

8 Troubleshooting & FAQ

Q: What if I see "[Errno 48] Address already in use" when starting the server?

A: This occurs if port 8765 is in use by another service on your computer. The updated workbench_server.py now includes Automatic Port Conflict Resolution—it will automatically detect occupied ports and seamlessly bind to the next available free port (e.g. 8000 or 8080). You can also explicitly specify any port you wish:

python3 workbench_server.py 8000
# or
python3 workbench_server.py 8080

Q: Why does the workbench say "Downloaded Master JSON" instead of saving to disk?

A: This occurs if you opened the workbench directly via file:///Users/... in Finder without running python3 workbench_server.py. Because browser security sandboxes forbid web pages from silently writing to the filesystem without a server, the browser safely downloads the JSON file to your Downloads folder. To enjoy automatic disk saving, simply start python3 workbench_server.py in your terminal and access the workbench through http://localhost:8765/.

Q: How do I audit standards for a volume from the command line?

A: You can verify that all ayahs, waqf marks, and couplets meet 100% of publishing criteria at any time:

python3 .agents/skills/tafseer-publishing/scripts/verify_para.py /Users/atifali/Projects/Tafseer --volume SurahFatiha

Tafsīr-e-Ṣiddīqī Digital Publishing Pipeline — Directed by Bahr al-‘Uloom Research Academy.
Built with Google DeepMind Advanced Agentic Coding.

بِسْمِ اللّٰهِ الرَّحْمٰنِ الرَّحِيْمِ

رہنمائے مطالعہ، تلاش اور پروف ریڈنگ ورک بینچ

کمپیوٹر کی بنیادی واقفیت رکھنے والے قارئین، محققین اور مصححین کے لیے نہایت آسان، قدم بہ قدم اردو گائیڈ — جس میں کتب کے مطالعہ، اردو/عربی/انگریزی الفاظ کی فوری تلاش، متن کی تصحیح اور اجازت ناموں (Admin / Editor / Viewer) کا مکمل طریقہ شامل ہے۔

1 کتاب کھولنے اور پڑھنے کا آسان طریقہ (بغیر کسی پیچیدگی کے)

اس ڈیجیٹل کتب خانے میں کل ۸۱ مستند کتب موجود ہیں: ۳۲ جلدیں تفسیرِ صدیقی کی، اور ۴۹ نادر رسائل و تصانیف۔ آپ کو کوئی پروگرام انسٹال کرنے کی ضرورت نہیں، بس ان آسان بٹنوں کو استعمال کریں:

قدم ۱: کتاب تلاش کریں

مرکزی صفحہ (Portal) پر اوپر تین بٹن ہیں: تمام ۸۱ جلدیں، تفسیر صدیقی (۳۲)، اور علمی رسائل و مخطوطات (۴۹)۔ یا اوپر مینو میں ⚡ جلد تبدیل کریں سے براہِ راست کسی کتاب پر کلک کریں۔

قدم ۲: اپنا پسندیدہ ایڈیشن کھولیں

کتاب کے اندر اوپر والی پٹی سے آپ ایک کلک میں رخ بدل سکتے ہیں:
• 🌐 دو لسانی: اردو اور انگریزی آمنے سامنے۔
• 📜 اردو اصل: صرف خالص اردو اور عربی کتاب۔
• 🔤 انگریزی: صرف انگریزی ترجمہ۔
• 🛠️ ورک بینچ: اصل اسکین سے مقابلہ اور تصحیح۔

قدم ۳: پڑھتے وقت سہولیات

کتاب کے اندر اوپر والی پٹی پر A+ / A- سے حروف بڑے یا چھوٹے کریں، روشن / قدیم / تاریک سے تھیم بدلیں، EN | اردو سے زبان بدلیں، اور 🔖 نشانات سے کسی بھی سطر پر نشانی لگائیں۔

2 کثیر لسانی مکمل تلاش (اردو، عربی، فارسی اور انگریزی)

اب آپ تمام ۸۱ کتب کے ۳۴,۱۳۶ پیراگراف، آیات، احادیث اور اشعار کے اندر بیک وقت کوئی بھی لفظ یا جملہ تلاش کر سکتے ہیں۔

🔎 تلاش کھولنے کا طریقہ: کسی بھی صفحہ کے اوپری مینو میں 🔎 تلاش بٹن پر کلک کریں (یا کی بورڈ پر Ctrl+K / میک پر ⌘+K دبائیں)۔

دکنی / حیدرآبادی اور جدید اردو دونوں چلیں گے

اگر آپ جدید املا میں "یعنی"، "کیونکہ" یا "ہوئے" لکھیں گے تب بھی کتاب کے قدیم املا "یعنے"، "کیونکے" اور "ہوے" والے تمام مقامات خودبخود سامنے آ جائیں گے۔

عربی اور قرآنی آیات (اعراب کے بغیر بھی)

زیر، زبر، پیش لگانے کی ضرورت نہیں۔ بس سادہ عربی لکھیں یا سورت اور آیت کا نمبر لکھیں (مثلاً 2:255)، متعلقہ آیت اور اس کی تفسیر فوراً نکل آئے گی۔

براہِ راست مطلوبہ سطر پر پہنچیں

تلاش کے نتائج میں اردو اور انگریزی دونوں دکھائی دیتے ہیں۔ دو لسانی اشاعت یا ورک بینچ پر کلک کرتے ہی آپ عین اسی صفحہ اور اسی سطر پر پہنچ جائیں گے۔

3 پروف ریڈنگ ورک بینچ کے تین خانوں کی پہچان

ورک بینچ کھولنے پر اسکرین تین برابر حصوں میں تقسیم نظر آتی ہے تاکہ آپ آسانی سے اصل کتاب کا صفحہ دیکھ کر کمپوز شدہ متن کی تصحیح کر سکیں:

۱. اصل صفحہ کی تصویر (Scan)

یہاں مطبوعہ یا قلمی کتاب کا اصل اسکین صفحہ نظر آتا ہے۔ اوپر موجود Fit, 135%, 175%, 220% بٹنوں سے صفحہ کو بڑا کر کے باریک خط آسانی سے پڑھیں۔

۲. اردو / عربی متن (قابلِ ترمیم)

درمیان میں ٹائپ کیا ہوا اردو اور عربی متن ہوتا ہے۔ اگر آپ کے پاس Editor / مصحح کا حق ہے تو کسی بھی ڈبے پر کلک کر کے ٹائپ کر سکتے ہیں۔

۳. انگریزی ترجمہ (Academic English)

تیسرے خانے میں ہر پیراگراف کے سامنے اس کا مستند انگریزی ترجمہ ہوتا ہے، جسے بوقتِ ضرورت درست کیا جا سکتا ہے۔

4 متن میں غلطی درست کرنے کے ۳ نہایت آسان قدم

۱۔ کلک کریں اور ٹائپ کریں

درمیانی (اردو) یا دائیں (انگریزی) خانے میں جہاں غلطی نظر آئے، وہاں ماؤس سے کلک کریں۔ اس ڈبے کے گرد سنہرا کنارہ بن جائے گا۔ اب کی بورڈ سے صحیح لفظ لکھ دیں۔

۲۔ باہر کلک کریں (خودکار محفوظ)

ٹائپ کرنے کے بعد کہیں بھی باہر کلک کر دیں۔ آپ کی تبدیلی فوراً آپ کے براؤزر میں محفوظ ہو جائے گی۔ اگر ترجمہ دوبارہ کرانا ہو تو کارڈ پر ⚑ Flag بٹن دبا دیں۔

۳۔ صفحہ کی تصدیق (Verified ✓) کریں

جب پورے صفحے کا مقابلہ مکمل ہو جائے تو اوپر تصدیقِ صفحہ (Verify Page) کے چوکور خانے پر ٹِک (✓) لگا دیں تاکہ معلوم رہے کہ یہ صفحہ مکمل جانچا جا چکا ہے۔

5 اہم فرق: Edit، Save، Export اور Print میں کیا فرق ہے؟

بٹن / عمل اس کا آسان مطلب کب استعمال کریں؟
✏️ ترمیم (Edit) اسکرین پر عبارت یا حاشیہ (Note) تبدیل کرنا۔ جب آپ کسی لفظ کی املا یا ترجمہ درست کر رہے ہوں۔
💾 محفوظ کریں (Save) آپ کی کی گئی اصلاحات کو سیشن میں (یا لوکل سرور چل رہا ہو تو براہِ راست ڈسک پر) پکا محفوظ کرنا۔ کام کے دوران اور صفحہ مکمل کرنے کے بعد دبا دیں۔
📥 برآمد (Export JSON / MD) پوری کتاب کی ماسٹر فائل (.json یا .md) اپنے کمپیوٹر کے Downloads فولڈر میں ڈاؤن لوڈ کرنا۔ جب آپ کو بیک اپ فائل محفوظ کرنی ہو یا کسی دوسرے کو بھیجنی ہو۔
🖨️ پرنٹ / پی ڈی ایف (Print / PDF) کتاب کے صفحات کو کاغذ پر پرنٹ کرنا یا PDF فائل کے طور پر محفوظ کرنا۔ پڑھنے کے ایڈیشن یا ورک بینچ سے پرنٹ نکالنے کے لیے۔

6 رسائی اور اختیارات کا نظام (Admin ،Editor اور Viewer)

ایڈمن ہر فرد کو الگ الگ کتاب (Per-Item)، کئی کتابوں کے مجموعے (Multi-Item Batch)، یا پوری ۸۱ کتب (Global) کے لیے الگ کردار اور اختیارات دے سکتا ہے:

🛡️ منتظمِ اعلیٰ (Admin)

مکمل اختیار۔ نئے افراد کا اندراج یا ترمیم کر سکتا ہے، ہر فرد کے لیے کتاب وار یا مجموعی اجازتیں مقرر کر سکتا ہے، اور تحریری، محفوظ، برآمد یا پرنٹ کے بٹن کھول یا بند کر سکتا ہے۔

✍️ مصحح / مدیر (Editor)

متن کی اصلاح کر سکتا ہے، نوٹ لکھ سکتا ہے، اور حسبِ اجازت صفحہ کی تصدیق (✓)، Save یا Export کر سکتا ہے۔ ایڈمن چاہے تو کسی کو صرف Edit کی اجازت دے اور Export بند رکھے۔

👁️ قاری / ناظر (Viewer)

صرف مطالعہ کر سکتا ہے (Read-Only)۔ ورک بینچ کھلنے پر بھی ٹائپ کرنے کا خانہ بند رہے گا تاکہ غلطی سے متن نہ بدلے۔ Print/PDF کی اجازت ایڈمن کی مرضی پر منحصر ہے۔

💡 اپنا موجودہ درجہ کیسے دیکھیں؟ ہر صفحہ کے اوپر دائیں کونے میں 👤 [آپ کا نام · کردار] بٹن موجود ہے۔ اس پر کلک کر کے آپ اپنے اختیارات دیکھ سکتے ہیں یا (اگر ایڈمن ہوں تو) ایڈمن کنسول کھول کر دوسرے صارف کا کردار ٹیسٹ کر سکتے ہیں۔

7 آسان کی بورڈ شارٹ کٹس اور عام سوالات (FAQ)

شارٹ کٹ کلید اس سے کیا ہوتا ہے؟
Ctrl + K یا ⌘ + K فوراً کثیر لسانی سرچ باکس (۸۱ کتب میں تلاش) کھل جاتا ہے۔
◀ Left / ▶ Right ورک بینچ میں پچھلے یا اگلے صفحے پر جائیں (جب ٹیکسٹ باکس سے باہر ہوں)۔
Ctrl + S یا ⌘ + S تبدیلیاں محفوظ کریں (Save)۔
Ctrl + P یا ⌘ + P موجودہ صفحہ یا کتاب پرنٹ / PDF کریں (اگر پرنٹ کی اجازت فعال ہو)۔

سوال: اگر کسی کتاب پر "🔒 Restricted" یا "🔒 محدود" لکھا آئے تو کیا کریں؟

اس کا مطلب ہے کہ موجودہ لاگ ان صارف کو اس کتاب یا اس فنکشن (مثلاً برآمد یا پرنٹ) کی اجازت نہیں دی گئی۔ اگر آپ منتظم (Admin) ہیں تو ADMIN_CONSOLE.html میں جا کر اپنا صارف "Chief Administrator" منتخب کریں یا اس کتاب کے لیے اجازت کھول دیں۔