このエントリーをはてなブックマークに追加 にほんブログ村 IT技術ブログへ
にほんブログ村
目次

はじめに

前回は、VSCodeをMarkdownとUMLを使って文書を書き、最終的にはMicrosoftのWord形式のファイルを生成するための必要な拡張機能のインストール方法を紹介し、Word文章が作成されるところまで実験してみました。
今回は、ソフトウェア設計書のテンプレートとなるファイルを作り、ソフトウェア設計書をWord形式で出力してみます。

デフォルトのテンプレートを出力する

これまで構築してきたVSCodeの環境では、Word文書を生成するところで、Pandocを使用しています。
従って、出力する文書内の各種の書式は、PandocのWord文書用のテンプレートファイルを編集する必要があります。
Pandocのデフォルトのテンプレートファイルは、以下のコマンドを実行することでテンプレートとなるファイル(.docx)を生成できます。

pandoc --print-default-data-file reference.docx > ソフトウェア設計書テンプレート.docx

生成された「ソフトウェア設計書テンプレート.docx」をVSCodeのワークスペース(前回お試しのMarkdownファイルを作成した場所)にコピーしておきます。

テンプレートをカスタマイズする

次に、コピーした「ソフトウェア設計書テンプレート.docx」をカスタマイズします。
これは、Word文書を直接カスタマイズするので、まずは、Wordで「ソフトウェア設計書テンプレート.docx」を開きます。
テンプレートのカスタマイズは、下図の赤丸のところをクリックして、「スタイル」ウィンドウを表示します。
tedit01.png

次に、書式を編集する対象(例えばTitle)にカーソルを当て、「スタイル」の中から現在設定されているスタイルを見つけます。
Titleのところは「表題」のスタイルが割り当てられていると思います。
tedit02.png

次に、このスタイルを編集します。フォントや色などの編集は容易に行えると思います。
また、必要に応じてダイアログ左下の「書式」で詳細な設定を行うこともできます。
tedit03.png

スタイルの編集のコツとしては、Pandocで制御されない部分として以下の点を編集していきます。
・表紙のみ別書式とする
 (「ページ設定」の「その他」の「ヘッダーとフッター」で「先頭ページのみ別指定」をチェックする
・見出しの番号付け
 「書式」の「箇条書きと段落番号」で番号付きの書式を指定する
・見出し1など、改ページが必要な個所に改ページを入れる
 「書式」の「段落」の「改ページと改行」で「段落前で改ページする」をチェック
・ヘッダーやフッターの書式を編集する
・ページ番号を入れる(開始を0ページとする)

上記のように編集した「ソフトウェア設計書テンプレート.docx」の例を以下のリンクからダウンロードして参考にしてみてください。(ダウンロード時にファイル名が変わるので後で変更してください)
ソフトウェア設計書テンプレート.docx

Markdown文書(.md)に必要事項を記述する

Markdownで記述した文書をWord文書として出力する場合、Markdown文書の先頭で、YAML形式でいくつかの定義をする必要があります。
まず、以下の例を参考にして、必要な定義を解説します。

---
title: "□□□機能ソフトウェア設計書"
subtitle: "基本設計工程 (サンプル)"
author: "Yu'n Craft"
date: 2019/5/26
abstract: "○○システム □□□機能 ソフトウェア設計書の概要"
output: 
  word_document:
    path: word.docx
    toc: true
    pandoc_args: ["--reference-doc=ソフトウェア設計書テンプレート.docx"]
---

titleは、Word文書の表紙のタイトルの設定です。
subtitleやauthorやdateも同じです。
abstractも必要であれば記載します。
outputの部分は非常に重要です。
pathは出力するWordのファイル名、toc: trueは目次ありを示します。
そして、pandoc_args: ["--reference-doc=ソフトウェア設計書テンプレート.docx"]を設定することで、編集したテンプレートを使うように指定します。

なお、以下がMarkdownの全文です。

---
title: "□□□機能ソフトウェア設計書"
subtitle: "基本設計工程 (サンプル)"
author: "Yu'n Craft"
date: 2019/5/26
abstract: "○○システム □□□機能 ソフトウェア設計書の概要"
output: 
  word_document:
    path: word.docx
    toc: true
    pandoc_args: ["--reference-doc=ソフトウェア設計書テンプレート.docx"]
---

# タイトル1

タイトルの概要1

## サブタイトル1-1

サブタイトルの概要1-1

| i | サイコロの目 |
|------:|:------:|
| 1 | 3 |
| 2 | 2 |
| 3 | 6 |
| 4 | 5 |
| 5 | 1 |
| 6 | 4 |
| 7 | 2 |
| 8 | 6 |
: 表のサンプル

## サブタイトル1-2

サブタイトルの概要1-2

![システム構成図](ex.png)

# タイトル2

タイトルの概要2

## サブタイトル2-1

サブタイトルの概要2-1

## サブタイトル2-2

サブタイトルの概要2-2

* あああ
* いいい

```plantuml
User -> (Start)
User --> (Use the application) : A small label

:Main Admin: ---> (Use the application) : This is\nyet another\nlabel

```

## サブタイトル3

サブタイトルの概要3

Word文書を出力してみる

Word文書として出力した結果のイメージは以下の通りです。
p12.png
p34.png
p56.png

いかがですか?ソフトウェア設計書として、それなりに使えそうな書式でMarkdownが出力できたと思います。また、UMLもPlantUMLとの連携もできていますね。(図名が入れられないのがちょっと残念でしたが...)
以下に出力したファイルを例として置いておきます。
出力例(Word.docx)

まとめ

今回は、ソフトウェア設計書のテンプレートとなるファイルを作り、VSCodeを使ったMarkdownで記述したソフトウェア設計書をWord形式で出力しました。
Word文書のカスタマイズにより、ある程度の文書の書式設定が行えることはわかっていただけたかと思います。
ただし、なんでもできるわけではなく、結構できない書式設定も多いので、もし書式にこだわるのであれば、これまで通りWord文書を直接編集するのがよいと思います。
ここでは、あくまでVSCodeを使って、少々簡素な書式であっても、テキストだけでできるだけ早く手軽にソフトウェア設計書を書くことを目的としています。
本記事が、ソフトウェア開発にかかわる多くの方の参考にになることを期待しています。

関連記事