本ドキュメントは、以下のソース(ezht_help.in)から生成されたものです。
この種のツールは、ドキュメントを読むよりもソースと生成物を見比べるほうがずっと早く理解できるものです。
このソース(ezht_help.in)を適当なディレクトリにコピーし、いろいろといじくりまわしてezhtの挙動を確認してみてください。
ezht_help.in:
1: @push lang ja ;; 言語の設定
2: @push charset Shift_JIS ;; 文字コードの設定
3:
4: @push docname "ezht 0.1 help" ;; 本文書の名称
5: @push section-mark "§"
6: @push filename-rule section
7: @push text-index "目次"
8: @push anchor-next "▼"
9: @push anchor-prev "▲"
10: @push anchor-up "△"
11: @push anchor-back "戻る"
12: @push anchor-index "目次へ"
13: @push text-section-disjoined "本セクションは別ページに記述されています:"
14: @push text-relation "関連項目:"
15:
16:
17: @push head ;; <head>と</head>の間に挿入される共通コード
18: <style type="text/css">
19: <!--
20: BODY { color: black;
21: background-color: white;
22: font-size: 11pt;
23: line-height: 14pt;
24: }
25: A:link { color: blue; }
26: A:visited { color: blue; }
27: A:active { color: blue; }
28: A:hover { color: tomato; }
29: P { margin: 20px; }
30: P.DISP { background-color: wheat}
31: P.DISP2 { background-color: black; color: wheat}
32: -->
33: </style>
34: @end
35:
36: @push body-header ;; <body>の直後に置かれる共通コード
37: <div align="right">
38: <a href="index.html">
39: @image "logo.gif" (border="0")
40: </a>
41: </div>
42: @end
43:
44: @push body-footer ;; </body>の直前に置かれる共通コード
45: <br><br>
46: <hr>
47: <div align="right">
48: Copyright 2004 Tradcrafts. ALL RIGHTS RESERVED.
49: </div>
50: <table width="10" height="600"><tr><td></td></tr></table>
51: @end
52:
53: @push indexfile-introduction ;; インデックスページの前書き
54: <hr>
55: <p>
56: 本ドキュメントはezhtの使用法について記述されています。<br>
57: なお、本ドキュメントはすべてezhtにより自動生成されたものです。
58: @refer source "ソース"
59: と対比させながらご覧頂けばより早く理解できると思います。
60: </p>
61: <hr>
62: <br>
63: @end
64:
65: ;; ここからセクションの記述
66:
67: @section "ezhtについて" joined
68: <p>
69: 本セクションは、ezhtの概要・動作環境等について記述されています。
70: </p>
71: <p>
72: @index
73: </p>
74: @section "概要"
75: <p>
76: @begintext
77: ezhtは、平易な書式で記述されたソースを読み込み、ある程度複雑な構造を持つHTMLによる階層化された一連のドキュメントを自動生成するためのテキストコンバータです。
78: 概念的には、ezhtはsgml2html,latex2html,texi2htmlなどのコンバータによく似ています。
79:
80: HTMLに関する最低限の知識があれば、誰でも容易に使いこなせるはずです。
81: ただし、ezhtはGUIアプリケーションではありませんので、Windows環境に限って言えばもしかしたら初心者向けではないかもしれません。
82:
83: ezhtは、以前、HTMLによるドキュメント群を早急にそろえなければならなくなった際に急ごしらえで書いたコードを元に、新しいコードをつぎはぎして作っています。
84: テキストべた書きのマニュアルは書くのは楽でも読むのが大変。SGMLやLaTeXはいったん書いてしまえばHTMLなど多種多様な形式に変換できるので非常に便利だけれど、HTML形式の出力をさせるためだけに書くのはいささか高コスト。とにかくHTML形式の出力だけがいますぐ欲しいという場合に、ezhtは効率の良いツールです。
85:
86: @endtext
87:
88: なお、このヘルプもezhtがこちらの
89: @refer source "ソース"
90: から自動的に生成したものです。<br>
91: <br>
92: @relate doc_source refer
93: </p>
94: @end ;; 概要
95:
96: @section "動作環境"
97: <p>
98: @begintext
99: GNU g++のインストールされているUNIX系の環境であれば、おそらくほとんどの処理系でそのままmakeできるはずです。
100: その他のC++処理系の場合はsrc/Makefile中の使用コンパイラを書き換えて下さい。
101: Windows(win32)環境用にはあらかじめバイナリが用意されています。
102: @endtext
103: </p>
104: @end ;;動作環境
105:
106: @section "ライセンス" disjoined
107: <p>
108: ezhtはGNU GPLに準拠するフリーソフトです。
109: GPLについて詳しくは下記をご覧下さい。
110: </p>
111:
112: <p class="DISP">
113: @include "../COPYING.txt" text
114: </p>
115:
116: @end ;; ライセンス
117:
118: @section "生成物の使用制限"
119: <p>
120: 使用制限はありません。<br>
121: ezhtにより生成されたHTMLドキュメント群は、<b>商用非商用を問わずいかなる形態</b>で利用されても問題ありません。
122: </p>
123: @end ;; 生成物の使用制限
124:
125:
126: @section "バグ報告等"
127: <p>
128: ezhtは、まだ十分にテストされていません。<br>
129: バグ報告等は<a href="mailto:freesoft@tradcrafts.com"><addr>freesoft@tradcrafts.com</addr></a>までお願いします。<br>
130: </p>
131: @end
132:
133: @section "更新履歴"
134: <p>
135: @push include-filter (nkf -Es %file%) ;;devlog.txtで使われている日本語コードはEUCなのでSJISに変換させる
136: @autopop include-filter
137: @include devlog.txt text
138: </p>
139: @end ;; 更新履歴
140:
141: @end ;; ezhtについて
142:
143: @section "使用法" joined
144:
145: <p>
146: @index
147: </p>
148:
149: @section "HTML文書ファイル群を生成させる"
150: <p>
151: <kbd>ezht</kbd> <var>ifile</var>
152: </p>
153: <p>
154: とすると、ifileを読み込み、その結果としてカレントディレクトリにHTMLドキュメントを次々と生成する。<br>
155: なお、ifileが<kbd>STDIN</kbd>である場合、標準入力から読み込みが行われる。<br>
156: エラーが発生した場合には生成は行われない。
157: </p>
158: @end ;;
159:
160: @section "ファイル群を生成させず、生成される内容のみを得る"
161: <p>
162: <kbd>ezht</kbd> <var>ifile</var> <var>ofile</var>
163: </p>
164: <p>
165: とすると、<var>ifile</var>を読み込み、その結果生成されるファイル群の情報を<var>ofile</var>に出力する。<br>
166: ここで、<var>ifile</var>が<kbd>STDIN</kbd>であれば標準入力からの入力、また<var>ofile</var>が<kbd>STDOUT</kbd>であれば結果は標準出力に出力される。
167: </p>
168:
169: <p>
170: 出力の形式は以下の通り:<br>
171:
172: <table bgcolor="wheat"><tr><td>
173: <samp>
174: @begintext
175: +ファイル名(A)
176: -ファイルAの内容
177: -...
178: +ファイル名(B)
179: -ファイルBの内容
180: -...
181: @endtext
182: </samp>
183: </td><tr>
184: </table>
185:
186: </p>
187:
188: <p>
189: つまり、+で始まる行は新しいファイルの開始を意味し、それに後続する-で始まる行はそのファイルの内容である。<br>
190: これが生成されるファイル数分だけ繰り返される。<br>
191: 単純なフォーマットなので、perl等で二次加工するのは容易である。
192: </p>
193: @end ;;
194:
195: @section "ezhtの返り値"
196: <p>
197: ezhtは、成功すれば0を返し、エラーが生じた場合には非0を返す。
198: </p>
199: @end
200:
201: @end ;; 使用法
202:
203: @section "書式" joined
204: <p>
205: @index
206: </p>
207:
208: @section "コメント行"
209: <p>
210: 先頭が;;で始まる行はコメント行である。<br>
211: もし;;で始まる行をコメントとして扱わせたくなければ、<br>
212: <b>&#59;;</b>.....<br>
213: などとすればよい。(&#59;はブラウザ上では;と表示される)
214: </p>
215: @end ;; コメント
216:
217: @section "コマンド行"
218: <p>
219: 先頭が@で始まる行はコマンド行として認識される。<br>
220: <br>
221: @relate "command"
222: <br>
223: コマンドは、引数を取ることができる。<br>
224: 例えば、<br>
225: @command <var>foo</var> <var>bar</var><br>
226: の場合、<var>foo</var>,<var>bar</var>の2つが引数として認識される。<br>
227: <br>
228: 空白要素(スペースやタブ)を含んだ引数を取らせたい場合には、<br>
229: 二重引用符または引用符またはカッコでかこめばよい。つまり、<br>
230: <b>"hoge hoge"</b> <b>'hoge hoge'</b> <b>(hoge hoge)</b><br>
231: はいずれも同じ結果を与える。<br>
232: <br>
233: また、コマンド行中に;;が現れた場合、それ以降はコメントとして扱われる。<br>
234: ただし、それが引用符などで囲まれている場合や、コマンド名や裸の引数に接触している場合はコメントとして認識されない。<br>
235: つまり、<br>
236: <br>
237: <table border="1" cellspacing="2">
238: <tr><td>@command ;;comment</td><td>コメントとして認識される</td></tr>
239: <tr><td>@command;;comment</td><td>'command;;comment'という命令名として認識される</td></tr>
240: <tr><td>@command param;;comment</td><td>'param;;comment'という引数として認識される</td></tr>
241: </table>
242: <br>
243: <br>
244: なお、コマンド行でなく@で始まる行を書かなければならない場合、<br>
245: <b>&#64;</b>.....<br>
246: などとすればよい。(&#64;はブラウザ上では@と表示される)
247: </p>
248:
249: @end ;; コマンド行
250:
251: @section コマンド一覧 joined
252: <p>
253: @index
254: <br>
255: @relate "command"
256: </p>
257: @section "@push - スタックへの値のプッシュ"
258: <p>
259: @begintext
260: ezhtでは、各種スタックに値を積むことにより、動作を変化させることができる。
261:
262: スタックはezhtにおいて一種の変数の役割を果たすが、値を代入するのではなく、値を積むことに特徴がある。
263: スタックは、必要な時に値を積み上げ、必要なくなればポップしてやることにより、直前の状態を復元できるという点で単なる変数より利便性が高い。
264:
265: スタックに値を積むには、
266:
267: @push スタック名 値
268:
269: とするか、
270:
271: @push スタック名
272: 値
273: @end
274:
275: とする。
276: 後者は、値が複数行を必要とする場合に使用する。
277: 通常は前者を使用するべきである。
278:
279: @endtext
280: @relate stack
281: </p>
282:
283:
284: @section "スタック一覧" joined
285: <p>
286: @pop命令で値をプッシュできるスタックを詳説する。<br>
287: <br>
288: @index
289: </p>
290: @section "lang - 使用言語"
291: <p>
292: @begintext
293: @push lang "X"
294: は、使用言語をXに設定する。
295: デフォルトでは "ja"(日本語)である。
296: @endtext
297: </p>
298: @end ;; lang
299:
300: @section "charset - 使用文字セット"
301: <p>
302: @begintext
303: @push charset "X"
304: は、文字セットがXであることを伝える。
305: ezhtが受け付ける文字セットは現在のところiso-8859-1,EUC-JP,Shift_JISの三種類である。
306: なお、文字セット名の大文字小文字は区別しない。(Shift_JISでもshift_jisでもかまわない)
307:
308: UNIX系の環境のデフォルト設定はEUC-JPである。
309: Windows環境のデフォルト設定はShift_JISである。
310: @endtext
311: </p>
312: @end ;; charset
313:
314: @section "docname - ドキュメント名"
315: <p>
316: @begintext
317: @push docname "NAME"
318: は、ドキュメント名をNAMEに設定する。
319: ドキュメント名は、生成されるHTMLドキュメントのタイトルの一部に使われる。
320: デフォルトは "" である。
321: @endtext
322: <br>
323: @relate docname
324: </p>
325: @end ;; docname
326:
327: @section "head - <head>〜</head>間に挿入されるコード"
328: <p>
329: @begintext
330: @push head
331: 挿入されるコード
332: @end
333:
334: は、<head>と</head>の間に挿入されるコードを指定する。
335: デフォルトは "" である。
336: タイトルと文字セットの記述は自動的に行われるため、これらの記述は不要である。
337:
338: 例えば、全ファイル共通のスタイルシートを挿入したければ
339: @push head
340: <style type="text/css">
341: <!--
342: B {color: red}
343: -->
344: </style>
345: @end
346:
347: あるいは、
348:
349: @push head
350: <link rel="StyleSheet" "styles.css">
351: @end
352:
353: などとすればよい。
354:
355: @endtext
356: </p>
357: @end ;; head
358:
359: @section "body-attributes - bodyタグの共通属性(群)"
360: <p>
361: @begintext
362: @push body-attributes "ATTRS"
363:
364: は、生成される文書に共通するbodyタグの属性をATTRSに指定する。
365: デフォルトは "" である。
366:
367: 例えば、
368:
369: @push body-attributes (link="red" alink="blue" vlink="green")
370:
371: とすれば、生成される文書のbodyタグは
372: <body link="red" alink="blue" vlink="green">
373: のようになる。
374:
375: @endtext
376: </p>
377: @end ;; body-header
378:
379: @section "body-header - 共通ヘッダ"
380: <p>
381: @begintext
382: @push body-header
383: 共通ヘッダのコード
384: @end
385: は、生成される文書の<body>に続いて挿入される共通ヘッダを指定する。
386: デフォルトは "" である。
387: @endtext
388: <br>
389: @relate "body-header-footer"
390: </p>
391: @end ;; body-header
392:
393: @section "body-footer - 共通フッタ"
394: <p>
395: @begintext
396: @push body-footer
397: 共通フッタのコード
398: @end
399: は、生成される文書の</body>の直前に挿入される共通フッタを指定する。
400: デフォルトは "" である。
401: @endtext
402: <br>
403: @relate "body-header-footer"
404: </p>
405:
406: @end ;; body-header
407:
408: @section "section-bar-color - セクションのタイトルの背景色"
409: <p>
410: @begintext
411: @push section-bar-color "COL"
412: は、セクションのタイトルの背景色をCOLに指定する。
413: デフォルトでは、"silver"である。
414: ここで、COLORは#rrggbbのようなRGB形式の色コードか、あるいはgrayやblackといった色名のいずれかである。
415: いずれにせよ、一般的なブラウザが認識できる形式であることが前提である。
416: @endtext
417: </p>
418: @end ;; section-bar-color
419:
420: @section "section-mark - セクションのマーク"
421: <p>
422: @begintext
423: @push section-mark "MARK"
424: は、セクションのマークをMARKに指定する。
425: デフォルトは"#"である。
426:
427: 本ドキュメントでは、
428: @push section-mark "§"
429: としてマークを"§"に変更してある。
430:
431: @endtext
432: </p>
433: @end ;; section-mark
434:
435: @section "number-separator - セクション番号のセパレータ"
436: <p>
437: @begintext
438: @push number-separator "SEP"
439: は、セクション番号のセパレータをSEPに指定する。
440: デフォルトは"."である。
441:
442: @endtext
443: </p>
444: @end ;; section-mark
445:
446:
447: @section "anchor-* - アンカー"
448: <p>
449: anchor-*スタックは、セクション間の移動やインデックスページへ戻るためのアンカーテキストあるいはアンカーイメージを指定する。
450: <p>
451:
452: <p>
453: @begintext
454: @push anchor-next "ANC"
455: は、直後のセクションへのアンカーANCを設定する。
456: デフォルトでは "Next>"である。
457:
458: @push anchor-prev "ANC"
459: は、直前のセクションへのアンカーANCを設定する。
460: デフォルトでは "<Prev"である。
461:
462: @push anchor-up "ANC"
463: は、親セクション(親がいなければインデックスページ)へのアンカーANCを設定する。
464: デフォルトでは "Up"である。
465:
466: @push anchor-back "ANC"
467: は、直前のロケーションへのアンカーANCを設定する。
468: デフォルトでは "Back"である。
469:
470: @push anchor-index "ANC"
471: は、インデックスページへのアンカーANCを設定する。
472: デフォルトでは "Index"である。
473:
474: 参考:
475: 本ドキュメントでは、以下のようにアンカーを設定している。
476: @push anchor-next "▼"
477: @push anchor-prev "▲"
478: @push anchor-up "△"
479: @push anchor-index "目次へ"
480: @endtext
481: </p>
482: @end ;; anchor
483:
484: @section "text-section-disjoined - 別ファイルに記述された子セクションへの誘導文"
485: <p>
486: @begintext
487: @push text-section-disjoined "TEXT"
488: は、当該セクションの子セクションが別ページ(別ファイル)に格納され当該セクションと同一ページにはその子セクションのリンクのみが記載される場合に、そのリンクの左側に置かれる誘導文を指定する。
489: デフォルトでは"See -->"である。
490:
491: 本ドキュメントでは、
492: @push text-section-disjoined "本セクションは別ページに記述されています:"
493: としている。
494:
495: @endtext
496: @relate sec_disjoined
497: </p>
498: @end ;; text-section-dijoined
499:
500: @section "indexfile - インデックスページのファイル名"
501: <p>
502: @begintext
503: @push indexfile "FNAME"
504: は、生成されるインデックスページ(つまりezhtの生成するドキュメント群の最上位となるページ)のファイル名をFNAMEに設定する。
505: デフォルトは "index.html" である。
506: @endtext
507: <br>
508: @relate indexfile
509: </p>
510: @end ;; indexfile
511:
512: @section "text-index - インデックスページのサブタイトル"
513: <p>
514: @begintext
515: @push text-index "TEXT"
516: は、インデックスページのサブタイトルをTEXTに設定する。
517: デフォルトは "Index" である。
518:
519: ここで、インデックスページのタイトルは、
520: "ドキュメント名 - サブタイトル"
521: と定められる。
522:
523: @endtext
524: @relate docname
525: @relate indexfile
526:
527: </p>
528: @end ;; indexfile
529:
530:
531:
532: @section "indexfile-introduction - インデックスページの前書き"
533: <p>
534: @begintext
535: @push indexfile-introduction
536: コード
537: @end
538:
539: は、インデックスページに挿入される前書きを指定する。
540: デフォルトは "" である。
541:
542: 例:
543: @push indexfile-introduction
544: <center>
545: 本ドキュメントは○○について書かれています。
546: </center>
547: @end
548:
549: @endtext
550: <br>
551: @relate indexfile
552: </p>
553: @end ;; indexfile-introduction
554:
555: @section "text-relation - 関連セクションのリンク(群)への誘導文"
556: <p>
557: @begintext
558: @push text-relation "TEXT"
559: は、@relate命令によって生成される関連セクションへのリンク(群)への誘導文を指定する。
560: デフォルトでは、"<strong>See also:</strong>"である。
561:
562: 本ドキュメントでは、
563: @push text-relation "関連項目:"
564: としてある。
565:
566: 実例でいえば、こういう(↓)ことである。
567: @endtext
568: </p>
569: <p>
570: @relate reference
571: </p>
572: @end
573:
574:
575: @section "filename-* - ファイル名の命名規則"
576: <p>
577: filename-*スタックは、セクション毎に生成されるファイルの命名規則を規定する。
578: </p>
579:
580: <p>
581: @begintext
582: @push filename-prefix "PREFIX"
583: は、ファイル名の先頭をPREFIXに設定する。
584: デフォルトは "doc" である。
585: @endtext
586: </p>
587:
588: <p>
589: @begintext
590: @push filename-suffix "SUFFIX"
591: は、ファイル名の末尾・拡張子をSUFFIXに設定する。
592: デフォルトは ".html" であるが、これ以外の選択肢としてはおそらく".htm"くらいだろう。
593: 通常変更する必要はないと思われる。
594:
595: @endtext
596: </p>
597:
598: <p>
599: @begintext
600: @push filename-rule "RULE"
601: は、命名ルールをRULEに設定する。
602: 現在、3種類のルールのみを設定できる(下表参照)
603: @endtext
604: <br>
605: <table border=1 cellspacing=2>
606: <tr><th>ルール</th><th>意味</th></tr>
607: <tr><th>line</th><td>ソースファイル上で当該セクションの始まった行番号をファイル名とする<br>そのセクションがソースのどの位置から始まるのかがわかる</td></tr>
608: <tr><th>section</th><td>セクション番号をファイル名とする。<br>例えば1.2.3というセクションなら1-2-3がファイル名となる</td></tr>
609: <tr><th>serial</th><td>1から始まる5桁の通し番号をファイル名とする</td></tr>
610: </table>
611: <br>
612: デフォルトでは "section" である。
613: </p>
614:
615: <p>
616: @begintext
617: 例:
618: @push filename-rule serial
619: @push filename-prefix help
620: @push filename-suffix .htm
621:
622: とすると、生成されるファイルは
623:
624: help00001.htm
625: help00002.htm
626: help00003.htm
627: ...
628:
629: となる。
630: @endtext
631: </p>
632: @end ;;
633:
634: @section "include-* - @include命令用の緒設定"
635: <p>
636: @push include-header "HEAD"<br>
637: <br>
638: は、
639: @refer "@include" "@include命令"
640: および
641: @refer "@files" "@files命令"
642: によりファイルの内容が挿入される直前に置かれるヘッダをHEADに設定する。<br>
643: たとえば、@push include-header "<p>" などとする。
644: </p>
645:
646: <p>
647: @push include-footer "FOOT"<br>
648: <br>
649: は、
650: @refer "@include" "@include命令"
651: および
652: @refer "@files" "@files命令"
653: によりファイルの内容が挿入された直後に置かれるフッタをFOOTに設定する。<br>
654: たとえば、上記のヘッダであれば、必然的に@push include-footer "</p>" となるだろう。
655: </p>
656:
657: <p>
658: @push include-filter "CMD"<br>
659: <br>
660: は、
661: @refer "@include" "@include命令"
662: および
663: @refer "@files" "@files命令"
664: によりファイルの内容がインクルードされる際、ファイルを直接読むのではなくフィルタプログラムを間にはさみたい場合に、それを実現するシェルコマンドをCMDに指定する。<br>
665: ezhtはその<b>シェルコマンドからの標準出力を、あたかも指定されたファイルを直接読み込んでいるかのように扱う</b>。<br>
666: <br>
667: たとえば、バイナリファイルの先頭部分のダンプ表示を取り込みたい場合、UNIX系であればhexdumpとheadとをパイプで繋いで<br>
668: @push include-filter (hexdump %file% | head) <br>
669: などとすればよい。ここで、シンボル <b>%file%</b> はezhtによりインクルードファイル名に自動的に置換されるもので、必ず記述されなければならない。
670: </p>
671:
672: <p>
673: @relate include
674: </p>
675: @end ;; include-*
676:
677: @section "tab-spaces - タブの取り扱い"
678: <p>
679: @push tab-spaces N<br>
680: <br>
681: は、
682: @refer "@include" "@include命令"
683: または
684: @refer "@files" "@files命令"
685: によって、プレーンテキスト(もしくは番号付きテキスト)としてファイルが取込まれる際に、タブコードがN個のスペース(&nbsp;)に変換されることを約束する。<br>
686: デフォルトでは 8 である。<br>
687: <br>
688: @relate include
689:
690: </p>
691: @end ;; タブの扱い
692:
693:
694: @end ;; スタック一覧
695: @end ;; @push
696:
697: @section "@pop - スタックから値をポップ"
698: <p>
699: @begintext
700: @pop命令はスタックから現在の値をポップする。
701: 書式は以下の通り
702:
703: @pop stack [stack [stack [...]]]
704:
705: この命令は少なくとも1つのスタック名を要求する。
706: 複数のスタックからポップしたい場合には、それぞれのスタック名を複数渡せばよい。
707:
708: 対象となるスタックに値が積まれていない状態(デフォルトの状態)でポップを試みるとエラーが発生する。
709: @endtext
710: </p>
711: <p>
712: @relate stack
713: </p>
714: @end ;; @pop
715:
716: @section "@include - ファイルのインクルード"
717: @mark "@include"
718: <p>
719: @begintext
720: @include命令は、指定されたファイルを指定された形式でインクルードする。
721:
722: 書式は以下の通り
723:
724: @include fname [style]
725:
726: ここで、fnameはインクルードされるファイル名、第二引数styleは任意でインクルード形式を指定する。
727: styleの意味は下表の通りである。
728: @endtext
729:
730: <table border=1 cellspacing=4>
731: <tr><th>インクルード形式</th><th>挙動</th></tr>
732: <tr><th>無指定(デフォルト)</th><td>ファイルの内容をそのままインクルードする。<br>インクルードされた内容は、それが<b>もとからそこにあったかのように</b>処理される。</td></tr>
733: <tr><th>html</th><td>ファイルの内容はすべてHTMLで記述された文書の一部であるとしてインクルードする。<br>行頭の@は&#64;に、行頭の;は&#59;に変換されて取込まれる。</td></tr>
734: <tr><th>text</th><td>ファイルの内容をプレーンテキストとして取り込む。<br>行頭の@は&#64;、行頭の;は&#59;に変換され、HTMLにおける特殊文字はエスケープされ、改行は<br>に置換される</td></tr>
735: <tr><th>numbered</th><td>上記text同様ファイルの内容をプレーンテキストとして取り込むことに加え、行頭に行番号を自動的に振る。<br>行番号は、全体で統一されるよう桁揃いがなされる。(等幅フォントの場合)<br>ソースコードなどを表示させる場合に便利である。</td></tr>
736: </table>
737: </p>
738:
739: <p>
740: @relate include
741: </p>
742:
743: <p>
744: <b>インクルードの実例:</b><br>
745: 例えば、以下のようなファイル(include_source.inc)があったとし、それに対し各種インクルード方法を適用した例を示す。
746: </p>
747: <p class="DISP">
748: <b>include_sources.inc</b> の内容:<br>
749: @include included_source.inc text
750: </p>
751:
752: <p class="DISP">
753: <b>@include include_source.inc</b> の結果:<br>
754: @include included_source.inc
755: </p>
756:
757: <p class="DISP">
758: <b>@include include_source.inc html</b> の結果:<br>
759: @include included_source.inc html
760: </p>
761:
762: <p class="DISP">
763: <b>@include include_source.inc text</b> の結果:<br>
764: @include included_source.inc text
765: </p>
766:
767: <p class="DISP">
768: <b>@include include_source.inc numbered</b> の結果:<br>
769: @include included_source.inc numbered
770: </p>
771:
772: @end ;;@include
773:
774: @section "@begintext - プレーンテキストの埋め込み"
775: <p>
776: @begintext
777: 文字の装飾もなく、使われるタグといえば改行の<br>だけという場合は多い。
778: このような場合、@begintext命令を使うとプレーンテキストを(HTMLに従った形で)そのまま埋め込むことができる。
779:
780: この命令は以下の書式に従う。
781:
782: @begintext
783: プレーンテキスト
784: @endtext
785:
786: @endtext<br>
787: <br>
788: @endtextで始まる行が現れれば@begintext命令は終了する。<br>
789:
790: @begintext
791: なお、プレーンテキスト中に@で始まる命令があっても、それは命令とは認識されない。同様に、;;で始まる行もコメントとはみなされない。
792: プレーンテキストは、いくつかの特殊文字(& " < >など)が&などのように変換され、改行は自動的に<br>タグに置換される。
793:
794: @endtext
795: </p>
796: @end ;; @begintext
797:
798: @section "@refer - @mark命令で登録された参照先へのリンクの生成"
799: @mark "@refer"
800: <p>
801: @refer命令は、
802: @refer "@mark" "@mark命令"
803: で登録された参照先へのリンクを生成する。<br>
804: @begintext
805:
806: 書式は以下の通り
807:
808: @refer "IDENT" "ANC"
809:
810: ここで、IDENTは@mark命令で参照先を登録した際の識別子、ANCはアンカーである。
811:
812: @endtext
813: @relate refer_mark
814: </p>
815: @end
816:
817: @section "@files - 一連のファイルをプレーンテキストとして取込み個別にセクションを生成"
818: @mark "@files"
819: <p>
820: @files命令は、
821: @refer "@include" "@include命令"
822: を拡張したものである。<br>
823: @begintext
824:
825: 書式は、下記に従う。
826:
827: @files MODE DIR PTN [PTN [PTN [PTN...]]]
828:
829: ここで、MODEは text あるいは numbered の何れかである。
830: @endtext
831: インクルードのモードに付いて詳しくは
832: @refer "@include" "@include命令"
833: を参照していただきたい。
834: @begintext
835: 次に、DIRはインクルードされるファイル(群)の基準ディレクトリで、カレントディレクトリからの相対パスあるいは絶対パスとして指定する。
836: 第3引数以降のPTNには、インクルードファイルを好きなだけ指定できる。ここで、PTNには*および?を使ったワイルドカード形式の記述が可能である。
837: これらの指定されたパターンから全てのマッチするファイル名が検索され、さらにそれらは昇順にソートされ、概念的には次の形式の命令群に置き換わる。
838:
839: @endtext
840: <table bgcolor="wheat"><tr><td>
841: @section 一致したファイル名1<br>
842: @include MODE DIR/一致したファイル名1<br>
843: @end<br>
844: <br>
845: @section 一致したファイル名2<br>
846: @include MODE DIR/一致したファイル名2<br>
847: @end<br>
848: <br>
849: @section 一致したファイル名3<br>
850: @include MODE DIR/一致したファイル名3<br>
851: @end<br>
852: <br>
853: ...
854: </td></tr></table>
855: <br>
856: <br>
857: @relate include
858: </p>
859: @end ;; @files
860:
861: @section "@jump - インクルードされたテキストの指定された行へのジャンプ"
862: <p>
863: @begintext
864: @jump命令は、@include命令もしくは@files命令によってプレーンテキストもしくは行番号付きプレーンテキストとしてインクルードされたテキストに対し、そのテキストの指定された行へのリンクを生成する。
865: 書式は以下の通り。
866:
867: @jump FNAME LINE ANC
868:
869: ここで、FNAMEは対象となるインクルードファイルのファイル名(相対パス)である。
870: LINEはジャンプ先となる行番号で、先頭行を1とする。
871: ANCはアンカーである。
872: @endtext
873: </p>
874: <p>
875: 例えば、<br><br>
876: <table bgcolor="wheat"><tr><td>
877: @include jump.inc text
878: </tr></td></table>
879: <br>
880: というコードを記述すれば、次のように生成されることになる。<br>
881: <br>
882: <table bgcolor="wheat"><tr><td>
883: @include jump.inc
884: </td></tr></table>
885: </p>
886: <p>
887: なお、同一のファイルが複数の個所でインクルードされている場合には、現在のバージョンのezhtでは<b>最後にインクルードされた個所</b>へのリンクを生成する。
888: </p>
889: <p>
890: @relate include
891: </p>
892: @end ;; @jump
893:
894: @section "@image - <img 〜>の自動生成"
895: <p>
896: @begintext
897: @imageコマンドは、(可能であれば)引数として取られた画像ファイルから縦幅と横幅を取得し、imgタグのwidth属性とheight属性を自動的に記述する。
898:
899: この命令は、以下の書式に従う
900:
901: @image file [attrs]
902:
903: ここで、fileは画像ファイル名である。
904: fileがオープン可能で且つezhtで認識できる画像形式である場合に限り、縦幅と横幅の取得が行われる。認識可能な画像形式は、現在のところ、PNGとGIFと標準(JFIF)のJPEGである。
905: fileがオープンできない、または認識できない画像形式である場合には、ezhtは警告を発する。
906:
907: 第2引数のattrsは任意である。必要であれば、imgタグの属性群を指定する。例えば、
908:
909: @image logo.png (border="0" hspace="4" vspace="4")
910:
911: とすると、@image命令は(logo.pngがサイズ88x31だと仮定して)以下のような記述に置換されることになる。
912:
913: <img src="logo.png" width="88" height="31" border="0" hspace="4" vspace="4">
914:
915: @endtext
916: </p>
917: @end ;; @image
918:
919: @section "@section - セクションの記述" joined
920: <p>
921: @begintext
922: 新しいセクションを開始するには、@section命令を用いる。
923: 命令の書式は以下の通り
924:
925: @section name [joint_attr]
926: 内容
927: @end
928:
929: ここで、nameはセクションの名称つまりセクションのタイトルとなる文字列である。
930: joint_attrは任意の引数で、当該セクションの子セクションに対する結合属性である。
931: 結合属性joint_attrは、下表の意味を持つ。
932:
933: @endtext
934:
935: <table border="1" cellspacing="2">
936: <tr><th>結合属性</th><th>挙動</th></tr>
937: <tr><th>無指定</th><td>結合属性は親セクションの結合属性を継承する。<br>当該セクションが親を持たない、つまり最上位のセクションの場合は、結合属性は暗黙に<b>disjoined</b>が指定されたとみなされ、セクションの内容は個別ファイルに格納される。</b><br>親セクションが存在し、その結合属性が<b>joined</b>であれば、当該セクションは親セクションと同一ファイルに格納される。</td></tr>
938: <tr><th>disjoined</th><td>親セクションの結合属性また親の存在ににかかわらず、当該セクションは個別ファイルに格納される。<br>当該セクションの<b>子セクションもまた個別ファイルに格納</b>される。</td></tr>
939: <tr><th>joined</th><td>親セクションの結合属性また親の存在ににかかわらず、当該セクションは個別ファイルに格納される。<br>当該セクションの子セクションの結合属性が無指定の場合、子セクションは当該セクションと同一のファイルに格納</b>される。</td></tr>
940: </table>
941:
942: <br>
943: 子セクションを作るには、単に@section命令をネストさせればよい。<br>
944: 例えば、「性別」というセクションの下に「男性」と「女性」という2つの子セクションを作るには、<br>
945: <br>
946:
947: <table bgcolor="tan">
948: <tr><td>
949: @begintext
950: @section "性別"
951: 性別に関する内容をここに記述
952:
953: @section "男性"
954: 男性に関する内容をここに記述
955: @end ;; セクション「男性」の終了
956:
957: @section "女性"
958: 女性に関する内容をここに記述
959: @end ;; セクション「女性」の終了
960:
961: @end ;; セクション「性別」の終了
962: @endtext
963: </td></tr>
964: </table>
965: <br>
966: とすればよい。<br>
967: <br>
968: @relate "sec_disjoined"
969: @relate "section"
970: </p>
971:
972:
973:
974: @section "セクション内のみで使える命令群" joined
975:
976: <p>
977:
978: @section〜@endで記述されるセクション内でのみ使用できるいくつかの命令がある。<br>
979: これらはセクション外で使うことはできない。<br>
980: <br>
981: @index
982: <br>
983: @relate "section"
984: </p>
985:
986: @section "@index - 当該セクション下の索引を挿入"
987: <p>
988: @begintext
989: @index命令は、当該セクションの子セクションに対する索引(Index)を挿入する。
990: 子セクションに子セクションがあれば、つまりネストされていれば、ネストされている分だけ全深度に渡った索引が挿入される。
991:
992: 書式は以下の通り
993:
994: @index
995:
996: この命令は引数を取らない
997: @endtext
998: </p>
999: @end ;; @index
1000:
1001: @section "@mark - 参照先の登録"
1002: @mark "@mark"
1003: <p>
1004: @mark命令は、
1005: @refer "@refer" "@refer命令"
1006: で生成されるリンクの参照先を登録する。<br>
1007: @begintext
1008:
1009: 書式は次の通り
1010:
1011: @mark "IDENT" [OPT]
1012:
1013: ここで、IDENTはユニークな識別子である。
1014: OPTは無指定もしくはhereを指定する。hereが指定された場合、参照先は@mark命令の現れたその場所、無指定の場合の参照先は、@mark命令が現れたセクションの先頭となる。
1015:
1016: @endtext
1017: @relate refer_mark
1018: </p>
1019: @end
1020:
1021: @section "@relate - セクション間の相互・単一の関連をリンクさせる"
1022: <p>
1023: @begintext
1024: @relate命令は、セクション間に相互に関連がある場合、あるいは別のセクションへの単一(非相互)の関連がある場合に使用される。
1025: この命令はセクション間の関連に基づき、関連あるセクションへのリンク(群)に置き換わる。
1026:
1027: まず、相互に関連のある場合には、
1028: @relate "IDENT"
1029: とする。
1030: ここで、IDENTは相互に関連するセクションで共通に使われる任意の識別子である。
1031: 例えば、セクションA,B,Cの3つのセクションが、@relate命令に識別子"computer"を渡した場合、セクションAからはB,Cへ、セクションBからはA,Cへ、セクションCからはA,Bへのリンクが張られることになる。
1032:
1033: 次に、相互ではなく当該セクションから単一の関連、つまり単に参照したいだけの場合、
1034: @relate "IDENT" refer
1035: とし、第二引数にオプションのreferを渡す。
1036: 上の例の続きで説明すれば、セクションDが
1037: @relate "computer" refer
1038: と識別子"computer"であらわされる関連先を指定した場合、セクションDからは、セクションA,B,Cへのリンクが張られる。
1039: 相互の関連ではないため、セクションA,B,CからはセクションDへのリンクは張られない。
1040:
1041: @endtext
1042: </p>
1043: <p>
1044: @relate reference
1045: </p>
1046: @end ;; @relate
1047:
1048: @section "@autopop - セクション終了時のスタック一斉ポップ"
1049: <p>
1050: @begintext
1051: @autopop命令は、当該セクションが終了した際に自動的にポップされるスタック(群)を設定する。
1052: 設定されたスタック(群)は、当該セクションの終端でポップされる。
1053:
1054: 書式は以下の通り
1055:
1056: @autopop stack [stack [stack [...]]]
1057:
1058: この命令は少なくとも1つの引数が必要である。stackにはスタック名を指定し、複数あればその分だけ引数として渡す。
1059: 例えば、A,B,Cの3つのスタックを当該セクションの終端でポップさせたければ、
1060: @autopop A B C
1061: とすればよい。
1062:
1063: @endtext
1064: </p>
1065: <p>
1066: @relate stack
1067: </p>
1068: @end ;; @autopop
1069:
1070:
1071: @end ;; セクション内の命令群
1072:
1073: @end ;; @section
1074:
1075:
1076: @end ;; コマンド一覧
1077:
1078: @end ;; 書式
1079:
1080:
1081: @section "本ドキュメントのソース"
1082: @mark source
1083: <p>
1084: 本ドキュメントは、以下のソース(ezht_help.in)から生成されたものです。<br>
1085: この種のツールは、ドキュメントを読むよりもソースと生成物を見比べるほうがずっと早く理解できるものです。
1086: このソース(ezht_help.in)を適当なディレクトリにコピーし、いろいろといじくりまわしてezhtの挙動を確認してみてください。
1087: </p>
1088:
1089: @relate doc_source
1090:
1091: <p class="DISP">
1092: <b>ezht_help.in:</b><br>
1093: @include "ezht_help.in" numbered
1094: </p>
1095: @end ;; 本ドキュメントのソース
1096:
1097: @section "開発者向け"
1098: <p>
1099: @index
1100: </p>
1101:
1102: @section "ezhtのソースコード" disjoined
1103: @push include-filter (nkf -Es %file%) ;;ソースコードで使われている日本語コードはEUCなのでSJISに変換させる
1104: @push include-header (<p class="DISP2">)
1105: @push include-footer (</p>)
1106: @autopop include-filter include-header include-footer
1107: @files numbered ../src *.cc *.h
1108: @end ;; ezhtのソースコード
1109: @end ;; 開発者向け