R for Thais

ในการทำแฟ้มความช่วยเหลือนั้น ดังที่ได้กล่าวไว้ในเรื่องการ build package แล้วว่าจะต้องเขียนในรูปแบบ R document (Rd) การที่จะทำแฟ้มความช่วยเหลือเป็นภาษาไทยก็เช่นเดียวกัน ต้องเริ่มต้นด้วยการสร้างแฟ้มความช่วยเหลือในรูปแบบ Rd นั่นเอง ซึ่งมี tag คำสั่งต่างๆ ดังได้อธิบายไว้ในเรื่อง “การเขียนแฟ้มความช่วยเหลือในรูปแบบ R document” แล้ว

ในการเขียนแฟ้มความช่วยเหลือในรูปแบบ Rd ให้เป็นภาษาไทยนั้นก็เขียนเช่นเดียวกับที่กล่าวไว้แล้วในบทที่กล่าวถึงข้างต้น โดยยังคง tag คำสั่งไว้เช่นเดียวกับที่ได้อธิบายไว้นั้น เพียงแต่เขียนข้อความภายใน tag คำสั่ง บางอันเป็นภาษาไทยเท่านั้น ขอทบทวน tag คำสั่งที่สำคัญดังนี้

\name{name}
\alias{topic}
\title{Title}
\description{…}
\usage{fun(arg1, arg2, …)}
\arguments{…}
\details{…}
\value{…}
\references{…}
\note{…}
\author{…}
\seealso{…}
\examples{…}
\keyword{key}

tag คำสั่ง \name และ \alias นั้นให้เขียนเป็นภาษาอังกฤษเสมอ เนื่องจากจะเป็นส่วนของชื่อคำสั่งนั้นๆ ที่ R ใช้อ้างอิงและค้นหาคำสั่งในระบบ tag คำสั่ง \title และ \description สามารถเขียนเป็นภาษาไทยได้ ในส่วนของ \usage นั้นจะต้องเขียนเป็นภาษาอังกฤษ เพราะเป็นส่วนที่แสดงวิธีการเรียกใช้ฟังก์ชัน ในส่วนของ \arguments นั้น ในส่วนของชื่อ argument จะต้องเป็นภาษาอังกฤษตามที่ระบุไว้ใน \usage นั่นเอง แต่ในส่วนของคำอธิบายสามารถเขียนเป็นภาษาไทยได้

ส่วน tag คำสั่ง \details, \value, \references, \note, และ \author สามารถเขียนเป็นภาษาไทยได้ตามความเหมาะสม ส่วน tag คำสั่ง \seealso, \examples, และ \keyword จะต้องเขียนเป็นภาษาอังกฤษ ยกเว้นในส่วนของ comment ใน \examples อาจเขียนเป็นภาษาไทยได้

ส่วนที่สำคัญที่จะกล่าวโดยละเอียดในบทนี้คือขั้นตอนการ build ให้ได้แฟ้มความช่วยเหลือภาษาไทยในรูปแบบ html และ chtml ได้แสดงเป็นภาษาไทยได้อย่างถูกต้อง ซึ่งหากทำไม่ถูกขั้นตอนแล้วอาจทำให้การแสดงภาษาไทยไม่ถูกต้องได้

ดังได้กล่าวในบท “การสร้าง package ใน R” แล้วนั้น โฟลเดอร์ที่บรรจุแฟ้มความช่วยเหลือในรูปแบบ Rd คือโฟลเดอร์ man นั่นเอง หากจะมีบางกรณีที่ต้องการเรียกความช่วยเหลือในรูปแบบ text ด้วย ให้เขียนแฟ้มความช่วยเหลือเป็นสองโฟลเดอร์ โดยโฟลเดอร์หนึ่งเขียนเป็นภาษาอังกฤษ และอีกโฟลเดอร์หนึ่งเขียนเป็นภาษาไทย ตามคำแนะนำข้างต้น อย่างไรก็ตามเพื่อความสะดวกอาจเขียนเป็นภาษาไทยอย่างเดียวก็ได้ แล้วกำหนดค่าปกติของการเรียกความช่วยเหลือให้เรียกรูปแบบ html หรือ chtml (เฉพาะบน Windows) ซึ่งบนระบบปฏิบัติการ Macintosh นั้นจะไม่มีปัญหาแต่อย่างใด เนื่องจาก R บน Macintosh จะเรียกความช่วยเหลือในรูปแบบ html เสมออยู่แล้ว ส่วนบน Linux นั้นอาจเรียกคำสั่ง help ด้วย option html=TRUE เสมอ และบน Windows นั้น สามารถแก้ไขแฟ้ม Rprofile ในโฟลเดอร์ ../R/rw20xx/etc โดยเอาเครื่องหมาย # หน้าบรรทัด options(chmhelp=TRUE) หรือ options(htmlhelp=TRUE) ออกเสีย ส่วนจะเลือกเอาเครื่องหมายหน้าบรรทัดไหนออกนั้น ก็ขึ้นอยู่กับว่าต้องการให้แสดงความช่วยเหลือเป็นแบบ html หรือ chtml นั่นเอง

ในขั้นตอนของการ build package นั้น ขอแยกกล่าวเป็นสองกรณี คือการ build บน Macintosh บน Linux และการ build บน Windows

บน Macintosh นั้น ถ้าต้องการความช่วยเหลือภาษาไทย ก็สร้างแฟ้มความช่วยเหลือในรูปแบบ Rd เป็นภาษาไทยอย่างเดียวได้เลย แล้ว build package ตามที่อธิบายไว้ในบท “การ build package ใน R” ได้เลย

บน Linux นั้น เนื่องจากการ build เป็นภาระของผู้ใช้เอง ดังนั้นอาจต้องเตรียมแฟ้ม .tar.gz ไว้ทั้งที่มีแฟ้มความช่วยเหลือภาษาไทยและอังกฤษ ให้ผู้ใช้เลือกที่จะ build แบบใดแบบหนึ่งต่อไปนี้ด้วยตัวเอง

หากไม่ต้องการใช้ความช่วยเหลือแบบ text ก็สามารถสร้างแฟ้มความช่วยเหลือรูปแบบ Rd เป็นภาษาไทยอย่างเดียวได้เลย แต่หากเรียกคำสั่ง help โดยไม่ระบุตัวเลือก html=TRUE แล้ว จะได้ข้อความช่วยเหลือเป็น text ที่อ่านไม่รู้เรื่อง เนื่องจากความช่วยเหลือแบบ text นั้นจะแสดงบน terminal console ซึ่งแสดงภาษาไทยไม่ได้

ดังนั้นถ้าต้องการให้ข้อความช่วยเหลือรูปแบบ text ที่อ่านออกเป็นภาษาอังกฤษด้วย ก็จะต้อง build package สองครั้ง โดยครั้งแรกแนะนำให้ build โดยใช้แฟ้ม .tar.gz ที่มีแฟ้มความช่วยเหลือเป็นภาษาไทยก่อน โดยเมื่อขยายแฟ้มออกมาแล้ว ให้ build ด้วยคำสั่ง

R CMD INSTALL package_name

จากนั้นจึงขยายแฟ้ม .tar.gz ที่มีแฟ้มความช่วยเหลือภาษาอังกฤษออกมา แล้ว build ด้วยคำสั่ง

R CMD check package_name

อีกครั้ง คราวนี้จะได้โฟลเดอร์ package_name.Rcheck ขึ้นที่ root (ในการ build package จะต้อง login เป็น root เสมอ) จากนั้นเข้าไปในโฟลเดอร์ package_name.Rcheck/package_name จะเห็นโฟลเดอร์ชื่อ help อยู่ ให้คัดลอกโฟลเดอร์นี้ไปไว้ในโฟลเดอร์ R_HOME/library/package_name ทับโฟลเดอร์ help ที่มีอยู่เดิม โฟลเดอร์ R_HOME อาจแตกต่างกันตามแต่ระบบ Linux ที่ใช้ ทางที่ดีให้ใช้วิธีค้นหาชื่อของ package ในโฟลเดอร์ / (ไม่ใช่ /root) จะเห็นว่าการทำค่อนข้างยุ่งยากพอสมควร

ส่วนบนระบบ Windows นั้น ผู้พัฒนา package จะต้องแจกจ่ายแฟ้ม package ในรูปแบบ zip จึงต้อง build package เสียก่อน นั่นคือผู้พัฒนาสามารถทำแฟ้ม package_name.zip ที่มีโฟลเดอร์ความช่วยเหลือ html และ chtml เป็นภาษาไทย ขณะที่แฟ้มในโฟลเดอร์ help เป็นภาษาอังกฤษได้เลย

ขั้นตอนการ build ให้ build package ด้วยแฟ้มความช่วยเหลือภาษาอังกฤษ โดยใช้คำสั่ง

Rcmd check package_name

ดังที่ได้กล่าวแล้วในบท “การ build package ใน R” ซึ่งจะต้องออกคำสั่งนี้สองครั้งดังได้กล่าวในบทความ เมื่อเสร็จแล้วจะได้โฟลเดอร์ package_name.Rcheck ซึ่งภายในมีโฟลเดอร์ package_name อยู่ ให้ zip โฟลเดอร์นี้เป็น package_name.zip ที่มีแฟ้มความช่วยเหลือเป็นภาษาอังกฤษล้วน พร้อมแจกจ่ายให้กับชาวต่างประเทศได้ จากนั้นเปลี่ยนชื่อโฟลเดอร์ package_name.Rcheck นี้ให้เป็น package_name.Rcheck.en เพื่อให้รู้ว่าเป็นโฟลเดอร์ที่มีแฟ้มความช่วยเหลือเป็นภาษาอังกฤษ

จากนั้น build package ที่มีแฟ้มความช่วยเหลือเป็นภาษาไทย ในการออกคำสั่ง

Rcmd check package_name

ในรอบแรกนั้น ก่อนเรียกใช้โปรแกรม HTML Help Workshop จะต้องแก้ไขข้อความในแฟ้มทุกแฟ้มในโฟลเดอร์ chm ที่คำสั่งได้สร้างขึ้นใหม่เสียก่อน

เมื่อเปิดโฟลเดอร์ chm จะเห็นแฟ้มต่างๆ ที่มีนามสกุลเป็น .html โดยจะต้องมีแฟ้มแรกเป็น 00Index.html เสมอ ส่วนแฟ้มอื่นๆ จะมีชื่อตามแฟ้ม Rd ที่สร้างไว้เดิมนั่นเอง ตามด้วยนามสกุล .html ให้เปิดแฟ้ม 00Index.html ด้วยโปรแกรม text editor ที่มีอยู่ เช่น Notepad หรือ Notepad++ หรือ Crimson Editor หรือโปรแกรมอื่นก็ได้ ไม่ควรเปิดด้วย Word เพราะอาจเผลอบันทึกแฟ้มเป็น .doc ซึ่งจะทำให้การทำงานต่อไปไม่ถูกต้องได้

ในแฟ้ม 00Index.html นั้น สามบรรทัดแรกจะเป็นดังนี้

หมายเหตุ ในข้อความในแฟ้ม html ต่อไปนี้ จะใช้เครื่องหมาย ( ) แทนเครื่องหมาย <> ทั้งนี้เพราะเป็นเครื่องหมายที่จะมีผลต่อการแสดงผลทางเว็บ และไม่สามารถแสดงบนหน้าจอนี้ได้ เมื่อจะนำไปใช้จริงให้เปลี่ยนกลับเป็นเครื่องหมาย <>

(html)(head)(title)Functions for Epidemiology(/title)
(link rel="stylesheet" type="text/css" href="Rchm.css")
(/head)(body)

ข้อความใน tag (title)…(/title) จะเปลี่ยนไปตามที่ระบุคำอธิบาย package นั้นๆ

ให้แทรกบรรทัดต่อไปนี้เป็นบรรทัดที่สองหรือสามก็ได้

(meta http-equiv="Content-Type" content="text/html; charset=tis-620")

จะได้ดังนี้

(html)(head)(title)Functions for Epidemiology(/title)
(link rel="stylesheet" type="text/css" href="Rchm.css")
(meta http-equiv="Content-Type" content="text/html; charset=tis-620")
(/head)(body)

ทั้งนี้เพื่อระบุให้การ compile แฟ้มความช่วยเหลือที่เป็น chtml นั้นให้ใช้ภาษาไทยชุดอักษร tis-620 แก้เช่นนี้กับทุกแฟ้มในโฟลเดอร์ chm นี้

จากนั้นเรียกโปรแกรม HTML Help Workshop เพื่อ compile สร้างแฟ้มความช่วยเหลือ chtml แล้ว build package ใหม่อีกครั้ง คราวนี้จะได้โฟลเดอร์ package_name.Rcheck ที่มีแฟ้มความช่วยเหลือเป็นภาษาไทย แต่สามบรรทัดแรกในแฟ้มความช่วยเหลือรูปแบบ html จะกลับไปเป็นเหมือนเดิมอีก และแฟ้มความช่วยเหลือในรูปแบบ text ที่ยังเป็นตัวอักษรไทยที่อ่านใน R console ไม่ได้อยู่

ขั้นตอนต่อไปเป็นการแก้ไขให้แฟ้ม html บังคับให้โปรแกรม browser ใช้ชุดตัวอักษรภาษาไทย tis-620 ทำได้โดยเข้าไปในโฟลเดอร์ html ในโฟลเดอร์ package_name.Rcheck แล้วเปิดทุกแฟ้มมาแก้ส่วน head เช่นเดียวกับที่กล่าวข้างต้นอีกครั้งหนึ่ง เช่นในแฟ้ม 00Index.html จะมีสามบรรทัดแรกเป็น

(html)(head)(title)R: Functions for Epidemiology(/title)
(link rel="stylesheet" type="text/css" href="../../Rth.css")
(/head)(body)

ก็แทรกบรรทัดเช่นเดิม จะได้ใหม่เป็นดังนี้

(html)(head)(title)R: Functions for Epidemiology(/title)
(link rel="stylesheet" type="text/css" href="../../Rth.css")
(meta http-equiv="Content-Type" content="text/html; charset=tis-620")
(/head)(body)

หมายเหตุ ขอให้สังเกตว่าบรรทัดที่ 2 นั้นไม่เหมือนเดิมทีเดียว คือจะเรียกแฟ้ม cascade style sheet ที่ต่างกัน

เนื่องจาก R รุ่น 2.0.0 ไม่สามารถแสดงภาษาไทยบน console และความช่วยเหลือที่เป็น text ได้ เมื่อแก้เสร็จแล้ว ให้กลับไปที่โฟลเดอร์ package_name.Rcheck.en ที่ได้สร้างไว้ก่อนแล้ว คัดลอกโฟลเดอร์ help ที่เป็นความช่วยเหลือภาษาอังกฤษนี้มาทับโฟลเดอร์ help ในโฟลเดอร์ package_name ที่อยู่ภายในโฟลเดอร์ package_name.Rcheck ที่เป็นภาษาไทยเสีย เพื่อให้แฟ้มความช่วยเหลือในรูปแบบ text อ่านได้เป็นภาษาอังกฤษ (อาจลบโฟลเดอร์นี้ไปเลยก็ได้ แต่ต้องแจ้งให้ผู้ใช้ทราบว่าในการเรียกความช่วยเหลือสำหรับ package นี้ ต้องเรียกเป็น chtml หรือ html เท่านั้น) แต่สำหรับ R รุ่น 2.1.0 ขึ้นไป สามารถแสดงอักษรภาษาไทยได้อย่างถูกต้อง จึงไม่ต้องเปลี่ยนความช่วยเหลือแบบ text เป็นภาษาอังกฤษ

จากนั้น zip โฟลเดอร์ package_name นั้นดังที่ได้อธิบายไว้ข้างต้น จะได้แฟ้ม package_name.zip ที่มีแฟ้มความช่วยเหลือเป็นภาษาไทยพร้อมแจกจ่ายแก่ผู้ใช้ได้

สนับสนุนโดย สำนักงานกองทุนสนับสนุนการวิจัย (สกว)