L
A
TEX
ドキュメントの記述方法
ver. 0.91
日高 隆博
1997
年 8 月 23 日
1
はじめに
Sapidプロジェクトにおいて，ドキュメントのソースは LATEX を用いて記述され，HTML に変換される． この文章では，HTML 変換に対応した LATEX ソースの記述のための規約について説明する．2
L
ATEX
ファイルの記述
2.1
ヘッダの記述
Sapidで用いる LATEX のファイルでは，先頭で必ず\input{common.tex} として共通の定義ファイルを読
み込む．ここで documentstyle も定義されている．
次に，\title,\author, \date, \begin{document} をこの順番に定義し，\maketitle を呼び出す．
2.2
使用可能な L
ATEX 命令
本文の記述には，表 1 の記述を利用できる．これらの記述は適切に反映されると考えてよい．
\title, \author, \date, \appendix, \input, \maketitle, \footnote, \tableofcontentsも適 切に変換される．また，\def についてはごく単純な置き換えを行なうマクロについては利用することがで きる． 表 2 のコマンドについては，HTML では無視される可能性を考慮に入れておく必要がある．
2.3
使用に制限のある L
ATEX 命令
minipage環境は無視される．しかし，現在のところ 1. 2段組にするため 2. 改ページを避けるため 3. 表の中で長い文章を書くため などの限られた用途にしか minipage 環境は使われていないので，特に問題はないと考えられる． tabular環境に関しては，以下の制限に従う． 1. tabular内の全ての要素に対して罫線が引かれているものは問題なく利用できる．すなわち， • tabular の書式指定で項目間に全て罫線が指定されている • 各行には\hline がある表 1: 使用可能な LATEX 命令 LATEX HTML 環境 document <html> itemize <ul> enumerate <ol> description <dl> verbatim <pre> center <center> figure <center> table <center> quote <blockquote> マクロ \section <h1> \subsection <h2> \subsubsection <h3> \paragraph <h4> \item <li> or <dd> \verb <pre> \epsfile <img> \ref <a href> \label <a name> \bibitem <a name>
表 2: 無視されることもある LATEX 命令 LATEX HTML フォント \rm 無視 \bf <b> \it <i> \sl <i> \sf 無視 \tt <tt> \sc 無視 \dm 無視 \dg <b> フォントサイズ \tiny <font size=1>
\scriptsize <font size=1> \footnotesize <font size=2> \small <font size=2> \normalsize <font size=3> \large <font size=4> \Large <font size=5> \huge <font size=6> \Huge <font size=7>
ものである． 2. また，逆に罫線が全くない表も利用して構わない．これはテキストを配置する際に利用できる． これ以外の表は，通常の表の組合せで実現できるものが多いはずなので，できるだけ組み合わせで表現す るが，HTML に変換する際には上記のいずれかに変換されるので注意が必要である．ただし，型定義の仕 様書，およびクラス仕様書については，それぞれ専用の環境を用意してあるので，それを用いることで複雑 な表を表現することができる．
2.4
使用できない L
ATEX 命令
空白制御やサイズ指定，ページ指定などの，LATEX および紙への印刷に強く依存した命令は使用できな い．これらの命令は基本的に無視される． また，それ以外の命令でも，tabbing 環境, list 環境，数式関係については現在のところサポートされ ていない．3
拡張された
L
ATEX
コマンド
3.1
リンクの記述方法
LATEX で用意された\label と\ref による参照と同様に，\SapidGlobalLabel{label},
\SapidGlobalRef{ref} という記述が利用できる．このラベルはドキュメント間で共有されるので，複数 のドキュメントの間にリンクを張ることができる．ただし，\section, \caption などのパラメータには記
表 3: フォント指定 マクロ LATEX 用途 \SapidVarFont \tt 変数名 \SapidFuncFont \sl 関数名 \SapidTypeFont \it 型名 \SapidValueFont \tt 定数値 (マクロ) \SapidClassFont \bf クラス名 \SapidFileFont \tt ファイル名 \SapidLibraryFont \tt ライブラリ名 \SapidCommandFont \tt コマンド名 \SapidCodeFont \tt その他ソースコード類 述することができないので注意が必要である． Sapidのドキュメントで頻出する単語である下記のようなものについては
Sapid, AR, AR3, AR4, sdb3, SDB3, sdb4, SDB4, pidb, PIDB, SDA, SDA2, mkSpec3, mk-Spec4, sat, SBR, SpdStr, emacs-appli, SaQuLa, SaTuKi, sdv, xsda, xsda2 sip, SIP, xsip, I-model, C-model, P-model, CFG, DFG
\SapidGlobalLabelによってラベルをつけて\SapidGlobalRef によって参照できるようにすることが 強く推奨される． また，3.4 節で説明する定義類の環境においては，\SapidGlobalLabel がマクロ中で自動的に記述され るので，それらに含まれるものについては\SapidGlobalLabel を明示的に記述しなくても良い．
3.2
フォント
ドキュメント中に用いられる様々な要素についてフォントを統一するため，表 3 のマクロを用意した．3.3
フォントとリンクの記述
3.2節のフォントの記述は，リンクとともに用いられることが多いので，表 4 のような記述を用意した． これらのマクロは通常は 1 つの引数を取り，その引数と同じ名前のラベルへのリンクに展開される．ただ し，オプション引数としてラベル名が指定されている場合には，そのラベルへのリンクに展開される．ま た，リンクを生成したくない場合のために，各マクロ名の Ref の部分を NoRef に置き換えた名前のマクロ も用意されている． また，それぞれの要素についてリンクを生成するかどうかには偏りがあるため，Ref/NoRef を省略した 名前のマクロも，表 5 のように用意されている． さらに，\SapidGlobalFileRef[filename]{...} コマンドによって，特定のファイルへのリンクを作成可 能 で あ る1．ま た ，\SapidFileNameFileRef[filename]{string} と 記 述 す る こ と で {\SapidFileFont \SapidGlobalFileRef[filename]{string}} を短縮して記述できる． 1この仕様は暫定的なものである．表 4: リンクつきフォント指定 リンクつき リンクなし \SapidVarNameRef[label]{...} \SapidVarNameNoRef[label]{...} \SapidFuncNameRef[label]{...} \SapidFuncNameNoRef[label]{...} \SapidTypeNameRef[label]{...} \SapidTypeNameNoRef[label]{...} \SapidValueRef[label]{...} \SapidValueNoRef[label]{...} \SapidClassNameRef[label]{...} \SapidClassNameNoRef[label]{...} \SapidFileNameRef[label]{...} \SapidFileNameNoRef[label]{...} \SapidLibraryNameRef[label]{...} \SapidLibraryNameNoRef[label]{...} \SapidCommandNameRef[label]{...} \SapidCommandNameNoRef[label]{...} \SapidCodeRef[label]{...} \SapidCodeNoRef[label]{...} 表 5: リンクつきフォント指定のデフォルト マクロ 展開結果 \SapidAttrName[label]{...} \SapidAttrNameNoRef[label]{...} \SapidVarName[label]{...} \SapidVarNameNoRef[label]{...} \SapidValue[label]{...} \SapidValueNoRef[label]{...} \SapidFileName[label]{...} \SapidFileNameNoRef[label]{...} \SapidCode[label]{...} \SapidCodeNoRef[label]{...} \SapidClassName[label]{...} \SapidClassNameRef[label]{...} \SapidFuncName[label]{...} \SapidFuncNameRef[label]{...} \SapidTypeName[label]{...} \SapidTypeNameRef[label]{...} \SapidLibraryName[label]{...} \SapidLibraryNameRef[label]{...} \SapidCommandName[label]{...} \SapidCommandNameRef[label]{...}
3.4
Sapid
依存の定義の記述
Sapidのドキュメントでよく用いられている • クラス定義 (I-model 仕様書など) • 型定義 (AR 仕様書など) • 関数定義 (AR 仕様書など) • コマンドマニュアル • ソースコード これらは環境として記述する．これらはよく使われるので，LATEX/HTML それぞれのテンプレートを用 意して，適切に表示できるようにするためのものである． また，以下のコマンドのうち，オプション引数として label を指定できるものについては，それぞれ省略 しても暗黙の生成される．他からリンクを生成したくない場合には [*NOREF*] と記述することで回避で きる． 3.4.1 クラス定義 クラス定義は， \begin{SapidClassDefList} : \end{SapidClassDefList} と記述する．この環境の中には，以下の 2 つのいずれかのクラス定義の要素を記述することができる． ヘッダファイルが不必要なクラス \begin{SapidClassDef}[label]{classname}{description} \SapidClassAttrItem{attrname}{attrtype}{description} : \end{SapidClassDef} ヘッダファイルが必要なクラス \begin{SapidClassDefWithHeader}[label]{classname}{description}{headerfilename} \SapidClassAttrItem{attrname}{attrtype}{description} : \end{SapidClassDef} また，属性が列挙型属性の場合\SapidClassAttrItem の代わりに \SapidClassEnumAttr{attrname}{attrtype}{description}{enumdescription} \SapidClassEnumAttrItem{enumerator}{description} : \SapidClassEnumAttrEnd と記述することができる．3.4.2 型定義 型定義については，2 種類の記述が存在する． まず，1 つめは，比較的短い記述の場合に用いることができる記述で， \begin{SapidTypeDefList} : \end{SapidTypeDefList} このように記述する．この環境の中には，以下のような要素を記述することができる． Struct である場合 \begin{SapidTypeDefStruct}[label]{Typename}{Tagname}{description} \SapidTypeStructMember{membertype}{membername}{description} : \end{SapidTypeDef} Enum の場合 \begin{SapidTypeDefEnum}[label]{Typename}{Tagname}{description} \SapidTypeDefEnumMember{membername}{description} : \end{SapidTypeDef} その他の通常の型の場合 \SapidSimpleTypeDefItem[label]{newTypename}{typename}{description} 実装を示したくない場合 \SapidTypeDefOnlyDescription[label]{newTypename}{description} これらは混在させることができる．
また，description については，\SapidDescriptionItem{description}2と記述することで，段落や
他の環境を含む文章を記述することもできる． 2つめの記述方法は，1 つの構造体について複雑な情報を記述したいときに用いることができる記述で， \begin{SapidStructAttrList}{typename} \SapidStructAttrItem{attrType}{attrName}{description} : \end{SapidStructAttrList} と記述する．これは 1 つめの記述方法よりも description を詳しく書くことができる． 2将来的には，環境の第 3 引数の description は無くなる可能性がある．
3.4.3 関数定義 これは，関数プロトタイプとその説明を記述するためのもので， \begin{SapidFuncDef}[label]{FuncType}{FuncName} \SapidFuncArgItem[label]{argtype}{argname}{description} : \SapidDescriptionItem{description} \end{SapidFuncDef}
と記述する．Sapid で定義されている型については，必ず\SapidTypeName{typename} と記述する．ま た，引数をとらない場合には， \begin{SapidFuncDef}[label]{FuncType}{FuncName} \SapidFuncArgVoidItem \end{SapidFuncDef} と記述する． 3.4.4 定数の説明 定数の内容を説明するために， \begin{SapidMacroListWithHeader}{header1}{header2} \SapidMacroItem{macroname}{description} : \end{SapidMacroListWithHeader} もしくは \begin{SapidMacroList} \SapidMacroItem{macroname}{description} : \end{SapidMacroList} と記述することができる． 3.4.5 コマンドマニュアル 以下のような記述が利用できる． \begin{SapidCommandManual} \SapidCommandManualName[label]{name} \SapidCommandManualSynopsis{synopsis} : \SapidCommandManualDescription{...} \SapidCommandManualOptions{...} \SapidCommandManualEnvironment{...} \SapidCommandManualExitStatus{...} \SapidCommandManualFiles{...}
\SapidCommandManualSeeAlso{...} \SapidCommandManualNotes{...} \SapidCommandManualBugs{...} \end{SapidCommandManual} これらの \SapidCommandManual* マクロは，必要なものだけ記述すればよい．また，Synopsis だけは複 数列挙することも可能である． 3.4.6 ソースコード \begin{SapidSource} : \end{SapidSource} で囲んで書く方法と， \SapidSourceInput{filename} で書く方法の 2 種類を用意する．SapidSource 環境は，現状では quote 環境と同様の働きをする．その ため，一般には記号類を適切に表示するために，LATEX のマクロを適切に記述するか，\begin{verbatim} などをさらに内側に記述する必要がある． \SapidSourceInputマクロでは，行番号つきでファイルを読み込み，タイプライタ体で出力する．
3.5
FAQ,BugList
以下のように記述する． FAQ \begin{SapidFAQList} \begin{SapidFAQ} \SapidFAQNo{No.} \SapidFAQQuestion{question} \SapidFAQAnswer{answer} \end{SapidFAQ} : \end{SapidFAQList} BugList \begin{SapidBugList} \begin{SapidBug} \SapidBugNo{No.} \SapidBugDate{date} \SapidBugReporter{reporter} \SapidBugPhenomenon{phenomenon} \SapidBugComment{comment} \SapidBugTarger{target}\SapidBugReason{reason} \SapidBugModifier{modifier} \SapidBugModifyDate{modifydate} \SapidBugStatus{status} \end{SapidBug} : \end{SapidBugList}
3.6
その他
LATEX と HTML との違いを吸収できない場合の最終手段として， \SapidExpandOnlyLaTeX{...} \SapidExpandOnlyHTML{...} \SapidExpandOnlyRawHTML{...} という記述が利用可能である．\SapidExpandOnlyHTML{} と\SapidExpandOnlyRawHTML{} の違いは，前 者のパラメータは LATEX のマクロとして解釈されるのに対して，後者のパラメータは単純に HTML ファイ ルに出力される，という点である． これらは，LATEX と HTML で出力を切り分けたいときにも用いるが，spdMkHtml の制限により，LATEX で変数に値を代入する式 (\var=value の形式の式) は全て\SapidExpandOnlyLaTeX のパラメータ内に記述 する必要がある．4
ラベルの利用方法
3章では，リンクを記述するためのラベルの記述方法について説明した．本章では，ラベル名の規定につ いて説明する．4.1
ラベルをつけるべき位置
ドキュメントを記述する際には，他のドキュメントからのリンクを生成しやすいように，以下のような位 置にラベルをつけることが推奨されている． • ドキュメントそのもの (\maketitle コマンドの直前) • ライブラリについて説明している章 (\section コマンドなどの直後) • その他重要な概念 (SDB,ISDB など) について説明している章 (同上) 特に，ライブラリについて説明している章については，参照しやすいように， 1. サブシステム名 (AR3 など)2. ライブラリ名 (SapidAR3, libSapidAR3, libSapidAR3.a) などの複数の名称のラベルを生成する必要がある．
また，クラス，型，関数，コマンドについては，3.4 節で説明した環境を用いて記述した場合には，それ ぞれラベルが自動的に生成されるが，このときにもサブシステム名などのラベルについては手でつけてお く必要がある．
