FC2ブログ

天地有情

[便利ツール] Doxygen でドキュメントを作成

§1 はじめに

Doxygen(読み:ドキシジェン)は,ソースコードのドキュメンテーションジェネレータです.
自作ライブラリ(C/C++,Fortran,...等々)のドキュメント化にも使えますが,
本稿では,Doxygenで文書を作成するために有益と思われるソースの書き方などをサンプルで示します.

(留意事項)
 「Doxygen」で検索するとインストールの仕方,設定の仕方,使い方などなど多数の情報が得られます.
 本稿では,これらについては割愛させて頂きます.必要最小限の事柄についてのみ説明することとします.

以下に必要と思われる事柄を,あらかじめ箇条書きで列挙しておきます.


■ インストールの要約
  (1)doxygen ソースコードのドキュメントツール
        https://sourceforge.net/projects/doxygen/

  (2)Graphviz dot言語で記述されたグラフの構造を画像ファイルへ出力
        https://graphviz.gitlab.io/_pages/Download/Download_windows.html
        オプションである.graphvizをインストールしてドキュメント作成すると,
        関数やクラス間の関係性を図にしてくれる.

■ 出力成果
  doxygen の出力結果は,HTML形式とLaTex形式である.

■ ユーザ作成ファイルの要約
   ファイルの拡張子は各種プログラミング言語のソースコードを除いて,
   Doxygenに文書として使用されるファイルの拡張子は
   
   .dox
   .md
   
   の2種類である..doxはDoxygen標準の文書ファイルであり,.mdはマークダウンである.


  ちなみに Doxygen はファイル中のコメントを抜き出すというスタイルなので,
  .doxファイルは全体をコメントアウトする.
  要は,最初の行と,最後の行を下記のようにする.C言語風のコメントアウトがおすすめ.

   xxx.doxの書式例
   
   ■■■■■■■■■■■■■■
   /**
   \mainpage タイトル
   \section タイトル
   (本文)
   (本文)
   (本文)
   **/
   ■■■■■■■■■■■■■■
   
   doxファイル1つにつき1つの名前を付ける.
   そういうわけで,各ファイルの先頭では,このdox(md)ファイルが何を表すのか上記のコマンドでタイトルなど
   を宣言する.
   ちなみに,1つのプロジェクトに1つの\mainpageが存在し,\pageはそれにぶら下がるような構造になります.

■ プロジェクト名
  プロジェクト名はデフォルトで 「My Project」 である.設定変更可能である,
  
■ コンパイル方法
  ユーザ作成ファイルのコンパイル方法には2つの方法がある.
  (1) ウイザードによる方法
  (2) コマンドライン操作
  
  本稿のサンプルでは,簡単な(2)のコマンドライン操作で行う.
    コマンドラインで以下を実行する.
    
    ■■■■■■■■■■■■■■
    > doxygen -g    (この操作でDoxyfileが生成される)
      続いて
    > doxygen (あるいは > doxygen Doxyfile)
     これで HTML および LaTeX ディレクトリが生成される.(中身は関連ファイルが格納されている)
    ■■■■■■■■■■■■■■
    
    > doxygen -g はconfiguration fileを作成するためconfiguration fileを変更しない限り
    最初に1回だけ操作する.(configuration fileのデフォルト名は "Doxyfile" である)
    
    > doxygen はユーザ作成ファイルを修正した場合に使うため,修正のたびに操作する.
    

■ 実行方法
  (1) HTMLの場合:
    [html]ディレクトリを開いて,その中にある 「index.html」をクリックするだけである.
    
  (2) LaTeXの場合:
    [LaTeX]ディレクトリを開く.
    ・欧文だけの場合は「make.bat」を起動させるだけである.
    ・和欧文混合の場合は「refman.tex」を修正し,「lualatex」コマンドコンパイルする.
     (後述のサンプルを参照)

■ Ghostscriptについて注意喚起する
  数式表示のため,Ghostscript(32bit)を必要とします.(64bit)ではエラーになる,
  (32bit)であることを確認する.
  
■ ユーザ作成ファイルの文字コード
  .dox や .tex ファイルの文字コードは UTF-8 である.
 
 
〇 My System configuration
-------------------------------
  ・Windows 10
  ・doxygen 1.8.14
  ・Graphviz 2.38
  ・Ghostscript 9.26 (32bit)
-------------------------------

§2 サンプル

次の手順で作業を進めます.

(1)作業環境を作る
   Desktop上に [DoxySample] ディレクトリを作成し,
   ・作成ファイル: DoxySample.dox
   ・コマンドプロセッサ: cmd.exe のショートカット
   を配置します.
   DoxySample.dox は http://hayato1224.web.fc2.com/Doxygen/DoxySample.dox をコピーして(CTRL-A + CTRL-C)
   お手持ちのエディタに転写(CTRL-V)して本ディレクトリに DoxySample.dox の名前で格納します.

doxygen01.png



(2)cmd.exe を開いて,次の操作を行います.
   > doxygen -g
   > doxygen (あるいは doxygen Doxyfile)
   
   操作完了すると,[html] と [latex] ディレクトリが生成されます.

doxygen02.png



(3)[html] ディレクトリ内を確認する
   先ず,tiger.png をコピーしておきます.その後
   > doxygen のみを実行.
   
   次に index.html をクリックすると,次が表示されます.

doxygen03.png


doxygen04.png


doxygen05.png


doxygen06.png


doxygen07.png


doxygen08.png


doxygen09.png


 
  


 
  
(4)[latex] ディレクトリ内を確認する

doxygen10.png


   ・先ず,コマンドプロセッサ cmd.exe のショートカットを配置
   ・IMAGESディレクトリを作成し,その中にtiger.pngを格納します.
   ・その後,
      > doxygen のみを実行.

(5)TeXファイルの修正
   TeXファイルのメインファイルは refman.tex であるが .doxファイルが和欧文のため,
   修正する必要があります.
   
   ================================
   01行目:
     \documentclass[twoside]{ltjsbook} %%%%%%{book}を{ltjsbook}に変更
   23行目:
     %% \usepackage{sectsty} ------------- コメントアウト
   25~28行目:
     %% \allsectionsfont{% ------------- コメントアウト
     %% \fontseries{bc}\selectfont ------ コメントアウト
     %% \color{darkgray}% --------------- コメントアウト
     %% } --------------------------------- コメントアウト
   146行目:
     %% \backmatter ----------------------- コメントアウト
   ================================
     

(6)コマンドプロセッサ cmd.exe から次の操作を行います.
      > luajitlatex refman.tex
      > luajitlatex refman.tex
      (続けて2回コンパイル実行します)
      

(7)結果表示
   以下のPDFを開いてください.都合により 12分割 となっております.(空白ページもあります)
   

http://hayato1224.web.fc2.com/Doxygen/refman-01.pdf
http://hayato1224.web.fc2.com/Doxygen/refman-02.pdf (空白ページ)
http://hayato1224.web.fc2.com/Doxygen/refman-03.pdf
http://hayato1224.web.fc2.com/Doxygen/refman-04.pdf (空白ページ)
http://hayato1224.web.fc2.com/Doxygen/refman-05.pdf
http://hayato1224.web.fc2.com/Doxygen/refman-06.pdf
http://hayato1224.web.fc2.com/Doxygen/refman-07.pdf
http://hayato1224.web.fc2.com/Doxygen/refman-08.pdf
http://hayato1224.web.fc2.com/Doxygen/refman-09.pdf
http://hayato1224.web.fc2.com/Doxygen/refman-10.pdf
http://hayato1224.web.fc2.com/Doxygen/refman-11.pdf
http://hayato1224.web.fc2.com/Doxygen/refman-12.pdf

   
   




(EOF)
スポンサーサイト
  1. 2018/12/17(月) 09:38:00|
  2. 便利ツール

[LaTeX] TikZlings --- かわいい動物や類似の生き物のコレクション

§1 はじめに

TikZlingsパッケージは,同一作者による TikZmarmotsパッケージ(http://konoyonohana.blog.fc2.com/blog-entry-488.html) の次の進化段階で,
さらなる動物とともにそれを拡張したものになっています.このパッケージは進行中です.

1.1 インストール

必要に応じて,CTAN( https://ctan.org/pkg/tikzlings )から
ダウンロードしてください.

TeXLive/W32TeX などには標準でインストールされています.

1.2 マニュアル

コマンドラインから texdoc tikzlings を実行するか,
上記に同梱の tikzlings.pdf をお読み下さい.

§2 使い方

2.1プリアンブルに
  \usepackage {tikzlings}
  を記述します.

2.2 コマンド

次のTikZlingsコマンドが含まれています.

\bear %(クマ), \coati %(ハナグマ), \koala %(コアラ), \marmot %(マーモット), \moles %(モグラ)
\mouse %(マウス), \owl %(フクロウ), \penguin %(ペンギン), \sloth %(ナマケモノ), \snowman %(雪だるま)

§3 サンプル

オプションで着色,着替え,3D,サイズ,などの付加ができます.
以下はオプションなしのデフォルトのサンプルです.

(1)ソースコード (main.tex)

■■■■■■■■■■■■■■■■■■■
\documentclass[a5paper]{ltjsarticle}
\input{preamble.tex}
%
\begin{document}
\begin{tcblisting}{title={Basic Bear:クマ}}
\begin{tikzpicture}
\bear
\end{tikzpicture}
\end{tcblisting}

\bigskip

\begin{tcblisting}{title={Basic Coati:ハナグマ}}
\begin{tikzpicture}
\coati
\end{tikzpicture}
\end{tcblisting}

\bigskip

\begin{tcblisting}{title={Basic Koala:コアラ}}
\begin{tikzpicture}
\koala
\end{tikzpicture}
\end{tcblisting}

\bigskip

\begin{tcblisting}{title={Basic Marmot:マーモット}}
\begin{tikzpicture}
\marmot
\end{tikzpicture}
\end{tcblisting}

\bigskip

\begin{tcblisting}{title={Basic Moles:モグラ}}
\begin{tikzpicture}
\moles
\end{tikzpicture}
\end{tcblisting}

\bigskip

\begin{tcblisting}{title={Basic Mouse:マウス}}
\begin{tikzpicture}
\mouse
\end{tikzpicture}
\end{tcblisting}

\bigskip

\begin{tcblisting}{title={Basic Owl:フクロウ}}
\begin{tikzpicture}
\owl
\end{tikzpicture}
\end{tcblisting}

\bigskip

\begin{tcblisting}{title={Basic Penguin:ペンギン}}
\begin{tikzpicture}
\penguin
\end{tikzpicture}
\end{tcblisting}

\bigskip

\begin{tcblisting}{title={Basic Sloth:ナマケモノ}}
\begin{tikzpicture}
\sloth
\end{tikzpicture}
\end{tcblisting}

\bigskip

\begin{tcblisting}{title={Basic Snowman:雪だるま}}
\begin{tikzpicture}
\snowman
\end{tikzpicture}
\end{tcblisting}
\end{document}
■■■■■■■■■■■■■■■■■■■
 
 
 
(2)preamble.tex

■■■■■■■■■■■■■■■■■■■
\usepackage{tikzlings}
\usepackage[most]{tcolorbox}
%
\usepackage{tikzlings-bears} %クマ
\usepackage{tikzlings-coatis} %ハナグマ
\usepackage{tikzlings-koalas} %コアラ
\usepackage{tikzlings-marmots} %マーモット(モルモット)
\usepackage{tikzlings-moles} %モグラ
\usepackage{tikzlings-mice} %マウス
\usepackage{tikzlings-owls} %フクロウ
\usepackage{tikzlings-penguins}%ペンギン
\usepackage{tikzlings-sloths} %ナマケモノ
\usepackage{tikzlings-snowmans}%雪だるま
%
\definecolor{duckblue}{RGB}{0,70,140}
\definecolor{marmotred}{RGB}{140,20,40}
%
\lstdefinestyle{marmotstyle}{%
language={[latex]TeX},
tabsize=2,
breaklines,
basicstyle=\footnotesize\ttfamily,
columns=fullflexible,
texcsstyle=*\color{duckblue}\bfseries,
keywordstyle=\color{red!60!black}\bfseries,
morekeywords={tikzpicture,scope,patterns,calc,pgfinterruptboundingbox},
moretexcs={marmot,path,definecolor,scalebox,foreach,node,draw,PassOptionsToPackage,%
usetikzlibrary,selectcolormodel,colorlet,includegraphics,tikzset,shade,duck},
}
%
\tcbset{%
colframe=marmotred,
arc=2mm,
fonttitle=\bfseries,
sidebyside,
listing options={style=marmotstyle},
center lower,
righthand width=5.5cm,
bottom=0pt,
top=0pt,
before lower={%
\setlength{\parskip}{0.5cm}%
\spaceskip=5\fontdimen2\font},
}
■■■■■■■■■■■■■■■■■■■


(3)コンパイル

   luajitlatex main.tex


(4)結果

tikzrings01A.png


tikzrings01B.png


tikzrings01C.png

 
 
(EOF)

  1. 2018/12/09(日) 09:49:50|
  2. LaTeX Tools

[LaTeX] topiclongtable --- 階層的にマージするセルでロングテーブルを拡張する

§1 はじめに

topiclongtableパッケージは,longtableを拡張してtopiclongtableを実装しています.
これは垂直に隣接するセルが同じ内容をもち,左側のセルがマージされている場合にのみマージされます.

典型的な使用例は,複数のページにまたがる表であり,階層的に構成されたトピックのリスト
(したがってパッケージ名)を含んでいます.

例:
topiclongtableマクロを使用するには,最初のカラム指定に "F"を,他のカラム指定に "T"を付加する
必要があります.プレフィックスは,topiclongtableマクロを含む最後の列に続く列でのみ省略できます.

topiclongtable01.png



1.1 インストール

必要に応じて,CTAN( https://ctan.org/pkg/topiclongtable )から
ダウンロードしてください.

TeXLiveには標準でインストールされています.

1.2 マニュアル

コマンドラインから texdoc topiclongtable を実行するか,
上記に同梱の topiclongtable.pdf をお読み下さい.

§2 使い方

2.1プリアンブルに
  \usepackage {topiclongtable}
  を記述します.

2.2 コマンド

● topiclongtable環境
 \begin{topiclongtable}{<column specification>}
  <cells specification>
 \end{topiclongtable}

   longtable の全ての機能が利用可能です.

● \Topic[<content>]
 これはパッケージのメインマクロです.セルのオプションの<content>をラップして、
 隣接するセルとマージできるようにすることができます.

● \TopicLine
 行の先頭で使用して,水平線を自動的に描画しマージされたセルを正しく考慮します.
 デフォルトでは,上部と下部に水平線が描画されません.longtableフッターとヘッダーを使用して
 簡単に描画することができます

● \TopicSetVPos{<vertical position specification>}
 \Topicセルの垂直位置を設定できます。
 水平位置指定は、 "b"(下)、 "c"(中央)、およびデフォルト "t"(上)です.

● \TopicSetWidth{<cell width specification>}
 \Topicセルの幅を設定できます.
 <cell>幅の指定は, "="(列の幅に適合する)とデフォルトの "*"(自然な内容の幅に適合)です.

§3 サンプル

topiclongtable02.png


(EOF)

  1. 2018/11/25(日) 09:25:08|
  2. LaTeX Tools

[LaTeX] cmdtrack --- 使用されているコマンドのチェック

§1 はじめに

cmdtrackパッケージは,ドキュメントプリアンブルで定義されたコマンドが実際にドキュメントのどこで
使用されているかどうかを支援します.

cmdtrackパッケージがドキュメントのプリアンブルにロードされた後,そのポイントとドキュメントの先頭との間の
すべての \newcommand がログに記録されます.同時に,コンソール画面にも表示されます.

\newcommand,\newenvironment,\newtheorem,\DeclareMathSymbol,\DeclareMathOperator
およびその変種で定義されたコマンドだけが記録されます.

\newcommandではなく \def で定義されている場合はコマンドは記録されません.

1.1 インストール

必要に応じて,CTAN( https://ctan.org/pkg/cmdtrack )から
ダウンロードしてください.

TeXLive には標準でインストールされています.

1.2 マニュアル

コマンドラインから texdoc cmdtrack を実行するか,
上記に同梱の cmdtrack.pdf をお読み下さい.

§2 使い方

2.1プリアンブルに
  \usepackage {cmdtrack}
  を記述します.

§3 サンプル

cmdtrack01.png


コンソール画面

=========================================
"年賀" was never used      ---\年賀は定義されているが使われていない
"whele" was used on line 11   ---\wheleはソース11行目で使用されている
"mipX" was used on line 16   ----mip環境はソース16行目で使用されている
"THE" was used on line 26    ---THE環境はソース26行目で使用されている
=========================================

(注) .logファイルにも同上が記録されます.


(EOF)

  1. 2018/11/07(水) 09:52:02|
  2. LaTeX Tools

[LaTeX] kvmap --- Karnaughマップを作成する

§1 はじめに

kvmapは,隣接する"1"のグルーピング化を含むKarnaughマップをタイプセットするための
ユーザフレンドリーな方法を提供しています.
このパッケージは,xparse(expl3),tikz,およびenvironに依存します.

Karnaughマップを描くのは珍しいことではなく,CTANですでにタイプされているパッケージを利用できるように
なっています.

拙著ブログでも,次が公開されています.

askmaps --- カルノー図を描く
karnaugh-map --- カルノーマップを最大6変数まで描画する
kvmacros --- カルノー図を描く

今回,提供される kvmap が最もやり易いと思われます.


1.1 インストール

必要に応じて,CTAN( https://ctan.org/pkg/kvmap )から
ダウンロードしてください.

TeXLive/W32TeX などには標準でインストールされています.

1.2 マニュアル

コマンドラインから texdoc kvmap を実行するか,
上記に同梱の kvmap.pdf をお読み下さい.

§2 使い方

2.1プリアンブルに
  \usepackage {kvmap}
  を記述します.

2.2 簡単な例

(1)\kvlist による方法

\kvlist{<width>}{<height>}{<1,0[,…]>}{<a,b[,…].>}

行列の幅と高さを指定し,要素を行単位で入力します.
最後の引数は,コンマで区切られた変数名のリストで構成されます.
それらは数式モードでタイプセットされています.

kvmap-HH01.png



(2)kvmatrix環境による方法

\begin{kvmatrix}{<a,b,c[,…]>}
<environment content>
\end{kvmatrix}


この環境は,表形式の環境と同様に行と列を入力する構造化された方法を
提供します.こちらの方が,推奨されています.


kvmap-HH02.png



(3)バンドル(グルーピング)

\bundle[<key-value pairs>]{<x1>}{<y1>}{<x2>}{<y2>}

このパッケージのもう1つの特徴は,少なくとも隣接する1または0(インプリカントとも呼ばれます)を視覚化する
長方形(グルーピング)を描く方法を \bundleコマンドで行います.

kvmap-HH03.png


\bundle は,2つのコーナーで指定された領域の周囲に矩形を描画します. オプションの invert はバンドルを
外側に開き、overlapmarginsは,エッジがマージンにどれだけ引き込まれるかを長さで指定します.
color を使用すると,境界線の色を変更することができ,reducepace によって,bumdle の幅を狭くするか広げるかを
指定できます.オプションの使い方については,下記のサンプルをご覧ください.


§3 サンプル

kvmap-HH04.png



\begin{kvmap}[<key-value pairs>]
<environment content>
\end{kvmap}

この環境は,最初の子要素としてkvmatrixまたは\kvlistをもつべきtikzpicutreへのインタフェースです.



(EOF)
  1. 2018/10/21(日) 17:02:27|
  2. LaTeX Tools
次のページ