Trang `man` rất tuyệt, vấn đề nằm ở trình đọc `man`

• Những lời chê rằng trang man “không có các liên kết kết nối với nhau” hay “văn bản không tự sắp xếp lại khi thu nhỏ cửa sổ terminal” là rất phổ biến, nhưng thực tế bản thân định dạng man đã hỗ trợ tính năng liên kết và sắp xếp lại văn bản
• Vấn đề nằm ở chỗ các công cụ dùng để đọc trang man (lệnh man, less, v.v.) chưa triển khai đúng các tính năng này

Cấu trúc định dạng của trang man

• Tài liệu man chủ yếu được viết theo hai định dạng:
  • mdoc(7): định dạng markup hiện đại, dựa trên ngữ nghĩa
  • man(7): định dạng cũ được dùng trong giai đoạn 1979~1989
• Ví dụ (một phần cú pháp mdoc):

  .Sh NAME  
  .Nm openrc  
  .Nd stops and starts services for the specified runlevel  
  .Sh SYNOPSIS  
  

• .Sh, .Nm, .Nd lần lượt có nghĩa là tiêu đề mục, tên lệnh và phần mô tả
• Nếu muốn chỉnh sửa trực tiếp thì cần tham khảo danh sách macro của mdoc

Chức năng tham chiếu (liên kết) cũng đã được tích hợp sẵn

• Định dạng mdoc có các macro liên kết như sau:
• .Xr: tham chiếu chéo đến trang man khác
• .Sx: tham chiếu đến mục khác trong cùng một trang
• Khi chuyển sang HTML, chúng được render thành liên kết thật và có thể bấm trong trình duyệt
• Tiêu đề mục .Sh được xử lý như anchor nên có thể trở thành đích đến của liên kết .Sx
• Nhưng khi xem trong terminal bằng lệnh man, chức năng liên kết này không hoạt động

Kết luận: vấn đề không phải ở định dạng man mà ở trình xem

• Hiện tại lệnh man hiển thị trang bằng cách pipe sang less, và cách này không thể xử lý liên kết
• Giải pháp là:
• cần một trình xem trang mới hiểu định dạng man và hỗ trợ liên kết
• Nếu đồng thời triển khai thêm tính năng tự động sắp xếp lại văn bản (reflow) khi thay đổi độ rộng terminal thì sẽ còn tốt hơn

Thông tin nền

• mdoc(7) là định dạng được giới thiệu trong 4.4BSD vào thập niên 1990
• man(7) là định dạng cổ điển được dùng từ 1979 đến 1989, hiện gần như không còn được sử dụng

[scari]

Tôi chỉ nhìn dòng đầu trong thông báo của Slackbot là đã thấy đồng cảm ngay và bấm vào. Tôi cũng đồng ý 100% với nhận định rằng vấn đề nằm ở trình đọc.

...Nhưng có vẻ con người thời hiện đại không chỉ không dùng man mà thậm chí còn không dùng cả terminal nữa. rtfm giờ đã trở thành di vật lãng mạn của một thời rồi.

[winterjung]

Tôi khai báo như bên dưới trên mac và dùng kiểu pman ls để xem dưới dạng PDF.

pman() {  
  mandoc -Tpdf "$(man -w $@)" | open -f -a Preview  
}  

[pcj9024]

Mẹo siêu hay... cảm ơn bạn

[pkj3186]

Tuyệt vời, cảm ơn rất nhiều

[bbulbum]

Wow, mình đồng cảm quá. Nếu đọc man tốt thì nó thực sự rất hữu ích, nhưng để đọc cho tốt thì khó quá..

[GN⁺]

Ý kiến trên Hacker News

• Có ý kiến cho rằng dù đã viết tài liệu theo định dạng mdoc và mandb trong thời gian dài, việc thành thạo ngôn ngữ này vẫn rất khó
  • mdoc và mandb giống như các bộ macro nằm trên roff
  • Có người muốn đề xuất chuyển toàn bộ trang man sang Markdown để hệ thống hiển thị
  • Markdown có nhiều công cụ hơn nên ngay cả người dùng không chuyên cũng có thể dễ dàng viết tài liệu
  • Nhưng Markdown ít tính hình thức hơn nên tồn tại nhiều phương ngữ khác nhau giữa các chương trình
• Việc duyệt các trang info trong Emacs khá hữu ích, và có thể làm điều tương tự với trang man
  • Sự phong phú của các trang man hiện tại là một ưu điểm mà nhiều người chưa nhận ra
  • Có sự tiếc nuối với những người muốn chuyển sang Markdown
  • Nếu chuyển sang Markdown, sẽ khó triển khai liên kết và ngữ nghĩa tổng quát của các giải pháp hiện có
  • Nhìn vào các trường hợp chuyển dữ liệu sang JSON, có thể thấy nhiều nỗ lực nhằm bổ sung các tính năng phức tạp
• Dùng ft-man-plugin tích hợp sẵn của Vim làm trình đọc man mặc định giúp ích cho việc giải quyết vấn đề
  • Liên kết hoạt động tốt và vẫn giữ thụt lề khi xuống dòng
  • Có thể cải thiện cấu hình mặc định của less, nhưng sẽ cần cuộn ngang
• Nhiều phiên bản web của trang man dùng phông chữ đơn cách một cách đơn điệu, khá đáng tiếc
  • Trang man trực tuyến của OpenBSD rất xuất sắc
  • Đọc trang man trong terminal cũng rất tốt
  • Chủ yếu dùng chức năng tìm kiếm và cuộn nửa trang
• pinfo vốn dùng để xem các trang GNU Info, nhưng cũng có thể hiển thị trang man
  • Nó nhận diện và cho phép điều hướng các tham chiếu chéo giữa các trang
• Có ý kiến cho rằng sẽ rất hay nếu có chức năng nhảy đến phần giải thích của một cờ cụ thể
  • Hiện tại người ta dùng biểu thức chính quy để tìm phần mô tả của cờ
• Có đề xuất nên cân nhắc dự án mandoc
  • Dự án này có thể xử lý trang theo ngữ nghĩa để cho kết quả tốt hơn
• Có ý kiến cho rằng Markdown là giải pháp tốt hơn
  • Mọi người đã quen đọc tài liệu trên web hoặc trong trình soạn thảo mã, nên các giao diện khác gây bất tiện
  • Các nhà phát triển đã quen với Markdown và phần lớn tài liệu cũng được viết bằng Markdown
  • Trang man kém hơn cho cả người viết tài liệu lẫn người đọc