はるか昔、太古の時代には、顧客への納入ドキュメントは手書きでした。
仕様変更など出ようものなら、ホワイトで消して書き直します。
プログラムを直すより遥かに手がかかります。
仕様変更が嫌いな、最大の理由です(^_^;
恐竜が絶滅した頃、ワードプロセッサという新しい種が現れました。
めっちゃ便利でしたが、やはり紙に出力して納品するので、手書きの頃より遥かにページ数が増えました。
もう殆ど、ファイル何冊納品するかを他社と競っていたようなものです。
仕様変更など出ようものなら、全ページ出力し直して、全ページにページ数をスタンプして、穴を開けて綴じます。
プログラムを直すより遥かに手がかかります。
仕様変更が嫌いな、最大の理由です(^_^;
人類が出現した頃、顧客側でもワープロやスプレッドシートを表示することができるようになり、紙での納品は無くなりました。
しかし、ワープロやスプレッドシートで作成したファイルは、基本的に差分が取れないためバージョン管理がしにくい（できない）という、致命的な欠点があります。
そのせいで、変更履歴をコツコツと作成する羽目になります（電子データを使っているにもかかわらずです）。
プログラムを直すより遥かに手がかかります。
仕様変更が嫌いな、最大の理由です(^_^;
そして、やっと最近になって（今更？）PDFでの納入ができるようになりました。
PDFでも、差分が取れないことは変わりませんが、なんと言っても、いろいろなソースから比較的きれいなPDFが作成できます。
特に、HTMLで作成したコンテンツからWebブラウザで（印刷処理で）簡単にPDFが出力できるようになったのは、非常に嬉しいところです。
HTMLはテキストなので、簡単に差分がとれます。
それに、JavaScriptという強力な手段があるので、編集をサポートする機能を簡単に実現できます。
このコンテンツは、できるだけ編集内容を簡潔にして、ページ単位のドキュメントを作成ことを目的としています。
ツールの使用方法を説明している体裁ですが、ソースを見ていただければ多分何をやっているか理解できると思います。
興味があれば、参考にしてください。
下記は、そのソースです。
body要素の直下をsection要素とし、その中にドキュメントの内容を記述します。
クラス属性に、break_alwaysを記述すると、その直後直前で改ページを行います。
改ページの指示が無い場合、section要素に指定されたページサイズに合わせて改ページを行います。
下記が、ヘッダ部でスクリプトとスタイルシートをロードしている箇所です。
必要な処理は、jsdoc.jsの中で全て行うため、ロード以外の処理は不要です。
但し、com.yscjp.jsapp.JsAutoLoaderでロードしている場合は、window.addEventListener("load", com.yscjp.jsapp.jsdoc.init);が必要となります。
h2要素とh3要素に項番を付与し、それ以降の要素をインデントさせます。
h2要素の項番は、コンテンツ内で１から順にカウントアップしたものを付与します。
h3要素の項番は、h2要素の出現毎に１から順にカウントアップしたものを付与します。
h2要素の項番を、１以外から始める場合は、jsdoc.jsロード後に下記の様に設定してください。下記例では、項番を4から始めます。
インデントは、デフォルトではh2要素の後に出現する要素の左側の開始位置を6mm右に移動し、h3要素の後に出現する要素の左側の開始位置を12mm右に移動させます。
デフォルト値は、下記のように定義されているので、これを書き換えることで変更することが出来ます。
単位（indentUnit）は、CSSに設定できる単位を指定してください。
変更を行う箇所は、上記の項番の初期値を変更するケースと同じです。
クラス属性にpageが指定されているsection要素が、ページの単位となります。
この要素に指定されているCSSの内容から、１ページに表示可能なサイズ（ピクセル単位）を取得して、自動改ページを行います。
デフォルトは、高さが297mm、幅が210mmのA4縦で、余白が上20mm、下10mm、左右が15mmとなっています。
変更する場合は、jsdoc.cssのロード後に、section要素のパッディングを変更してください。
当ドキュメントでは、下記設定で下の余白を15mmに変更しています。
改ページしたページ数に基づいて、ページ番号を付与します。
ページ番号は、以下のようなCSSの定義がなされています。位置の変更などは、jsdoc.cssのロード後にCSSの定義を再設定してください。
このドキュメントの上部と下部に太い線が表示され、上部には当社のドメインが表示されていると思います。
このような、ヘッダとフッタを各ページに表示する機能です。
ヘッダとフッタは、下記のようにsectionの外に、com_yscjp_jsapp_jsdoc_header（ヘッダの場合）かcom_yscjp_jsapp_jsdoc_footer（フッタの場合）をIDに指定し、記述します。
これらのIDが指定されている要素は、非表示となります。
ヘッダやフッタは、上下に固定する様にスタイルシートで指定されています。positionは必ずabsoluteのままとしてください。
このドキュメントのヘッダとフッタのスタイルは、以下のように指定されています。
横幅は、デフォルトで画面いっぱい（width: 100%）となっているので、コンテンツの幅に合わせる場合は、widthに絶対値を指定する必要があります。
テーブルの先頭列に、自動的に項番を振る機能です。
table要素のクラス属性にitem_numberを指定することで、項番を振ることができます。
| 項番 | 項目１ | 項目２ | 項目３ | 備考 |
|---|---|---|---|---|
| 01234 | 4567 | A | ||
| 01234 | 4567 | B | ||
| 01234 | 4567 | C |
caption要素とfigcaption要素の内容に、それぞれ表n.や図n.を付与する機能です。nの部分は、1から始まり、ドキュメント全体でカウントアップされる数字です。
| abcdef | 01234 | 4567 | |
| ghijkl | 56789 | **** |
上記とか上記のように、table要素やfigure要素のIDを指定して、図表番を文章中に埋め込むことも出来ます。
指定例は、以下のとおりです。
data-com_yscjp_targetIdに指定しているのは、caption要素やfigcaption要素の親要素のIDです。通常はそれぞれtable要素とfigure要素となる筈ですが、構成が異なる場合は注意してください。
h2h3h4各要素の直前以外での改ページを抑止する機能です。
各ページの先頭が、必ず何らかのタイトルとなります。
サンプルをご覧ください。タイトル以外での改ページを抑止しないケースと、抑止するケースです。内容は同じです。
抑止するサンプルの方は、各ページの先頭がタイトルになっていると思います。
但し、4/5ページの『4-2. 節のタイトル』の後ろは、タイトル以外の箇所で改ページしています。
『4-2. 節のタイトル』は、そもそも１ページには入り切らないサイズなので、後ろの10行には必要に応じて改ページする指定がされています。
改ページを抑止するコードは以下の通りです。
必要に応じて改ページを行う指定は以下の通り。
要素のクラスにbreak_autoを指定すると、必要に応じてその要素の直前で改ページされるようになります。
section要素の子要素には、CSSのpositionに、absoluteやfixedは指定できません。
指定した場合、正しく表示されなくなります。
テーブルの幅に100%を指定すると、正しく表示されません。
横幅いっぱいにテーブルを表示する場合は、クラス属性にh2_table又はh3_tableを指定してください。
| サンプルの表 | 備考 |
| 横幅いっぱいに表示する | 備考 |
h2要素と同じネストに表示するテーブルの場合はh2_table、h3要素と同じネストに表示するテーブルの場合はh3_tableとなります。
上記テーブルは、class="h3_table"が指定されています。
h2_tableやh3_tableの定義内容は、デフォルトの文字サイズやインデントサイズを変更しない前提のものです。デフォルトから変更した場合は、適宜定義し直してください。
jsdoc.jsは、内部でwindowのloadイベントにハンドラを設定して、処理を呼び出しています。
jsdoc.jsの実行が終了した後に、要素のサイズやDOMの構成が変更された場合、インデントや自動ページ替えの結果が正しく表示されない可能性があります。
要素のサイズやDOMの構成が変更されるような処理は、jsdoc.jsの実行前に処理が終了するようにしてください。
タイトル以外での改ページを抑止しない（デフォルト）の状態では、ページの一番下にテーブルが来た場合、正しく自動改ページされない場合があります。
そのような場合は、break_alwaysで強制的に改ページさせるか、テーブル要素を他の要素（divなど）でラップしてください。
どう見ても、スマホ対応できそうですよね。
目次とかを自動で作成することも、それほど難しくはないのですが、あまり必要性を感じないというか...
更新履歴とかは、やっぱり欲しいかな。
テーブルのwidth: 100%;とかには、なんとか対応したいのですが、どうすればよいのか今の所不明。
ページ単位での表示と、通常のWeb形式での表示を簡単に切り替えるようなインターフェイスの追加。
ページ番号や、各タイトルの前に付与する項番の編集箇所を切り出して、簡単にオーバーライドできるようにする。
ちなみに、このドキュメントをPDFに出力したものです。
できるだけ簡単に、ページ単位のドキュメントを作成する.pdf...
多少罫線が太くなってしまうのと、日本語フォントのレンダリングが余りきれいでないのが気に入らないのですが、まあまあ見られる程度の物が簡単に出力できるようになりました。
このコンテンツで使用しているスクリプトなどは、下記からダウンロードしてください。但し、最新ではない可能性があります（最新すぎる可能性もあります）。