פרסואיד

מיזמים של קרן ויקימדיה Parsoid מנתח תחביר דו־כיווני לוויקיטקסט, הפועל בזמן ריצה. ממיר הלוך ושוב בין ויקיטקסט לבין DOM של HTML/XML עם RDFa. קבוצה: Content Transform Team התחלה: 2011-10 חברות וחברי הצוות: Arlo Breault, C.Scott Ananian, Isabelle Hurbain-Palatin, Mateus Santos, Otto Šleger, Subramanya Sastry, Yiannis Giannelos משימות ממתינות: #parsoid הובלה: C.Scott Ananian ניהול: Sérgio Lopes עדכונים: Parsoid/Releases התקדמות: Parsoid/Deployments

פרסואיד (Parsoid) היא ספריית PHP המשמשת להמרה הלוך ושוב בין ויקיטקסט ל־HTML. היא נמצאת בפיתוח מאז 2012. במקור היא נכתבה ב־JavaScript ונועדה לתמוך ב־VisualEditor . היא כלולה במדיה־ויקי החל מגרסה 1.35. במדיה־ויקי 1.47, פרסואיד מתוכננת להפוך למנתח התחביר המוגדר כברירת מחדל במדיה־ויקי, ולהחליף את מנתח התחביר המובנה הנוכחי במסגרת מיזם המכונה איחוד מנתחי התחביר .

פרסואיד היא יישום המאפשר המרה הלוך ושוב בין תחביר הוויקיטקסט של מדיה־ויקי לבין מודל מסמך HTML/RDFa מקביל, עם תמיכה משופרת בעיבוד אוטומטי ובעריכה עשירה.

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

פרסואיד נועדה לספק המרה מדויקת הלוך ושוב, כלומר למנוע אובדן מידע וגם למנוע הבדלים מיותרים בהשוואת גרסאות („dirty diffs”).

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

למידע נוסף על המיזם בכללותו, ראו רשומה זו בבלוג ממרץ 2013. למידע על מודל ה־HTML שבשימוש, ראו מפרט ה־DOM של מדיה־ויקי.

במקור, פרסואיד נבנתה כשירות רשת ונכתבה ב־JavaScript, תוך שימוש ב־Node.js. הרצאה טכנית מפברואר 2019 (שקופיות) ורשומה בבלוג מתארות את תהליך הסבתה ל־PHP. ה־API להרחבות של פרסואיד נמצא כעת בפיתוח פעיל; הרצאה טכנית מאוגוסט 2020 מתארת עבודה זו.

מאגר GitHub: https://github.com/wikimedia/parsoid

• Parsoid/Releases – רשימת הגרסאות שפורסמו לפרסואיד
• Parsoid/API – עבור ה־API של שירות הרשת
• MediaWiki DOM spec – להבנת ה־HTML המתקבל מה־API, שנועד לשמש גם כתסדיר אחסון בעתיד
• Parsoid/LanguageConverter – הערות על המימוש של LanguageConverter בפרסואיד
• Parsoid/Known differences with Core Parser output

פרסואיד כלולה במדיה־ויקי החל מגרסה 1.35. אין צורך בהגדרות כלשהן כדי להפעיל אותה.

פרסואיד חושפת REST API פנימי, ששימש בעבר את RESTBase ולא היה נגיש מחוץ לאשכול השרתים הפנימי של קרן ויקימדיה. הוא כבר אינו נדרש לעורך החזותי או לתצוגות הקריאה של הליבה. ה־API הפנימי מוצא משימוש ומתוכנן להסרה במדיה־ויקי 1.43.

פרסואיד היא ביסודה ספריית Composer המשמשת את ליבת מדיה־ויקי. אם עדיין נדרש ה־API הפנימי מסיבה כלשהי, אפשר לטעון את פרסואיד במפורש „כהרחבה” באמצעות הוספת הקוד הבא ל־LocalSettings.php:

wfLoadExtension( 'Parsoid', "$IP/vendor/wikimedia/parsoid/extension.json" );

בשימוש ב־API הפנימי של פרסואיד בהתקנות מחוץ לוויקימדיה, מומלץ מאוד לעבור לנקודת הקצה לדפי HTML ב־REST API של הליבה, המספקת יכולות מקבילות.

הפיתוח מתבצע ב־Parsoid Git repository. סקירת הקוד מתבצעת בגריט. להגדרת חשבון, ראו גריט/צעדים ראשונים.

בסביבת הפיתוח MediaWiki-Vagrant המבוססת על מכונה וירטואלית, אפשר פשוט להוסיף את התפקיד visualeditor, וכך תוגדר פרסואיד פעילה לצד Extension:VisualEditor .

ההוראות שלהלן מיועדות למדיה־ויקי 1.35 ומעלה. להפעלת הגרסה הישנה של פרסואיד, שנכתבה ב־JavaScript ושימשה במדיה־ויקי 1.34 ומטה, ראו Parsoid/JS .

בהתקנה רגילה של מדיה־ויקי, פרסואיד נכללת כספריית Composer בשם wikimedia/parsoid.

לצורכי פיתוח, בדרך כלל עדיף להשתמש בעותק עבודה של פרסואיד מ־Git, במקום בגרסה הכלולה בליבת מדיה־ויקי כספריית Composer. הוספת השורות הבאות ל־LocalSettings.php מאפשרת להשתמש בעותק עבודה של פרסואיד מ־Git (לפי הצורך), לטעון את ה־REST API של פרסואיד באמצעות wfLoadExtension (במקום להשתמש בגרסה הכלולה בעורך החזותי), ולהגדיר ידנית את פרסואיד כפי שהעורך החזותי עושה בדרך כלל:

$parsoidInstallDir = 'vendor/wikimedia/parsoid'; # העותק הכלול בחבילה
#$parsoidInstallDir = '/my/path/to/git/checkout/of/Parsoid';

// לצורכי פיתוח: יש לוודא שפרסואיד מופעלת מתוך $parsoidInstallDir,
// (ולא הגרסה הכלולה ב־mediawiki-core כברירת מחדל)
// חייב להתבצע *לפני* wfLoadExtension()
if ( $parsoidInstallDir !== 'vendor/wikimedia/parsoid' ) {
    function wfInterceptParsoidLoading( $className ) {
        // יש ליירט רק מחלקות במרחב השמות של Parsoid
        if ( preg_match( '/(MW|Wikimedia\\\\)Parsoid\\\\/', $className ) ) {
           $fileName = Autoloader::find( $className );
           if ( $fileName !== null ) {
               require $fileName;
           }
        }
    }
    spl_autoload_register( 'wfInterceptParsoidLoading', true, true );
    // AutoLoader::registerNamespaces נוסף במדיה־ויקי 1.39
    AutoLoader::registerNamespaces( [
        // יש לשמור על התאמה לסעיף "autoload" בקובץ
        // $parsoidInstallDir/composer.json
        'Wikimedia\\Parsoid\\' => "$parsoidInstallDir/src/",
    ] );
}

wfLoadExtension( 'Parsoid', "$parsoidInstallDir/extension.json" );
unset( $parsoidInstallDir );

לרוב, בשימוש בעורך החזותי אין צורך בשורות שב־LocalSettings.php, שכן אפשר להשתמש בהגדרה האוטומטית של העורך החזותי ובקוד פרסואיד הכלול במדיה־ויקי. עם זאת, השורות יידרשו ברוב המקרים לצורכי פיתוח של פרסואיד.

אם מדיה־ויקי מוגשת באמצעות Nginx, יש להוסיף גם הגדרה דומה לזו לבלוק השרת (בהנחה שקובצי התקנת מדיה־ויקי נמצאים ב־/w/):

location /w/rest.php/ {
    try_files $uri $uri/ /w/rest.php?$query_string;
}

אם מדיה־ויקי מופעלת באמצעות Docker והמאגר המקומי של פרסואיד מקושר אליה, יש למפות כרך אחסון נוסף למכולת Docker בקובץ docker-compose.override.yml שבמיזם מדיה־ויקי. הדרך הפשוטה ביותר לעשות זאת היא ליצור את הקובץ docker-compose.override.yml במיזם מדיה־ויקי ולהוסיף אליו את הקוד שלהלן (לאחר התאמת הנתיב). אם הקובץ docker-compose.override.yml כבר קיים, יש לשנותו בהתאם.

services:
  mediawiki:
    volumes:
      - ./:/var/www/html/w:cached
      - /my/path/to/git/checkout/of/Parsoid:/my/path/to/git/checkout/of/Parsoid

כדי לבדוק שההגדרות תקינות, יש לפתוח את {$wgScriptPath}/rest.php/{$domain}/v3/page/html/Main%20Page, כאשר $domain הוא שם המארח המוגדר ב־$wgCanonicalServer. (לתשומת לב: שרתי הייצור של קרן ויקימדיה אינם חושפים את ה־REST API של פרסואיד לרשת החיצונית.)

להרצת כל בדיקות מנתח התחביר ובדיקות Mocha:

$ composer test

לבדיקות מנתח התחביר יש כעת אפשרויות רבות. אפשר להציג את רשימתן באמצעות php bin/parserTests.php --help.

אם משתנה הסביבה MW_INSTALL_DIR מצביע על התקנה מוגדרת של מדיה־ויקי, אפשר להריץ בדיקות נוספות באמצעות:

$ composer phan-integrated

אפשר להמיר קטעי ויקיטקסט פשוטים משורת הפקודה באמצעות הסקריפט parse.php שבתיקייה bin/:

$ echo '[[Foo]]' | php bin/parse.php

לסקריפט הניתוח יש אפשרויות רבות. אפשר לקבל עליהן מידע באמצעות php bin/parse.php --help.

לעצות לניפוי שגיאות, ראו Parsoid/Debugging .

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

• מנגנון חיבור השירותים של פרסואיד (ServiceWiring)
• ה־REST API החיצוני של פרסואיד

כלי הרצת הבדיקות Quibble יפעיל אותם אם יזהה שהמאגר mediawiki/services/parsoid.git שוכפל כחלק מתהליך הבנייה. במקרה כזה הוא:

• מפנה את הטוען האוטומטי של Wikimedia\Parsoid לקוד ששוכפל (ובפועל מחליף את הגרסה שהותקנה באמצעות Composer)
• טוען את ההרחבה wfLoadExtension( 'Parsoid', '/path/to/cloned/repo' );

מנגנון ServiceWiring אמור להיות מופעל במדיה־ויקי החל מגרסה 1.38.

תאורטית, ה־REST API לא אמור להתמזג לעולם במדיה־ויקי: א) הוא מעולם לא נחשף לציבור בסביבת הייצור, והוא API פנימי המשמש את RESTBase, שעתיד לצאת משימוש; ב) הוא מעולם לא עבר ביקורת אבטחה; ג) היכולות שלו חופפות לאלה של ה־API הארגוני של מדיה־ויקי. הפתרון יהיה שהעורך החזותי יפעיל את פרסואיד ישירות דרך ה־Action API של העורך החזותי, וכך ייחסך סבב בקשה ותשובה דרך ה־REST API.

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

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

טעינת פרסואיד כהרחבה מאפשרת להריץ משימות של בדיקות שילוב במדיה־ויקי מול mediawiki/services/parsoid.git (כגון Quibble ו־apitesting), ולוודא שפרסואיד ומדיה־ויקי פועלות יחד.

ייתכן שאפשר לכתוב בהרחבה בדיקות המשתמשות בפרסואיד גם כאשר המאגר לא שוכפל. מכיוון שפרסואיד היא תלות Composer של ליבת מדיה־ויקי, מרחב השמות MediaWiki\Parsoid זמין, אך רכיב חיבור השירותים אינו זמין (הוא נמצא ב־extension/src במאגר פרסואיד ונחשף כמרחב השמות \MWParsoid). הקוד ParsoidTestFileSuite.php יריץ את בדיקות מנתח התחביר רק אם פרסואיד נטענה (מצב שאמור להיות ברירת המחדל במדיה־ויקי 1.38).

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

בבניות מדיה־ויקי להפצה, מנגנון ServiceWiring של פרסואיד משולב בעורך החזותי, כדי שהעורך החזותי יפעל ללא הגדרות נוספות (מלבד wfLoadExtension( 'VisualEditor' )). הבנייה להפצה מפעילה גם את ה־REST API ומחברת את כל הרכיבים, כדי שפרסואיד תפעל מיד לאחר ההתקנה. לשם כך מועתק לעורך החזותי קטע מהקוד של פרסואיד. קוד זה אינו נמצא בענף master של העורך החזותי, משום שהוא יתיישן ברגע שפרסואיד תתעדכן. במקום זאת, הקוד מתוחזק בשני מקומות.

• Parsoid/Internals – תיעוד של המבנה הפנימי של פרסואיד, עם קישורים לפרטים נוספים.
• הערות על ההסבה ל־PHP ומשימות שדרושה בהן עזרה
• לוח הזמנים לפריסת פרסואיד באשכול השרתים של ויקימדיה (הקוד נפרס בדרך כלל בכל יום שני ורביעי, בין 13:00 ל־13:30 לפי שעון החוף המערבי של ארצות הברית, PST)
• Parsoid/Round-trip testing – מערך בדיקות ההמרה הלוך ושוב המשמש אותנו לבדיקת הרצף ויקיטקסט ← DOM של HTML ← ויקיטקסט על תוכן ממשי מוויקיפדיה.
• Parsoid/Visual Diffs Testing – מידע על בדיקות השוואה חזותית בין תצוגת ה־HTML שמפיקה פרסואיד לזו שמפיק מנתח התחביר ב־PHP, וכן מערך testreduce להרצת בדיקות השוואה חזותית בהיקף נרחב.
• Parsoid/limitations – מגבלות בפרסואיד, בעיקר שימושים מלאכותיים או שימושים לרעה בתבניות, שאין להם חשיבות מעשית. אפשר להרחיב זאת בדומה להערות על שדרוג המעבד המקדים (ייתכן שנדרש עדכון)
• Parsoid/Bibliography – ביבליוגרפיה של ספרות בנושא

• לעצות לניפוי שגיאות, ראו Parsoid/Debugging .
• שדרוג או הוספה של חבילות לפרסואיד
• ראו הוראות אלו לסנכרון העותק של בדיקות מנתח התחביר שבפרסואיד עם הליבה, בשני הכיוונים
• לפרסואיד יש ממשק ספרייה מוגבל להפעלתה מתוך קוד.
• הרצאה טכנית על התאמת הרחבות לעבודה עם פרסואיד
• התאמת הרחבה לעבודה עם פרסואיד
• ניהול גרסאות של מפרט ה־HTML של פרסואיד
• לקראת שינוי בפלט של פרסואיד

• Parsoid/Deployments
• שינויי קוד של בדיקות המרה הלוך ושוב (שימושיים לבדיקת נסיגות ותיקונים)
• הוראות לפריסת פרסואיד
• לוח מחוונים של Kibana
• לוח מחוונים של Grafana למדדי wt2html
• לוח מחוונים של Grafana למדדי html2wt
• פירוט נתוני Prometheus לאשכול פרסואיד ב־eqiad
• פירוט נתוני Prometheus לאשכול פרסואיד ב־codfw
• תיעוד Jenkins Job Builder לעדכון משימות Jenkins

היישום המקורי נכתב ב־JavaScript (באמצעות Node.js) והחל לפעול באשכול השרתים של ויקימדיה בדצמבר 2012. בשנת 2019 הוסבה פרסואיד ל־PHP, וגרסת ה־PHP החליפה את גרסת ה־JavaScript באשכול השרתים של ויקימדיה בדצמבר 2019. פרסואיד משולבת בהדרגה בליבת מדיה־ויקי, במטרה להחליף בסופו של דבר את מנתח התחביר המובנה הנוכחי של מדיה־ויקי. בתחילת 2024 החל השימוש בפרסואיד כמנתח התחביר המוגדר כברירת מחדל לתצוגות קריאה בחלק מאתרי הוויקי הפעילים של קרן ויקימדיה. אפשר למצוא אותם ברשימת ההגדרות של סביבת הייצור.

פרסואיד (גרסת ה־PHP) כלולה כחלק מובנה במדיה־ויקי החל מגרסה 1.35, שיצאה בספטמבר 2020. בהתקנות מחוץ לוויקימדיה, התמיכה בפרסואיד/JS נמשכה עד תום תקופת התמיכה במדיה־ויקי 1.31 (גרסת תמיכה ארוכת טווח, LTS), בספטמבר 2021.

• איך אפשר לדעת אם דף עובד באמצעות פרסואיד?
  • בתחתית הדף תופיע ההודעה „Page was rendered with Parsoid” (הדף עובד באמצעות פרסואיד).
• איך אפשר להגדיר שדף יעובד זמנית באמצעות פרסואיד?
  • יש להתקין את הרחבה:ParserMigration
  • יש להוסיף את ?useparsoid=1 לכתובת ה־URL
• איך אפשר להגדיר שאתר ויקי שלם יעובד באמצעות פרסואיד?
  • יש להתקין את הרחבה:ParserMigration
  • יש להגדיר $wgParserMigrationEnableParsoidArticlePages = true;
  • יש להגדיר $wgParserMigrationEnableParsoidDiscussionTools = true;
• באילו אתרי ויקי של ויקימדיה נעשה שימוש בפרסואיד לעיבוד דפים?
  • הרשימה נמצאת ב־parsoidrendered.dblist. נכון לאוקטובר 2025, מדובר בכ־650 מתוך 1,000 אתרי הוויקי. הפריסה תימשך עד שבכל אתרי הוויקי ייעשה שימוש בפרסואיד.

• ממשק תכנות יישומים (API)
• RESTBase – מתווך API לשמירה ולאחסון במטמון של דפי HTML המופקים באמצעות פרסואיד
• Parser 2011/Parser plan – רעיונות וסוגיות תכנון מוקדמים משנת 2011 (כיום ישנים יחסית)
• Special:PrefixIndex/Parsoid/ – דפים הקשורים לפרסואיד באתר ויקי זה
• Extension:ParsoidBatchAPI (בארכיון)
• parsoid-jsapi – ממשק ברמה גבוהה לחילוץ ויקיטקסט ולהמרתו, בדומה ל־API של mwparserfromhell.
• Alternative parsers
• פרסואיד/איחוד ניתוח מחרוזות

• קוד המקור (עותק מראה ב־GitHub)
• תיעוד JavaScript (הגרסה הישנה של פרסואיד)
• תיעוד PHP
• פרסואיד בוויקישיתוף

לקבלת עזרה, לשאלות או למשוב, אפשר ליצור איתנו קשר ב־#mediawiki-parsoid ^connect או ברשימת התפוצה wikitext-l. אם הדרכים האלה אינן מועילות, אפשר לפנות אלינו גם בדוא״ל לכתובת content-transform-team תחת שם המתחם wikimedia.org.

התחזוקה של Parsoid נעשית בידי Content Transform Team. קבלת עזרה: #mediawiki-parsoid connect ← צ׳אט בזמן אמת (IRC) wikitext-l ← רשימת התפוצה Talk:Parsoid ← דף השיחה parsoid (הוספת מטלה) ← דף המיזם ב־Phabricator