hylomによる
2009年04月27日 21時07分の掲載
そういえば意外に思い当たらない、部門より
そういえば意外に思い当たらない、部門より
何本か技術的なドキュメントを書きたいんだが、良いジェネレータが見つからない。一つのリソースからHTMLとPDFを生成したい。体裁としてはAppleの開発ドキュメントのようなものを想定している（例 Core Data Programming Guide）。frameなどで章を行き来できることが最低条件である（伝統的なprevious, next, topナビゲーションからは脱却したい）。
将来的な共同作業を考えるとクロスプラットフォームなツールが望ましい。また副次的な要求であるがバージョン管理を考えるとリソースはテキストである方が扱いやすいだろう。すぐに思い浮かぶのがtexとWikiであるが、texは強力ではあるが日本語環境構築が私家版に頼りすぎている（というか私家版しかない）ので好みではない。Wikiは掲示板機能などのライブな情報蓄積が魅力ではあるが、章構成に弱いことが不満である。PDFの生成ができるWikiについては未調査である。
テキストでないリソースとしてはOpenOfficeがPDFとHTMLを作成でき、またPDFの作成では見出しからしおりを生成してくれるので好印象ではある。しかし、生成されるHTMLは単一ページであり章を行き来するのが面倒であることが不満である。
ソースコードからドキュメントを生成するツールについてはjavadocやdoxygenなど豊富であるが、ソースを元としない、技術解説に適したツールにはどのようなものがあるだろうか？
emacs muse (スコア:4, 参考になる)
emacs使いには、emacs museがおすすめです。
一つのリソースからHTMLとPDFを生成できます。
(PDFに関しては、一旦texに出力し、dvi -> pdf という変換によって実現します。AUCTexも組み合わせると、2アクションで行けます)
公式ページは下記です。
前身のemacs wikiというのをしばらく使っていたところ、下記ページにより、emacs museを知り、これは！と思った次第。
(ただし下記ページは、使い方の解説に関しては、makeでインストールしてなかったり、*.elファイルを直接編集したりと、いい加減です。)
わたくしめがまとめたページもありますので、よければ参考にしてください。
(museを使って生成しています)
コメントを書く
texinfo, pod, man (スコア:3, すばらしい洞察)
コメントを書く
Re:texinfo, pod, man (スコア:4, 参考になる)
系列だった。m はmacroのmで、指定されたmacro を使って、段落とか章とかを作っておったのじゃ。
論文を書く時には、自分専用のmacro packageぐらい持っておったのものじゃ。
TeX自体も、macro processor と formatter の組合せに過ぎず、LaTeX は、TeX の上の一つのmacroの
流儀に過ぎんのじゃよ。それは、-me とか -ms とか -man に対応するという言うわけじゃ。
今の、man のformatは、-ms の陰も形もないがのう〜
コメントを書く
親コメント
うーん (スコア:2, 参考になる)
WikiならTracがplain/html/pdf出せた気が(自信ない)、ドキュメントジェネレータならasciidocみたいなのがあるね。
# 決定版と呼べるのが、なかなかないよねぇ。
BOINC説明ページ(書きかけ) [bit.ly]
コメントを書く
Re:うーん (スコア:2, 参考になる)
でき上がりはこんなかんじ [makezine.com]のようです。
＃これがそのExtensionかどうかは確認しておりません。しかし同等の物はこのあたり [wikimedia.org]にあるでしょう。
コメントを書く
親コメント
XML+XSLT=XSL-FO(PDF) or HTML (スコア:2)
手間はかかりますが、XMLでドキュメント作成、XSLTでHTML/XSL-FO(PDF)という手段があります。
HTMLはまだしもXSL-FOに変換するには結構大変なのと、元となるXMLのスキーマをどうするかというのが問題になります。
一応標準技術の寄せ集めなのでつぶしは利くのと、XMLベースなので履歴管理はしやすいのとツール類がある程度あるのがメリットでしょうか。
コメントを書く
Re:XML+XSLT=XSL-FO(PDF) or HTML (スコア:2)
個人的には…
XML は文明的ではあるが、文化的とは言いがたい。
（文化的とは何か？という問題はおいとく。）
## ジェネレータと言われて難解バカボンを先に思い出した
[Q][W][E][R][T][Y]
コメントを書く
親コメント
Re:XML+XSLT=XSL-FO(PDF) or HTML (スコア:2)
不勉強でDITAというものを知りませんでした。
元ACさん、下のACさん、ありがとうございます。
Google先生に聞いてDITAの仕様を見ていますが、とても面白そうですね。
自分が「あればいいな」と思っていた仕様かもしれません。
時間があるときに詳しく調べて見ようと思います。
ご指摘感謝します。
コメントを書く
親コメント
Re:XML+XSLT=XSL-FO(PDF) or HTML (スコア:2, 参考になる)
コメントを書く
親コメント
PukiWiki+Copper PDF (スコア:2, 参考になる)
PukiWikiのPDF出力プラグイン
http://pukiwiki.sourceforge.jp/?%E8%87%AA%E4%BD%9C%E3%83%97%E3%83%A9%E... [sourceforge.jp]
＋
Copper PDFの個人向けライセンス
http://copper-pdf.com/?cat=11 [copper-pdf.com]
でどうかな？
コメントを書く
当然 (スコア:2, おもしろおかしい)
Excel
生成作業はもちろん人手でやります。日本では機械が自動生成したものはありとあらゆる理屈を付けて否定されます。わざわざ人間様が手間暇掛けて生成してやっと最低限文化的であると認められます。人間様が労働力を投入してさえいれば実際の品質はまったく問題ではありません。
コメントを書く
自分を振り返ってみよう (スコア:1, おもしろおかしい)
死ねばいいのになどと平気で吐く奴自体が文化的なわけが無いよな
コメントを書く
日本語対応 (スコア:1, すばらしい洞察)
> texは強力ではあるが日本語環境構築が私家版に頼りすぎている
>（というか私家版しかない）ので好みではない。
ASCII-pTeXレベルで「私家版しかないので好みではない」って話だと、
ほとんどのフリーウェアのlocalizeは「好みではない」ってことだろうか。
＃ 本家に取り込まれないものは全否定？
敷衍するとプロジェクトのforkすら許せないって純血主義にもなりそうですが。
コメントを書く
Re:日本語対応 (スコア:3, 興味深い)
現状、LaTeXを上まわるものはありません。MS Wordは相互参照や数式の多い文書でハングアップするバグを直す気はなさそうだし。（学者人口なんてたかが知れているのでビジネスにならないということでしょう。）
もっとも、数式を全然使わない人がドキュメントの基本としてLaTeXを使う必要もないかと。しかし、ある程度の水準以上の数学を使う人にとっては、現状、LaTeX（とくにAMS LaTeX）以上のものはないでしょうね。
コメントを書く
親コメント
最低限度文化的なドキュメントジェネレータとは？ (スコア:1, おもしろおかしい)
どこの絶望先生だよｗ
コメントを書く
Re:最低限度文化的なドキュメントジェネレータとは？（オフトピ） (スコア:4, おもしろおかしい)
その突っ込みは間違っていると思う。
「ドキュメントの自動生成なんて文化的すぎます！」
コメントを書く
親コメント
Re:最低限度文化的なドキュメントジェネレータとは？（オフトピ） (スコア:2, おもしろおかしい)
つ『edlin』
# ジェネレートしてないじゃないですか！
## GUIどころかスクリーンエディタですらないし！
### スクリーンエディタなんて文化的過ぎます。ただ"copy con"だと原始的過ぎるので、edlinでいいでしょう。
コメントを書く
親コメント
それって (スコア:1, すばらしい洞察)
技術的なドキュメントを書く「技術」がないから誰か助けて、ってこと？
それならまず練習、次に練習、後はそうだな、練習かな？
コメントを書く
PDF出力可能なWikiについて (スコア:1)
コメントを書く
Re:PDF出力可能なWikiについて (スコア:2, 興味深い)
Wikipediaの英語版には、「ブック作成」という機能のがあります。これを使うと、好きなページを指定して、それを適当に並べ替えてPDFにすることが出来ます。そうすると、結構な量のウェブページを一気にPDFにすることが出来ます。
詳しくは、 http://en.wikipedia.org/wiki/Help:Books [wikipedia.org] のページを。
この機能は、日本語版にはありませんので、あしからず。
コメントを書く
親コメント
LaTeXソース流しこめるWikiがあれば嬉しい (スコア:1)
普段はかなりLaTeXべったり、スライドもseminarスタイルな私なので、LaTeXソース流しこめるWikiがあれば嬉しいです。一部のWikiエンジンではLaTeXスタイルで数式を書くと裏でLaTeX呼び出して画像として数式を作成してくれるものもありますが。
屍体メモ [windy.cx]
コメントを書く
SmartDoc (スコア:1)
XMLで記述して、HTMLやLaTeXで出力できます。 ウチではLaTeXからPDFも生成しています。
HTMLやTeXのタグも記述できるため、出力方式毎に微調整が可能。 CSS、.styで見た目はどのようにも加工できます。
コメントを書く
Re:SmartDoc (スコア:2)
最近使ってないな～
locale属性（だったかな？）日本語と英語のドキュメントを同じxmlに書けるというのが重宝してました。
コメントを書く
親コメント
WEB (スコア:1)
コメントを書く
SourceForge.JPをSourceForgeというのは (スコア:1, 参考になる)
WikipediaをWikiと書くようなものであまり望ましい傾向ではないのだが、それはさておいて、そのWikipediaのエンジンであるMediaWikiにはPDFを出力する拡張があって、Wikibookの一部作品がPDFでも入手できてたと記憶している。
コメントを書く
親コメント
Re:DocBookなんかどうでしょ？ (スコア:1)
使えるようになりたくて最近調べていましたが、
日本語の情報が少なくて情報が少なくてつらいです。
funcsynopsisとかclasssynopsisとか関数やクラスの記述方法はあるみたいですが、
名前空間とグローバル変数の記述方法が見当たらず悩んでいます。
いい実例をご存知の方は教えてください。
コメントを書く
親コメント
Re:DocBookなんかどうでしょ？ (スコア:1, 参考になる)
AdobeのFrameMakerあたりがいいんだろうけど、Adobe製品の常で個人で買うには高すぎるかｗ 他にはWYSIWYGじゃないXMLエディタだとEmacsのnXML modeとかXML Copy Editor [sourceforge.net]が、WYSIWYGなやつならoXygen XML Editor [oxygenxml.com]とかXMLmind XML Editor [xmlmind.com]などがある。初心者向けかどうかは知らんけど。
コメントを書く
親コメント