最低限度文化的なドキュメントジェネレータとは？ 92
ストーリー by hylom
そういえば意外に思い当たらない、 部門より
そういえば意外に思い当たらない、 部門より
何本か技術的なドキュメントを書きたいんだが、良いジェネレータが見つからない。一つのリソースから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を使って生成しています)
Re:emacs muse (スコア:1, 興味深い)
補足しておくと、docbookやオープンオフィス形式のファイルも作れるので そこから変換すればWordやパワーポイントのファイルも作成できます。
私はいつもEmacsMuseでWord文書を作成してます。
texinfo, pod, man (スコア:3, すばらしい洞察)
Re:texinfo, pod, man (スコア:1)
texinfo,podはともかく今時(一から書くのに)man(troff)はないと思う。
htmlですら文章構造と表現の分離が言われてるのに、manは太字とか表現だけ（もしかしたらマクロで何でもできるのかもしれんが、そういった例を見たことはない）
Re:texinfo, pod, man (スコア:4, 参考になる)
系列だった。m はmacroのmで、指定されたmacro を使って、段落とか章とかを作っておったのじゃ。
論文を書く時には、自分専用のmacro packageぐらい持っておったのものじゃ。
TeX自体も、macro processor と formatter の組合せに過ぎず、LaTeX は、TeX の上の一つのmacroの
流儀に過ぎんのじゃよ。それは、-me とか -ms とか -man に対応するという言うわけじゃ。
今の、man のformatは、-ms の陰も形もないがのう〜
Re: (スコア:0)
むしゃくしゃしたのでplain textのままcatディレクトリに放り込んだ。
今は後悔している。
うーん (スコア:2, 参考になる)
WikiならTracがplain/html/pdf出せた気が(自信ない)、ドキュメントジェネレータならasciidocみたいなのがあるね。
# 決定版と呼べるのが、なかなかないよねぇ。
M-FalconSky (暑いか寒い)
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 (スコア:1, 参考になる)
Re:XML+XSLT=XSL-FO(PDF) or HTML (スコア:2)
不勉強でDITAというものを知りませんでした。
元ACさん、下のACさん、ありがとうございます。
Google先生に聞いてDITAの仕様を見ていますが、とても面白そうですね。
自分が「あればいいな」と思っていた仕様かもしれません。
時間があるときに詳しく調べて見ようと思います。
ご指摘感謝します。
Re:XML+XSLT=XSL-FO(PDF) or HTML (スコア:2, 参考になる)
Re:XML+XSLT=XSL-FO(PDF) or HTML (スコア:1)
DITA は、個々の情報の固まりである Topic と、文書にまとめるときの
組み立てを表現する Map の概念を分けることで、なるべく One source
であることを守ろうとする構造はすばらしいと思います。
特殊化によって、フォーマットを決めていけるところも、XML の良さを
うまく生かしていると思います。
正直、僕のなかでは理想に近いのですが、現在のところ、
素人さんでも使いやすい標準的なエディタが見あたらないのが
悩みです。
皆さんのおすすめエディタがあれば、教えてください。
Re: (スコア:0)
Adobe FrameMakerもDITAをサポートしてたっけな。
それならタグ打ちの苦手な人もOKか。
PukiWiki+Copper PDF (スコア:2, 参考になる)
PukiWikiのPDF出力プラグイン
http://pukiwiki.osdn.jp/?%E8%87%AA%E4%BD%9C%E3%83%97%E3%83%A9%E3%82%B0... [osdn.jp]
＋
Copper PDFの個人向けライセンス
http://copper-pdf.com/?cat=11 [copper-pdf.com]
でどうかな？
当然 (スコア:2, おもしろおかしい)
Excel
生成作業はもちろん人手でやります。日本では機械が自動生成したものはありとあらゆる理屈を付けて否定されます。わざわざ人間様が手間暇掛けて生成してやっと最低限文化的であると認められます。人間様が労働力を投入してさえいれば実際の品質はまったく問題ではありません。
自分を振り返ってみよう (スコア:1, おもしろおかしい)
死ねばいいのになどと平気で吐く奴自体が文化的なわけが無いよな
日本語対応 (スコア:1, すばらしい洞察)
> texは強力ではあるが日本語環境構築が私家版に頼りすぎている
>（というか私家版しかない）ので好みではない。
ASCII-pTeXレベルで「私家版しかないので好みではない」って話だと、
ほとんどのフリーウェアのlocalizeは「好みではない」ってことだろうか。
＃ 本家に取り込まれないものは全否定？
敷衍するとプロジェクトのforkすら許せないって純血主義にもなりそうですが。
Re:日本語対応 (スコア:1, すばらしい洞察)
まあ多分公式ヅラしたWindows版バイナリがないことを指してるんだと思いますが、角藤版W32TeX [kindai.ac.jp]のレベルで私家版だから嫌と言う人に、お勧めできる処理系はないよなあ。
LaTeXアレルギーさえ何とかなるなら、だいぶ昔のストーリーになりますがLaTeX2e 10 周年 [srad.jp]でのOliverのコメント [srad.jp]なんかが参考になるかと。
Re:日本語対応 (スコア:1)
日本語アドオン、なんて「今っぽい」言葉ではなく、japanese環境を使えばできます。
そのへんはおそらく日本で唯一のMikTeXの入門書はじめてのLaTeX—簡単「MiKTeX」と充実「W32TeX」で完全マスター! [amazon.co.jp]
あたりを参考にどうぞ。
Your 金銭的 potential. Our passion - Micro$oft
Tsukitomo（月友）
Re:日本語対応 (スコア:1)
元トピの
> texは強力ではあるが
というのはたぶんLaTeXのことだろうけど、LaTeX自体がある意味
私家版だよね。
>日本語環境構築が私家版に頼りすぎている
だったら日本語使わなければいいのにとしか思えない。
Re: (スコア:0)
標準化って行為は特定の実行環境への依存度を下げることに意義があるんだけど、それを理解していない開発者の多いこと多いこと。
Re:日本語対応 (スコア:1)
Re: (スコア:0)
TeXはいろんな意味で終わってると思います。
何もかもがバラバラで情報も散逸してますし。
もちろんLaTeXで簡単に出来る範囲内でのことしかしないんなら良いですけど
ちょっと手の込んだことをやろうとすると
アレも駄目これも駄目ってのがボロボロ出てきてかなりがんばらないと駄目です。
TeXに時間をとられるくらいならほかのことにその労力を費やしたほうが有意義でしょう。
Re:日本語対応 (スコア:3, 興味深い)
現状、LaTeXを上まわるものはありません。MS Wordは相互参照や数式の多い文書でハングアップするバグを直す気はなさそうだし。（学者人口なんてたかが知れているのでビジネスにならないということでしょう。）
もっとも、数式を全然使わない人がドキュメントの基本としてLaTeXを使う必要もないかと。しかし、ある程度の水準以上の数学を使う人にとっては、現状、LaTeX（とくにAMS LaTeX）以上のものはないでしょうね。
Re: (スコア:0)
Wordなんて組版ソフトウェアとして見たら下の下もいいところじゃん。それを使ってくれって案件も多いけどさ（つーか最近じゃExcelで組版の案件とかあって、もう泣けるｗ）
Re:日本語対応 (スコア:1)
基本のTeXはバージョンアップの終了が宣言されていますね。
これはバージョン依存の問題を起こしにくいという利点でもあります。もちろん拡張した側による問題発生はありうるけれど。
ただ、TeX系ではできないことも多いのはたしかかも。どこでハマったかいまいち思い出せないのですが何かで苦労した記憶はある･･･便利で強力だけれど融通がきかないところはありますね。
Re: (スコア:0)
たしかに。TeXの配布一つ取ってもUNIX向けはほぼteTeX（pTeXも今はteTeXベース）だろうけど、これがWindowsになるとMikTeXが強いし。あと国際化、多言語化もあまり考えられてなくてL10N版の亜種は腐るほど存在する。Omegaみたいな試みもあったけど、今でも広く普及するには至ってない。そもそも元のTeXが機能拡張を停止していて、クヌース先生が死んだ時点で終了ってソフトウェアだから、いろんな意味で終わってる気はする。
Re: (スコア:0)
> そもそも元のTeXが機能拡張を停止していて、クヌース先生が死んだ時点で終了ってソフトウェアだから、いろんな意味で終わってる気はする。
何を勘違いしているのか知りませんが、名前を変えさえすれば、誰でもTeXを改変して再配布できますよ。もちろんKnuthの死後でも。
TeX自体の機能拡張が止まっているのは、既に組版に必要な基本機能が完備されていて、その上で自分のやりたいことはマクロの追加で実現できるからです。
Re: (スコア:0)
特定の実行環境への依存度を下げた結果、どの環境でも使い物にならないようでは困るんだよね。
これはバランスの問題であって、「好みではない」という理由だけでは全く説得力がない。
Re:日本語対応 (スコア:1, すばらしい洞察)
亜流だか私家版だかよく分からないのが氾濫してるし
環境構築は面倒で、同じ環境をもう一度作る自信など微塵もないし
ちょっと違う事をしようと思うと難解なマクロやら文法と戦わなきゃいけないし
これはひどい。 と思うんだけど
それでも他のものと比べると雲泥の差なんだよ
最初に一度だけ環境構築が出来れば、後は困る事は無いしねぇ
最低限度文化的なドキュメントジェネレータとは？ (スコア: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] のページを。
この機能は、日本語版にはありませんので、あしからず。
Re:PDF出力可能なWikiについて (スコア:1)
Texinfo? Gopher?
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)
DocBookなんかどうでしょ？ (スコア:0)
処理系は豊富だし、必要ならスタイルシートをカスタマイズするとか。
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]などがある。初心者向けかどうかは知らんけど。
SourceForge (スコア:0)
http://osdn.jp/projects/linux-kernel-docs/wiki/FrontPage [osdn.jp]
SourceForgeのWikiのPDF出力はそこそこかと。OSS限定になりますが。
SourceForge.JPをSourceForgeというのは (スコア:1, 参考になる)
WikipediaをWikiと書くようなものであまり望ましい傾向ではないのだが、それはさておいて、そのWikipediaのエンジンであるMediaWikiにはPDFを出力する拡張があって、Wikibookの一部作品がPDFでも入手できてたと記憶している。
reStructuredText (スコア:0)
要件は満たさないけれども、 (スコア:0)
PDF の作成機能はないけれど、最近気に入って使ってます。
http://www.naturaldocs.org/ [naturaldocs.org]
ドキュメントを書くのに、いちいち決まった形式を要求しないルースな感じ好きです。（もちろん決まった形式に従えば、きれいなのが出来るんだけれども。）