streamalism.org

1. הקדמה

במאמר זה נערוך הקדמה מהירה על אופן השימוש ב- Asciidoctor עם Java. נדגים כיצד ליצור HTML5 או PDF ממסמך AsciiDoc.

2. מה זה AsciiDoc?

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

מכיוון שהוא ניתן להגדרה רבה, ניתן להמיר מסמכי AsciiDoc לפורמטים רבים אחרים כמו HTML, PDF, דפי אדם, EPUB ואחרים.

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

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

3. מהו Asciidoctor?

Asciidoctor הוא א מעבד טקסט להמרת מסמכי AsciiDoc לתוך HTML, PDF ופורמטים אחרים. זה כתוב ברובי וארוז כ- RubyGem.

כפי שצוין לעיל, AsciiDoc הוא פורמט פופולרי מאוד לכתיבת תיעוד, כך שתוכל למצוא בקלות את Asciidoctor כחבילה סטנדרטית בהפצת GNU לינוקס רבים כמו אובונטו, דביאן, פדורה ו- Arch.

מכיוון שאנחנו רוצים להשתמש ב- Asciidoctor ב- JVM, נדבר על AsciidoctorJ - שהוא Asciidoctor עם Java.

4. תלות

כדי לכלול את חבילת AsciidoctorJ ביישום שלנו, להלן pom.xml יש צורך בכניסה:

 org.asciidoctor asciidoctorj 1.5.5 org.asciidoctor asciidoctorj-pdf 1.5.0-alpha.15 

הגרסאות האחרונות של הספריות ניתן למצוא כאן וכאן.

5. AsciidoctorJ API

נקודת הכניסה של AsciidoctorJ היא אשציודקטור ממשק Java.

שיטות אלה הן:

• להמיר - מנתח את מסמך AsciiDoc מ- חוּט אוֹ זרם וממיר אותו לסוג הפורמט המסופק
• convertFile - מנתח את מסמך AsciiDoc ממסופק קוֹבֶץ אובייקט וממיר אותו לסוג הפורמט המסופק
• המרת קבצים - זהה לקודם, אך השיטה מקבלת מספר רב קוֹבֶץ חפצים
• convertDirectory - מנתח את כל מסמכי AsciiDoc בתיקיה המסופקת וממיר אותם לסוג הפורמט המסופק

5.1. שימוש ב- API בקוד

כדי ליצור אשציודקטור למשל, עליך לאחזר את המופע משיטת המפעל המסופקת:

יבוא org.asciidoctor.Asciidoctor.Factory.create סטטי; יבוא org.asciidoctor.Asciidoctor; .. // איזה קוד .. Asciidoctor asciidoctor = create (); 

עם מופע מאוחזר, אנו יכולים להמיר מסמך AsciiDoc בקלות רבה:

פלט מחרוזת = asciidoctor .convert ("שלום _ Baeldung_!", HashMap חדש ());

אם אנו רוצים להמיר מסמך טקסט ממערכת הקבצים, נשתמש ב- convertFile שיטה:

פלט מחרוזת = asciidoctor .convertFile (קובץ חדש ("baeldung.adoc"), HashMap חדש ()); 

להמרת קבצים מרובים, ה- המרת קבצים השיטה מקבלת רשימה אובייקט כפרמטר ראשון ומחזיר מערכים של חוּט חפצים.

מעניין יותר הוא כיצד להמיר ספרייה שלמה עם AsciidoctorJ.

כאמור לעיל, כדי להמיר ספריה שלמה - עלינו להתקשר ל- convertDirectory שיטה. זה סורק את הנתיב שסופק ומחפש את כל הקבצים עם סיומות AsciiDoc (.adoc, .ad, .asciidoc, .asc) וממיר אותם. כדי לסרוק את כל הקבצים, מופע של DirectoryWalker צריך לספק לשיטה.

נכון לעכשיו, Asciidoctor מספק שתי יישומים מובנים של הממשק שהוזכר:

• AsciiDocDirectoryWalker - ממיר את כל הקבצים של התיקיה הנתונה ותיקיות המשנה שלה. מתעלם מכל הקבצים שמתחילים ב- "_"
• GlobDirectoryWalker להמיר את כל הקבצים של התיקיה הנתונה בעקבות ביטוי גלוב

מחרוזת [] תוצאה = asciidoctor.convertDirectory (AsciiDocDirectoryWalker חדש ("src / asciidoc"), HashMap חדש ()); 

גַם, אנו יכולים לקרוא לשיטת המרה בתנאי java.io. קורא ו java.io.Writer ממשקים.קוֹרֵא ממשק משמש כמקור, ו- סוֹפֵר הממשק משמש לכתיבת נתונים שהומרו:

FileReader reader = FileReader חדש (קובץ חדש ("sample.adoc")); סופר StringWriter = חדש StringWriter (); asciidoctor.convert (קורא, כותב, אפשרויות (). asMap ()); StringBuffer htmlBuffer = writer.getBuffer ();

5.2. דור PDF

כדי ליצור קובץ PDF ממסמך Asciidoc, עלינו לציין את סוג הקובץ שנוצר באפשרויות. אם תבדוק קצת יותר בזהירות את הדוגמאות הקודמות, תבחין שהפרמטר השני של כל שיטת המרה הוא a מַפָּה - המייצג אובייקט אפשרויות.

נגדיר את האפשרות in_place כ- true כך שהקובץ שלנו נוצר ונשמר אוטומטית במערכת הקבצים:

אפשרויות מפה = אפשרויות () .inPlace (נכון) .backend ("pdf") .asMap (); קובץ outfile = asciidoctor.convertFile (קובץ חדש ("baeldung.adoc"), אפשרויות);

6. תוסף Maven

בחלק הקודם הראינו כיצד אנו יכולים ליצור קובץ PDF ישירות באמצעות היישום שלך ב- Java. בחלק זה נראה כיצד ליצור קובץ PDF במהלך בניית Maven. תוספי Simiar קיימים עבור Gradle ו- Ant.

כדי לאפשר יצירת PDF במהלך הבנייה, עליך להוסיף תלות זו ל- pom.xml:

 org.asciidoctor asciidoctor-maven-plugin 1.5.5 org.asciidoctor asciidoctorj-pdf 1.5.0-alpha.15 

הגרסה האחרונה של תלות התוסף של Maven נמצאת כאן.

6.1. נוֹהָג

כדי להשתמש בתוסף ב- build, עליך להגדיר אותו ב- pom.xml:

   פלט-html ליצור-משאבים תהליך-asciidoc 

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

כמו בתוסף Asciidoctorj, אנו יכולים להשתמש גם באפשרויות שונות לייצור PDF.

בואו נסתכל במהירות על האפשרויות הבסיסיות בזמן שתוכלו למצוא אפשרויות אחרות בתיעוד:

• sourceDirectory - המיקום של הספרייה שבה יש לך מסמכי Asciidoc
• ספריית פלט - מיקום הספרייה בה ברצונך לאחסן קבצי PDF שנוצרו
• backend - סוג הפלט של Asciidoctor. עבור הדור PDF להגדיר עבור pdf

זו דוגמה להגדרת אפשרויות בסיסיות בתוסף:

  src / main / doc target / docs pdf 

לאחר הפעלת ה- build, ניתן למצוא את קבצי ה- PDF בספריית הפלט שצוינה.

7. מסקנה

למרות ש- AsciiDoc מאוד קל לשימוש ולהבנה, זה כלי חזק מאוד לניהול תיעוד ומסמכים אחרים.

במאמר זה הדגמנו דרך פשוטה ליצור קבצי HTML ו- PDF ממסמך AsciiDoc.

את הקוד ניתן למצוא ב- GitHub.