Công cụ tài liệu nguồn đơn

Question

Công cụ OSS (hoặc miễn phí) nào có sẵn để soạn thảo một nguồn duy nhất cho tài liệu có thể được sử dụng để tạo các sách hướng dẫn? Cụ thể, trong các định dạng sau:

• trang web HTML
• tài liệu PDF
• nhúng (trong một ứng dụng; có thể HTML)
• Text (không bắt buộc)
• trang Man (không bắt buộc)

Yêu cầu bổ sung:

• Công cụ phù hợp với các nhà văn kỹ thuật (không cần WYSIWYG).
• XML/SGML nguồn
• chất lượng cao đầu ra PDF (so sánh với TeX)
• Multi-nền tảng

mở rộng Yêu cầu

Ứng dụng dòng lệnh tương tự được viết bằng hai ngôn ngữ (C và Java). Sử dụng XML để mô tả các tùy chọn dòng lệnh (một số trong đó là cụ thể cho một ngôn ngữ hoặc một ngôn ngữ khác), nó là đơn giản để chuyển đổi XML thành một lớp Java, hoặc một hàm C, viết giúp cho đầu ra tiêu chuẩn. Điều này đảm bảo rằng sự trợ giúp có thể được nhúng vào nhị phân mà không cần phải phụ thuộc vào các tệp bên ngoài.

Dường như AsciiDoc không có khả năng này. Có lựa chọn nào khác không?

Answer 1

Một trong đó đáp ứng hầu hết các yêu cầu của bạn, mà tôi đã sử dụng trước đây, là AsciiDoc.

Mặc dù vậy, AsciiDoc không phải là định dạng nguồn XML, thay vào đó, định dạng này chỉ cho định dạng văn bản đơn giản. Nó có thể xuất ra HTML và Docbook, có thể được hiển thị thành định dạng PDF hoặc các định dạng khác. Văn bản nguồn gần như đủ tốt để trình bày văn bản thuần túy.

Một lựa chọn phổ biến khác dọc theo cùng một dòng là reStructuredText.

Answer 2

Tôi đã cân nhắc việc truyền giáo DocBook làm thay thế cho Word trong nhóm kỹ thuật của chúng tôi. Có một số công cụ có sẵn. Cách dễ nhất cho kỹ sư có thể là DocBook XSL, Apache FOP và Ant hoặc Make. Đây là cách tôi đã làm công cụ DocBook của tôi. Nếu bạn đang thực sự vào LaTeX, sau đó bạn có thể muốn kiểm tra DBLaTeX cho một DocBook để môi trường xuất bản LaTeX.

Nếu bạn không phiền khi bước ra ngoài môi trường tự do, thì <oXygen/> XML Editor cung cấp trình chỉnh sửa DocBook WYSIWYG khá đẹp mắt. Tôi đã không sử dụng nó nhiều, nhưng nó trông khá hứa hẹn.

Answer 3

Sphinx là công cụ thêm một số tính năng vào Docutils, cho phép "tài liệu thông minh và đẹp" được viết bằng reStructuredText. Ban đầu nó được tạo ra để tạo ra tài liệu Python mới nhưng đang được nhiều dự án khác chấp nhận.

Answer 4

Doxygen là trình tạo tài liệu khá phổ biến và có thể xuất tài liệu theo số variety of formats. Mặc dù mục đích chính của nó là xây dựng tài liệu được trích xuất từ ​​các chú thích nguồn (từ nhiều ngôn ngữ), nó cũng khá có thể sử dụng như một công cụ viết tay chung. Trên thực tế, trang web và hướng dẫn sử dụng Doxygen được tạo theo cách này.