สร้างเครือข่ายสิ่งพิมพ์ด้วย Pandoc และ Docker

เผยแพร่แล้ว: 2022-03-11

วันนี้ เราจะมาเจาะลึกถึงวิธีที่ผู้เชี่ยวชาญสามารถขอความช่วยเหลือจาก Pandoc เพื่อสร้างห่วงโซ่สิ่งพิมพ์ที่แข็งแกร่งและใช้งานง่าย Pandoc เป็นเครื่องมือที่เรียบง่ายแต่ทรงพลังที่ช่วยให้ผู้ใช้สามารถแปลงเอกสารเป็นรูปแบบต่างๆ ได้ตามความต้องการ

สามารถลดความซับซ้อนของเอกสารและสิ่งพิมพ์ได้อย่างมาก หรือแม้กระทั่งเปิดโอกาสการทำงานอัตโนมัติใหม่ๆ สองสามอย่าง เหนือสิ่งอื่นใด Pandoc อาศัย Markdown ที่เป็นมิตรกับ Git ซึ่งหมายความว่าคุณสามารถใช้ระบบควบคุมเวอร์ชันสำหรับเอกสารของคุณได้โดยไม่ต้องยุ่งยากเพิ่มเติม

เมื่อพูดถึงความยุ่งยาก เราจะใช้อิมเมจ Docker เพื่อติดตั้ง Pandoc และ LaTeX ด้วยวิธีง่ายๆ การติดตั้งซอฟต์แวร์อาจใช้เวลานาน และการตั้งค่าสภาพแวดล้อมซอฟต์แวร์ที่ใช้งานได้ตั้งแต่เริ่มต้นเมื่อเริ่มโครงการใหม่แทบจะไม่มีประสิทธิผล นักเทียบท่าช่วยบรรเทาปัญหาเหล่านี้โดยอนุญาตให้ผู้ใช้ตั้งค่าทุกอย่างในไม่กี่นาที โดยไม่คำนึงถึงแพลตฟอร์ม

นอกจากนี้ ไม่ใช่เรื่องแปลกที่นายจ้างกำหนดให้คุณต้องจัดหาฮาร์ดแวร์คอมพิวเตอร์ของคุณเอง ซึ่งมักเรียกกันว่า "นำอุปกรณ์มาเอง" (BYOD) และอย่าลืมว่าการระบาดใหญ่ของโควิด-19 ทำให้การทำงานจากที่บ้านเป็นที่แพร่หลายมากขึ้น หากไม่มีโซลูชันอย่าง Docker ก็คงเป็นเรื่องยากที่จะรองรับแอปพลิเคชันที่ทำงานบนฮาร์ดแวร์และระบบปฏิบัติการที่หลากหลาย เช่น Windows, macOS และ Linux

เริ่มต้นด้วยการดูคอนเทนเนอร์และรูปภาพของ Docker ให้ละเอียดก่อนไปยัง Pandoc

นักเทียบท่าเพื่อช่วยเหลือ

การใช้คอนเทนเนอร์ Docker สามารถขจัดความจำเป็นในการติดตั้งแอพพลิเคชั่นซอฟต์แวร์หลายตัวในเครื่องใหม่ อิมเมจ Docker ที่สร้างไว้ล่วงหน้ามีอยู่ใน Docker Hub สำหรับแอปพลิเคชันจำนวนมาก ผู้ให้บริการระบบคลาวด์ชั้นนำ เช่น AWS, Azure และ Google ล้วนให้บริการรีจิสตรีคอนเทนเนอร์ มีการลงทะเบียนบุคคลที่สามอื่น ๆ อีกมากมายรวมถึง GitLab และ Red Hat OpenShift

มีแนวโน้มว่ารูปภาพจะพร้อมใช้งานสำหรับแอปพลิเคชันส่วนใหญ่ (ถ้าไม่ใช่ทั้งหมด) ซึ่งหมายความว่าไม่จำเป็นต้องติดตั้งแอปพลิเคชันส่วนใหญ่และการพึ่งพา แอปพลิเคชันสามารถเรียกใช้ได้ในคอนเทนเนอร์ Docker วิธีนี้ช่วยขจัดปัญหาที่เกี่ยวข้องกับสมาชิกในทีมที่เรียกใช้แอปพลิเคชันบนฮาร์ดแวร์และระบบปฏิบัติการที่แตกต่างกัน อิมเมจเดียวกันนี้สามารถใช้เพื่อรันคอนเทนเนอร์บนระบบใดๆ ที่รันได้ และผู้เชี่ยวชาญ Docker สามารถทำให้กระบวนการนี้รวดเร็วและมีประสิทธิภาพอย่างยิ่ง

Pandoc Use Case: เอกสารประกอบ

อาจต้องใช้เอกสารในรูปแบบต่างๆ เอกสารเดียวกันอาจต้องมีอยู่ในรูปแบบต่างๆ เช่น HTML สำหรับการนำเสนอ และ PDF สำหรับเอกสารประกอบคำบรรยาย การแปลงระหว่างรูปแบบไฟล์อาจเป็นเรื่องที่น่าเบื่อหน่ายและต้องใช้เวลามาก ทางออกที่ดีคือการมีห่วงโซ่สิ่งพิมพ์ที่มีแหล่งความจริงเพียงแหล่งเดียว เอกสารทั้งหมดควรเขียนในภาษาเดียวกัน ควรเป็นภาษาแบบข้อความเนื่องจากง่ายต่อการกำหนดเวอร์ชันและจัดเก็บในที่เก็บ Git

Markdown เป็นตัวเลือกที่ดีในการสร้างแหล่งความจริงเพียงแหล่งเดียว ซอฟต์แวร์ที่สามารถแปลงเอกสาร Markdown เป็นรูปแบบอื่นๆ ได้หลากหลายพร้อมใช้งานและมีแนวโน้มที่จะเชื่อถือได้

Markdown สามารถแปลงเป็นรูปแบบต่าง ๆ ได้อย่างง่ายดายสำหรับการใช้งานที่หลากหลาย
Markdown สามารถแปลงเป็นรูปแบบต่าง ๆ ได้อย่างง่ายดายสำหรับการใช้งานที่หลากหลาย

Pandoc

Pandoc เป็นแพ็คเกจซอฟต์แวร์ที่สามารถแปลงเอกสารเป็นรูปแบบต่างๆ โดยเฉพาะอย่างยิ่ง มันสามารถแปลง Markdown เป็น HTML, PDF และรูปแบบอื่นๆ ที่ใช้กันอย่างแพร่หลาย กระบวนการแปลงสามารถปรับแต่งได้โดยใช้เทมเพลตและข้อมูลเมตาในแหล่ง Markdown

Pandoc ต้องการการติดตั้ง LaTeX เพื่อสร้างไฟล์ PDF การติดตั้ง Pandoc และ LaTeX นั้นค่อนข้างใช้เวลานาน โชคดีที่มีอิมเมจ Docker ชื่อ pandoc/latex ซึ่งไม่จำเป็นต้องติดตั้งอย่างอื่นนอกจาก Docker

คำสั่งนักเทียบท่า

ต้องค้นหาหรือสร้างอิมเมจ Docker ที่เหมาะสมซึ่งมีซอฟต์แวร์ที่จำเป็น ขอแนะนำให้ดึงรูปภาพไปที่รีจิสตรีในเครื่องเนื่องจากการดาวน์โหลดอาจใช้เวลาสักครู่

 docker pull pandoc/latex

ในการรันคำสั่งในคอนเทนเนอร์ Docker ต้องใช้ wrapper เพื่อรันคอนเทนเนอร์ Docker และรันคำสั่งในคอนเทนเนอร์ วิธีแก้ปัญหาที่ดีคือการเขียนฟังก์ชันเชลล์บนระบบ macOS หรือ UNIX/Linux ฟังก์ชันนี้สามารถใส่ในสคริปต์การเข้าสู่ระบบใดๆ หรือในไฟล์แยกต่างหาก เช่น $HOME/.functions นอกจากนี้ยังสามารถเขียนสคริปต์หรือนามแฝงด้วยฟังก์ชันเดียวกันได้

 function pandoc { echo pandoc $@ docker run -it --rm -v $PWD:/work -w /work pandoc/latex pandoc "$@" }

ฟังก์ชันนี้ทำสิ่งต่อไปนี้:

  • มันพิมพ์คำสั่งไปที่หน้าจอ
  • มันรันคอนเทนเนอร์ Docker จาก pandoc/latex
  • อ็อพชัน -it สร้างเซสชันเทอร์มินัลแบบโต้ตอบและทำให้เอาต์พุตของคำสั่งมองเห็นได้
  • ตัวเลือก --rm จะลบคอนเทนเนอร์เมื่อคำสั่งสิ้นสุดลง
  • อ็อพชัน -v $PWD:/work จะเมาต์ไดเร็กทอรีปัจจุบันบนโฮสต์ไปยังไดเร็กทอรี /work ในคอนเทนเนอร์
  • -w /work ทำให้ไดเร็กทอรี /work ในคอนเทนเนอร์เป็นไดเร็กทอรีการทำงาน
  • pandoc "$@" รันคำสั่ง pandoc ในคอนเทนเนอร์ผ่านตัวเลือกบรรทัดคำสั่งทั้งหมดที่ส่งผ่านไปยังฟังก์ชัน

เชลล์หรือสคริปต์จำเป็นต้องโหลดฟังก์ชันลงในหน่วยความจำ

 . $HOME/.functions

ตอนนี้ฟังก์ชันนี้เป็นคำสั่งในสิทธิ์ของตนเองและทำงานในลักษณะเดียวกับที่ติดตั้งไบนารี pandoc ในเครื่อง วิธีนี้ใช้ได้กับคำสั่งใดๆ ที่มีอยู่ในอิมเมจ Docker

มาร์กดาวน์เป็น HTML

หากต้องการแปลง Markdown เป็น HTML ควรใช้เทมเพลตและข้อมูลเมตาใน Markdown

มาร์กดาวน์เป็น HTML

ข้อมูลเมตาของ Markdown

แหล่งที่มาของ Markdown สามารถมีส่วนส่วนหัวที่สามารถมีข้อมูลเมตาที่กำหนดเองได้ ข้อมูลเมตาจะอยู่ในรูปแบบของคู่คีย์-ค่า ค่าต่างๆ สามารถแทนที่ได้ในเทมเพลต HTML

 --- title: Document title links: prev: index next: page002 ...

ส่วนหัวเริ่มต้นด้วยบรรทัดที่มีเพียงสามขีดกลาง --- จบลงด้วยบรรทัดที่มีเพียงสามจุด ... . คีย์คือคำเดียวตามด้วยเครื่องหมายทวิภาคและค่าของมัน คีย์สามารถซ้อนกันได้ ตัวอย่างแสดงคำจำกัดความของคีย์ที่เรียกว่า title, links.prev และ links.next

วิธีนี้ใช้ไฟล์แยกกันสำหรับแต่ละหน้า ในตัวอย่าง หน้าก่อนหน้านี้คือ index.md หน้าปัจจุบันคือ page001.md และหน้าถัดไปคือ page002.md ในทางปฏิบัติ ชื่อไฟล์ที่มีความหมายมากขึ้นจะถูกใช้เพื่อให้ง่ายต่อการจัดลำดับใหม่และแทรกหน้า

เทมเพลต HTML

เทมเพลต HTML เป็นเพียงไฟล์ HTML สามารถเพิ่มการแทนที่ข้อมูลเมตาและโครงสร้างการควบคุมอย่างง่ายระหว่างสัญลักษณ์ดอลลาร์ นี่คือตัวอย่างง่ายๆ ของเทมเพลต HTML สำหรับ Pandoc:

 <html> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>$title$</title> <link href="../css/style.css" type="text/css" rel="stylesheet" /> </head> <header> <h1>$title$</h1> </header> <body> $body$ </body> <footer> $if(links.prev)$ <a href="$links.prev$.html" class="previous">&laquo; Previous</a> $endif$ $if(links.next)$ <a href="$links.next$.html" class="next">Next &raquo;</a> $endif$ </footer> </html>

ตัวอย่างแสดงเทมเพลต $body$ จะถูกแทนที่ด้วยข้อความ Markdown ที่แปลงเป็น HTML คำสั่งแบบมีเงื่อนไขจะสร้างลิงก์ HTML หากกำหนดเมตาดาต้าในส่วนหัวของ Markdown เท่านั้น

การสร้าง HTML จาก Markdown

Pandoc จำเป็นต้องได้รับแจ้งว่าไฟล์อินพุตและเอาต์พุตเรียกว่าอะไร บวกกับไฟล์เทมเพลตใดๆ รูปแบบไฟล์อินพุตเริ่มต้นคือ Markdown มันสามารถสรุปรูปแบบไฟล์เอาท์พุตจากนามสกุลไฟล์เอาท์พุตที่ระบุ

คำสั่งในการสร้างเอาต์พุตอาจเป็นสคริปต์หรือ makefile

 dir=Project for input_file in ${dir}/*.md do output_file=HTML/${input_file%.md}.html if [[ ${input_file} -nt ${output_file} ]] then pandoc --data-dir . --template presentations.html -t html \ -o ${output_file} ${input_file} fi done

สำหรับไฟล์ . .md ทุกไฟล์ในไดเร็กทอรี Project ไฟล์จะสร้างไฟล์ .html ที่สอดคล้องกันในไดเร็กทอรี HTML/Project หากไฟล์เอาต์พุตเก่ากว่าไฟล์อินพุตหรือไม่มีอยู่

กำลังสร้าง Beamer PDF จาก Markdown

Beamer เป็นแพ็คเกจ LaTeX สำหรับสร้างงานนำเสนอ ผลลัพธ์เป็นสไลด์โชว์ PDF

กำลังสร้าง Beamer PDF จาก Markdown

ไฟล์ต้นฉบับ Markdown เดียวกันสามารถใช้เพื่อสร้าง PDF Beamer

 pandoc -t beamer -o PDF/Project.pdf -V theme:Boadilla -V colortheme:whale Project/index.md Project/page000.md

รายละเอียดคำสั่งคือ:

  • ตัวเลือก -t beamer ระบุว่าใช้ LaTeX และ beamer เพื่อสร้าง PDF
  • อ็อพชัน -o ระบุไฟล์เอาต์พุต
  • ตัวเลือก -V จะเลือกธีมบีมเมอร์และธีมสี
  • คำสั่งลงท้ายด้วยรายการไฟล์ Markdown ที่จะต่อกันตามลำดับที่กำหนด

การประมวลผลทั้งหมดดำเนินการภายในคอนเทนเนอร์ Docker

Markdown เป็น PDF

การแปลงเอกสาร Markdown เป็นเอกสาร PDF นั้นค่อนข้างง่ายเช่นกัน PDF ถูกสร้างขึ้นเสมอโดยการแปลง Markdown เป็น LaTeX ก่อน สามารถเพิ่มข้อมูลเมตาในส่วนหัว Markdown เพื่อปรับแต่งผลลัพธ์ เช่น การตั้งค่าขนาดกระดาษและขนาดขอบ

 --- title: Title of document papersize: a4 geometry: - margin=20mm ...

กำลังสร้าง PDF จาก Markdown

คำสั่งในการแปลง Markdown เป็น PDF นั้นง่ายมาก:

 pandoc -s Project/outline.md -o PDF/ProjectOutline.pdf

อ็อพชัน -s สร้างเอกสารแบบสแตนด์อโลน

บทสรุป

ไม่จำเป็นต้องใช้เวลาหลายวันในการติดตั้งซอฟต์แวร์อีกต่อไป เพียงแค่รันคำสั่งในคอนเทนเนอร์ Docker ก็ไม่จำเป็นต้องติดตั้ง แอปพลิเคชั่นจำนวนมากมีอิมเมจ Docker ที่เหมาะสมบน Docker Hub หากจำเป็นต้องอัปเดตซอฟต์แวร์ ให้ดึงอิมเมจ Docker ล่าสุด

การตั้งค่าคอมพิวเตอร์เครื่องใหม่เป็นเพียงเรื่องของการติดตั้ง Docker การดึงอิมเมจที่จำเป็น และสร้างสคริปต์สองสามตัว

ไม่จำเป็นต้องสร้างเอกสารในรูปแบบต่างๆ อีกต่อไป รูปแบบเดียว เช่น Markdown สามารถใช้ได้กับเอกสารทั้งหมด เครื่องมือเช่น Pandoc สามารถสร้างเอกสารจาก Markdown ในรูปแบบต่างๆ ได้มากมาย

เนื่องจาก Markdown เป็นไฟล์ข้อความ เมื่อตรวจสอบในที่เก็บ Git ประวัติเวอร์ชันเต็มจะพร้อมใช้งาน ที่เก็บ Git ยังแสดงผล Markdown โดยอัตโนมัติและอนุญาตให้ผู้คนแสดงความคิดเห็นเกี่ยวกับการเปลี่ยนแปลงโดยไม่ต้องใช้ประวัติการเปลี่ยนแปลงที่ยุ่งเหยิงในไฟล์เอกสาร