מנהל הקישורים — אוצריא

כלי ליצירת קובצי הקישורים של אוצריא: הקבצים שמחברים בין ספר לפירוש שלו, בין גמרא למפרשים, בין טקסט להערות. הכלי קורא בלבד — הוא לא נוגע במסד הנתונים שלכם ולא משנה שום קובץ קיים. בסוף העבודה מקבלים קובצי _links.json להעתקה ל־otzaria-library.

הכלי הוא קובץ אחד: index.html. פותחים בכל דפדפן — גם בלחיצה כפולה מהמחשב, גם בלי חיבור לאינטרנט. אין התקנה, אין שרת, אין תלות חיצונית.

עובד על מחשב, טאבלט וטלפון, במצב בהיר ובמצב כהה. הכפתור 💾 בהגדרות שומר עותק עצמאי של הכלי — קובץ אחד שאפשר להעביר בדיסק־און־קי ולפתוח במחשב מנותק לגמרי.

מסמך	למי
README.md (כאן)	מדריך משתמש — מתחילים ומתקדמים
DEVELOPERS.md	מפתחים שמתחזקים או שולחים PR
AGENTS.md	כלי AI שעורכים את הקוד
קישורים-וכותרות.md ב־otzaria-library	מקור האמת לפורמט הקישורים ב־seforim.db

המסמך הזה מתעדכן מעת לעת במאגר Otzaria/otzaria-library. אין כאן עותק מקומי בכוונה — עותק כזה מתיישן והופך למקור אמת שקרי. לפני כל שינוי בפורמט הקישורים, קראו את הגרסה שם.

יש גם עזרה מלאה בתוך הכלי — כפתור ? בסרגל העליון, או F1.

---

תוכן

• 1. התחלה מהירה
• 2. חיבור מקורות
• 3. מסך העורך
• 4. יצירת קישור
• 5. חמשת מבני הקישור
• 6. סוגי הקשר — מפרשים מול קישורים
• 7. טווחים
• 8. עוגן על מילה
• 9. יצירה אוטומטית
• 10. מבני כותרות אלטרנטיביים
• 11. ייצוא
• 12. ספרי ספריא ו־ref_2 — אזהרה חשובה
• 13. הגדרות
• 14. קיצורי מקלדת
• 15. פתרון תקלות
• 16. על מה הכלי נבדק

---

1. התחלה מהירה

1. פותחים את index.html בדפדפן (Chrome, Edge, Firefox — כולם עובדים).
2. מחברים מקור. אם אוצריא מותקנת אצלכם — בחרו "מסד הנתונים של אוצריא" והצביעו על הקובץ seforim.db. אם אתם עובדים על קובצי טקסט — "קובצי טקסט" או "תיקיית ספרים".
3. "כניסה לעורך".
4. בעמודת הספרים, ודאו ש"פתיחת ספר אל" מכוון למקור, ולחצו על ספר. אחר כך העבירו ליעד ולחצו על ספר שני.
5. לחצו על שורה במקור, ואז על שורה ביעד.
6. בבונה שבעמודה האמצעית בחרו מבנה וסוג קשר, קראו את משפט הסיכום, ולחצו "יצירת הקישור".
7. בסוף — "ייצוא" בסרגל העליון. מקבלים קובץ ZIP.

טעות? Ctrl+Z מבטל כל פעולה. כפתור ההיסטוריה מאפשר לחזור לכל נקודה בעבודה.

הכלי לא שולח שום דבר לשום מקום, ולא כותב למסד. כל העבודה מקומית בדפדפן.

---

2. חיבור מקורות

מקור	מתי להשתמש	הערות
מסד הנתונים	יש לכם את אוצריא במחשב	seforim.db. גם קובץ של 8 ג'יגה נפתח מיד — ראו למטה
קובצי טקסט	ספר שעדיין לא נכנס למסד	כל שורה בקובץ = שורה בספר
תיקיית ספרים	ספרייה מקומית שלמה	כולל תת־תיקיות; רק קובצי .txt
קישורים קיימים	ממשיכים לערוך _links.json	משויך לספר המקור לפי שם הקובץ

אפשר לחבר כמה מקורות יחד — למשל את המסד המלא וגם קובץ txt חדש.

קבצים גדולים

מסד גדול מ־700 מ"ב (הסף ניתן לשינוי בהגדרות) נקרא בקריאה עצלה: הכלי קורא ישירות מהדיסק רק את עמודי ה־SQLite שהוא צריך, במקום להעלות את כל הקובץ לזיכרון. בפועל: רשימה של 7,293 ספרים מ־seforim.db נטענת בכ־130 מילישניות.

ספר־צל

כשמייבאים קובץ קישורים שמצביע לספר שלא נטען, נוצר "ספר־צל" — שם בלי טקסט. הקישורים אליו נשמרים ומיוצאים כרגיל, אבל אי אפשר לראות את שורותיו. כדי לראות אותן, טענו גם את הספר עצמו.

---

3. מסך העורך

ארבע עמודות:

#	עמודה	מה בה
1	ספרים	חיפוש, סינון, ובורר "פתיחת ספר אל: מקור / יעד"
2	מקור	הספר שממנו יוצא הקישור
3	קישורי השורה + הבונה	למעלה הקישורים של השורה הנבחרת, למטה טופס היצירה
4	יעד	הספר שאליו הקישור מוביל

• העמודה הפעילה (זו שאליה ייפתח הספר הבא) מסומנת בפס עליון צבעוני ובתווית "פעיל".
• שורות שכבר יוצא מהן קישור מסומנות בפס צבעוני בצד.
• לחיצה על כותרת עמודה ← כפתורי חיפוש בטקסט, תוכן עניינים, ועורך מבני הכותרות האלטרנטיביים.

בחירת שורות

פעולה	תוצאה
לחיצה	בחירת שורה אחת
Shift + לחיצה	טווח רצוף מהשורה הקודמת. בסוגי טווח — קובע גם את שורת הסיום
Ctrl + לחיצה	הוספה/הסרה של שורה בודדת

---

4. יצירת קישור

הבונה מוביל בארבעה שלבים, וכל שלב מסומן בוי כשהוא מוכן:

1. מקור — השורות שנבחרו בעמודת המקור.
2. יעד — השורה שנבחרה בעמודת היעד.
3. מבנה הקישור — שורה, טווח, או עוגן על מילה. מתחת לבורר מופיע הסבר על הבחירה.
4. סוג הקשר — פירוש, תרגום, הפניה… זה קובע באיזה פאנל באוצריא הקישור יופיע.

לפני היצירה מופיע משפט סיכום בעברית פשוטה שמתאר בדיוק מה ייכתב לקובץ. אם משהו לא נכון — תקנו לפני הלחיצה. אזהרות רלוונטיות (שורת כותרת, טווח לא תקין, ref_2 חסר) מוצגות באותו מקום.

יצירה מרובה

במבנה "שורה ↔ שורה", אם בחרתם כמה שורות במקור — ייווצר קישור נפרד מכל אחת מהן אל שורת היעד.

---

5. חמשת מבני הקישור

מבנה	מה נכתב לקובץ	מתי
שורה ↔ שורה	line_index_1, line_index_2	המקרה הרגיל
טווח ↔ טווח	+ line_index_1_end וגם line_index_2_end	פרשה שלמה ↔ כל הפירוש עליה
שורה במקור ↔ טווח ביעד	+ line_index_2_end בלבד	סעיף אחד ↔ כמה שורות ביאור
טווח במקור ↔ שורה ביעד	+ line_index_1_end בלבד	כמה שורות ↔ הערה אחת
מילה ↔ שורה	+ start, end	סמן (א)(ב) בתוך הטקסט

---

6. סוגי הקשר — מפרשים מול קישורים

אוצריא מחלקת את כל הקישורים לשתי קבוצות ומציגה כל אחת בפאנל אחר. סוג הקשר הוא שקובע.

יופיעו בפאנל המפרשים — ורק אלה: commentary · super_commentary · targum · midrash · parshanut · dibur_hamatchil · elucidation · explication

יופיעו בפאנל הקישורים — כל השאר: reference · quotation · source · mesorat hashas · ein mishpat · mishnah in talmud · related · linker · allusion · liturgy · law · summary · sifrei mitsvot · essay · other

אם בחרתם למשל allusion וציפיתם שיופיע בפאנל המפרשים — זה לא יקרה. הכלי מציין מתחת לבורר, בזמן אמת, לאיזה פאנל הקישור ילך.

---

7. טווחים

זו הנקודה שהכי קל לטעות בה. כדאי להבין את המבנה:

לקישור יש תמיד שורת התחלה אחת בכל צד. שורת ההתחלה נכתבת בשדה הרגיל — line_index_1 במקור, line_index_2 ביעד. כדי לומר "הקישור ממשיך עוד כמה שורות", מוסיפים שדה אחד לכל צד שמכיל את שורת הסיום בלבד:

{
  "line_index_1": 39,
  "line_index_2": 12,
  "line_index_2_end": 15,
  "heRef_2": "גמרא דף ג-ה",
  "path_2": "גמרא.txt",
  "Conection Type": "commentary"
}

הקישור יוצא משורה 39 במקור, ומכסה ביעד את השורות 12–15.

• אין שדה נפרד ל"תחילת הטווח". ההתחלה היא תמיד line_index_X עצמו.
• line_index_1_end שייך אך ורק לצד המקור; line_index_2_end אך ורק לצד היעד. שני הצדדים עצמאיים לגמרי — אפשר טווח רק במקור, רק ביעד, או בשניהם.
• טווח שסיומו שווה להתחלה = קישור רגיל, ושדה ה־_end לא נכתב כלל.

מילוי אוטומטי של שורת הסיום

ברוב המקרים הכלל פשוט: הטווח מתחיל בשורה שסימנתם ומסתיים שורה אחת לפני הקישור הבא. לכן, כשבוחרים מבנה טווח, הכלי ממלא את שדה "עד שורה" לבד לפי הכלל הזה. תמיד אפשר:

• להקליד ערך אחר בשדה,
• לגרור בחירה עם Shift,
• ללחוץ "עד הבא" (חישוב מחדש) או "עד הסוף".

בנוסף, כשנוצר טווח חדש, הטווח שלפניו מתקצר אוטומטית כדי שלא יבלע אותו (ניתן לכיבוי בהגדרות).

השלמת טווחים בדיעבד

יצרתם קודם הרבה קישורים ורק אחר כך החלטתם שהם צריכים להיות טווחים? קישור אוטומטי ← השלמת טווחים. הכלי עובר על כל הקישורים בספר ומשלים לכל אחד שורת סיום עד הקישור הבא, האחרון עד סוף הספר. יש תצוגה מקדימה לפני האישור, והפעולה הפיכה.

מה עלול להישמט

שורת סיום לפני ההתחלה, מעבר לסוף הספר, או שורת כותרת — הטווח יושמט אבל הקישור יישמר. הכלי מתריע על כך מראש בבונה ושוב בדוח הייצוא. שורות כותרת בתוך הטווח מדולגות אוטומטית ואינן בעיה.

---

8. עוגן על מילה

זה מה שמייצר את הסמנים הקטנים בתוך הטקסט — כמו האותיות (א)(ב)(ג) שמפנות לשער הציון.

1. בוחרים במבנה "מילה במקור ↔ שורה ביעד".
2. מסמנים בעכבר את המילה או הסימן בתוך שורת המקור.
3. נפתח חלון — כותבים את האות שתוצג (למשל ג) או משאירים ריק.
4. בוחרים שורת יעד ויוצרים.

בקובץ נכתבים start ו־end — מיקום התו בשורה כולל תגיות ה־HTML. הכלי מחשב את זה לבד מהטקסט כפי שהוא נראה על המסך. הסמן נשמר בתוך heRef_2 בצורה … אות ג.

העוגן תמיד יושב על צד המקור. אם רוצים שהסמן יופיע בספר א' ויוביל לספר ב' — ספר א' צריך להיות המקור.

---

9. יצירה אוטומטית

כפתור "קישור אוטומטי". בכל השיטות מקבלים תצוגה מקדימה ואפשר לבטל התאמות בודדות לפני היצירה. הכול הפיך ב־Ctrl+Z.

שיטה	מה עושה	מתי מתאימה
לפי כותרות	מזהה כותרות זהות בשני הספרים ומקשרת ביניהן	שולחן ערוך ↔ משנה ברורה
לפי תגיות	מחפשת <sup>ג</sup> ומשתמשת בתוכן כמספר שורת היעד	ספר עם הערות ממוספרות
לפי תבנית	Regex; הקבוצה בסוגריים = מספר שורת היעד	"עיין סימן קנ", "דף ג"
השלמת טווחים	ממלאת שורת סיום לכל קישורי הטווח בספר	ראו פרק 7

"לפי כותרות" — שלושה מצבי התאמה:

• לפי תוכן הכותרת (מומלץ) — משווה טקסט, מעדיף התאמה שגם ההורה שלה תואם.

• לפי מבנה מדויק — דורש שרשרת כותרות זהה משורש הספר.

• רק תתי־סעיפים — רק כותרות שאין תחתיהן כותרות.

  ובנוסף: "התייחס לפסקאות רגילות כאל סעיפים" — אם מספר הפסקאות תחת כותרת במקור שווה למספר הסעיפים ביעד, הן יפוצלו אחת לאחת.

התאמה גמישה לכתיב

מסומנת כברירת מחדל ב"לפי כותרות". היא מגשרת על ההבדלים שמפילים התאמה מדויקת:

מה מגושר	דוגמה
ניקוד וטעמים	שְׁמַע = שמע
גרשיים	רש"י = רשי
ראשי תיבות מבניים	סי׳ יב = סימן יב · ס"ק ג = סעיף קטן ג
אותיות שימוש	לבית ≈ בית
כתיב מלא/חסר	מצווה ≈ מצוה · יושבין ≈ יושבים
שגיאת כתיב קלה	מילה בת 4–6 אותיות — עד שינוי אחד; 7 ומעלה — עד שניים

מילים קצרות (עד 3 אותיות) חייבות תמיד התאמה מדויקת, כדי ש־לא ו־לה לא ייחשבו זהות.

כל התאמה מקבלת אחוז ודאות, והתצוגה המקדימה מחלקת אותן לשלוש דרגות: ≥95% "ודאי" (ירוק), ≥85% "כנראה" (צהוב), ומתחת לזה "לבדיקה" (אדום). כפתורי הסינון מאפשרים לסמן רק את הוודאיות, או ודאי+כנראה, בלחיצה אחת.

המנגנון מאומץ ממחולל הקישורים otzaria-link-generator ומצומצם למה שדרוש להשוואת כותרות.

"לפי תגיות" / "לפי תבנית" — יש אפשרות "קובץ ההערות מחולק לפרקים". סמנו אותה כשהמספור ביעד מתחיל מחדש אחרי כל כותרת (א, ב, ג… ואז שוב א, ב, ג).

---

10. מבני כותרות אלטרנטיביים

זה לא קישור אלא תוכן עניינים שני, שמוצג באוצריא לצד הרגיל — חלוקה אחרת של אותו ספר, לאותן שורות בדיוק.

הדוגמה המוכרת ביותר היא בראשית: לצד פרק א'…פרק נ' יש גם פרשות, ותחת כל פרשה עליות. אבל זו רק דוגמה אחת. אפשר לבנות כל חלוקה שנוחה ללומד — ימי לימוד, נושאים, מחזור שנתי, סדר הדף היומי. ספר יכול לשאת כמה מבנים במקביל.

פותחים מכפתור העץ בכותרת עמודת המקור. לכל מבנה נותנים:

• key באנגלית — מזהה יציב, אין לשנות אחרי הפרסום הראשון,
• כותרת תצוגה בעברית,
• צמתים: רמה 0 = הרמה העליונה, רמה 1 = מה שתחתיה, וכן הלאה ללא הגבלת עומק.

שני כפתורי עזר חוסכים הקלדה:

• "מילוי מכותרות הספר" — בונה שלד מכל תגיות ה־<h> שבספר, ומשם עורכים.
• "מספור בגימטריה" — נותן לכל צמתי המשנה שם רץ: "עליה א", "עליה ב"… בוחרים את מילת הבסיס, והמונה מתאפס בכל הורה. זה בדיוק מה שספריא עושה אוטומטית בבניית העליות שלה.

הקובץ שנוצר, alt_toc/<שם הספר>_alt_toc.json, אוטוריטטיבי: מה שאין בו נמחק מהמסד בבנייה הבאה.

---

11. ייצוא

קובץ ה־ZIP מכיל בדיוק את המבנה הנדרש:

links/<שם ספר המקור>_links.json
alt_toc/<שם הספר>_alt_toc.json
_report.txt

מעתיקים את links/ ואת alt_toc/ אל otzaria-library, ליד תיקיית הספרים. _report.txt הוא בשבילכם — סיכום ואזהרות; אין להעתיק אותו.

לפני הייצוא מוצגת בדיקה מקדימה:

• שגיאות באדום יפילו את הפייפליין השבועי — כדאי לתקן.
• אזהרות הן דברים שיושמטו בשקט (טווח לא תקין, קישור משורת כותרת).

פורמטים נוספים: קובצי JSON נפרדים, או CSV בפורמט ספריא (מתקדם, לא תומך בטווח/עוגן).

אם פתחתם את הכלי מאתר ולא מקובץ מקומי, יופיע בפינה כפתור "הורדת הכלי לעבודה אופליין" — הוא שומר עותק עצמאי, קובץ אחד שעובד בלי רשת. מקובץ מקומי הכפתור לא מוצג, כי הקובץ כבר אצלכם.

שם השדה בקובץ הוא "Conection Type" עם n אחת. זו שגיאת כתיב היסטורית של ספריא שנשמרת בכוונה. הכלי כותב אותה נכון — אין לתקן ידנית.

---

12. ספרי ספריא ו־ref_2 — אזהרה חשובה

ספרי ספריא — תנ"ך, תלמוד בבלי, רש"י, תוספות, משנה תורה — מיובאים מחדש כל שבוע, ומספרי השורות בהם זזים. לכן קישור שמצביע לספר של ספריא חייב לשאת מזהה יציב:

• ref_2 — כשהיעד הוא ספר של ספריא.
• ref_1 — כשהמקור הוא ספר של ספריא.
• אסור ששניהם יופיעו יחד, ואסור ששני הצדדים יהיו של ספריא.

ה־ref הוא ציטוט ספריא באנגלית: Mishneh Torah, Foreign Worship and Customs of the Nations 4:7, או לתלמוד Yevamot 3b:5.

ממלאים בבונה תחת "אפשרויות מתקדמות", או בחלון עריכת הקישור.

איך הכלי יודע

• אם טענתם מסד — לפי טבלת source שבתוכו.
• אם טענתם את sefaria_he_titles.txt (מסך המקורות ← אפשרויות מתקדמות) — לפי התאמת מחרוזת מדויקת, בדיוק כמו הפייפליין.

מלכודת הגרשיים: תוספות על יבמות מזוהה כספריא, אבל רשי על יבמות לא — כי בספריא הכותרת היא רש"י על יבמות. במקרה כזה אסור למלא ref_2; ref_2 מיותר מפיל את הפייפליין בדיוק כמו ref_2 חסר.

---

13. הגדרות

גלגל השיניים בסרגל העליון. ההגדרות נשמרות בדפדפן.

קבוצה	מה יש בה
תצוגה	ערכת נושא (אוטומטי/בהיר/כהה), צפיפות (מרווחת / רגילה / צפופה / צפופה מאוד), שורות בכל טעינה, טעינה בגלילה
יצירת קישורים	מבנה וסוג ברירת מחדל, אישור לפני מחיקה
טווחים	מילוי אוטומטי של הסיום, מהו "הסמן הבא", קיצור הטווח הקודם
בדיקות	אזהרה על שורות כותרת, אימות ref_1/ref_2
מתקדם	מצב מתקדם, סף הקריאה העצלה, הזחת ה־JSON, יומן מפורט

"מהו הסמן הבא" קובע לפי מה מחושבת שורת הסיום המוצעת: קישור קיים, שורת כותרת, שניהם (ברירת המחדל), או תמיד עד סוף הספר.

מצב מתקדם חושף שדות שנחוצים רק במקרים נדירים (למשל ref_1).

בתחתית ההגדרות: "הרצת בדיקות עצמיות" (93 בדיקות על פורמט הייצוא, הטווחים, העוגנים, ref_2 ושלמות המצב) ו־ "שמירת עותק של הכלי".

---

14. קיצורי מקלדת

קיצור	פעולה
Ctrl+Enter	יצירת הקישור
Ctrl+Z / Ctrl+Y	בטל / בצע שוב
Ctrl+F	חיפוש בטקסט המקור
Ctrl+E	ייצוא
Ctrl+H	היסטוריה
F1	עזרה
Esc	סגירת תפריט → חלון → מגירת היומן → ביטול מצב בחירה
↑ ↓ Enter	ניווט ובחירה בתפריט פתוח

יומן הפעולות נסגר גם בלחיצה בכל מקום אחר על המסך, לא רק ב־✕.

---

15. פתרון תקלות

"לא ניתן לקרוא את הקובץ" סגרו את אוצריא — היא נועלת את המסד. אם הקובץ ב־OneDrive/Drive, לחצו עליו ימני ובחרו "שמור תמיד במכשיר זה".

"זהו מסד נתוני־המשתמש, לא מסד הספרים" בחרתם מסד לא נכון. הקובץ הנכון הוא seforim.db.

קישור טווח קישר רק את השורה הראשונה שדה "עד שורה" נשאר ריק או שווה לשורת ההתחלה. ודאו שההגדרה "מילוי אוטומטי של שורת הסיום" דלוקה, או השתמשו ב"השלמת טווחים". ראו פרק 7.

הקישור לא מופיע בפאנל המפרשים באוצריא סוג הקשר אינו אחד משמונת סוגי המפרש. ראו פרק 6.

הקישור פשוט לא נוצר בבנייה בדקו שאף אחד משני הקצוות אינו שורת כותרת — הגנרטור מדלג עליהם.

האייקונים מופיעים כשמות באנגלית (swap_horiz, download…) זו הייתה תקלה בגרסאות קודמות, שנבעה מפונט אייקונים שנטען מהאינטרנט. בגרסה הזו כל האייקונים מוטמעים בקובץ כ־SVG ואינם דורשים רשת. אם זה בכל זאת קורה — הקובץ נחתך בהורדה; הורידו אותו מחדש.

הפייפליין נופל ב־new_target_ref_required חסר ref_2 בקישור לספר של ספריא. ראו פרק 12.

---

---

16. על מה הכלי נבדק

הכול נבדק בדפדפן אמיתי לפני כל שחרור. חבילת הבדיקות עצמה חיה בתוך הקובץ — אפשר להריץ אותה בכל רגע: index.html?selftest, או הכפתור בתחתית ההגדרות.

מה	היקף	תוצאה
בדיקות בתוך הקובץ	פורמט הייצוא, טווחים, עוגנים, ref_2, גימטריה, שלמות המצב, דחיית ייבוא פגום, נגישות	93/93
בדיקות ממשק (לפני שחרור)	52 בדיקות מקצה לקצה, כולל פתיחת כל דיאלוג	52/52
מקלדת ונגישות	ניווט בתפריטים, מלכודת פוקוס, סדר Esc, תוויות	8/8
הלוך-חזור	ייבוא _links.json → ייצוא → השוואה	זהה
רספונסיביות ומצב לילה	14 גדלי מסך × 2 ערכות × 6 מסכים	168/168 נקי
עבודה ללא רשת	כולל הרצת החבילה על העותק העצמאי שהכלי מייצר	14/14

גדלי המסך שנבדקו: 360×740, 390×844, 430×932, 844×390 (טלפון לרוחב), 768×1024, 1024×768, 1280×720, 1366×768, 1440×900, 1600×900, 1920×1080, 2560×1440, ועוד שתי נקודות בדיוק סביב נקודת השבירה (999 ו־1001).

בכל אחד מהם נבדק: אין גלילה אופקית, אין אלמנט שיוצא מהמסך, יעדי המגע גדולים מ־36 פיקסלים במכשירי מגע, אין טקסט שנחתך, וכל טקסט עומד ביחס הניגודיות של WCAG AA (4.5:1, או 3:1 לטקסט גדול) — בשתי הערכות.

---

רישיון ותרומות

הכלי הוא חלק מהמאמץ סביב אוצריא. דיווח על באגים והצעות — דרך ה־Issues של המאגר. לפני שליחת PR קראו את DEVELOPERS.md והריצו את הבדיקות: index.html?selftest.