Yu'n Craft
📅 投稿日: 2019-05-25 | 📂 カテゴリ: software-crafts

Visual Studio Codeでソフトウェア設計書(Word文書)を書く環境を作る(設計書のテンプレートを作る)

にほんブログ村 IT技術ブログへ
にほんブログ村

目次
はじめにデフォルトのテンプレートを出力するテンプレートをカスタマイズするMarkdown文書(.md)に必要事項を記述するWord文書を出力してみるまとめ

はじめに

前回は、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

![システム構成図](/sitemap_assets/software-crafts/vscode/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を使って、少々簡素な書式であっても、テキストだけでできるだけ早く手軽にソフトウェア設計書を書くことを目的としています。

本記事が、ソフトウェア開発にかかわる多くの方の参考にになることを期待しています。

前の記事

Visual Studio Codeでソフトウェア設計書(Word文書)を書く環境を作る(環境構築2)

次の記事

Visual Studio Codeでソフトウェア設計書(Word文書)を書く環境を作る(PlantUMLによる作図1)

関連記事

(8)Pythonの仮想環境をバージョン指定で切り替える

2021/03/05 13:48

                    Anacondaの有償化の対策として、Windows上での複数のPythonのバージョンの仮想環境の作成方法を紹介します。

この方法により、Anacondaほどではありませんが、自分の作ったテンプレート的な仮想環境を使いまわすことが可能になります。

Visual Studio Codeでソフトウェア設計書(Word文書)を書く環境を作る(PlantUMLによる作図1)

2019/05/30 11:02

                    Visual Studio Code(VSCode)でMarkdown Preview EnhancedとPlantUMLを使ってテキストだけでWord形式の文書を生成する方法を練習してみます。

Visual Studio Codeでソフトウェア設計書(Word文書)を書く環境を作る(環境構築2)

2019/05/21 17:58

                    Visual Studio Code(VSCode)でMarkdown Preview EnhancedとPlantUMLを使ってテキストだけでWord形式文書を生成するために必要な拡張機能のインストール方法と設定を紹介します。

Visual Studio Codeでソフトウェア設計書(Word文書)を書く環境を作る(環境構築1)

2019/05/20 23:54

                    Visual Studio Code(VSCode)でMarkdown Preview EnhancedとPlantUMLを使ってテキストだけでWord形式文書を生成するために必要なソフトウェアのインストール方法を紹介します。

Visual Studio Codeでソフトウェア設計書(Word文書)を書く環境を作る(概要)

2019/05/18 23:43

                    Visual Studio Code(VSCode)でMarkdown Preview EnhancedとPlantUMLを使ってテキストだけでWord形式文書を生成するために必要なソフトウェアを紹介します。

Visual Studio CodeでProxy(認証あり)を設定する方法

2019/05/17 1:51

                    Visual Studio Code (VSCode)で認証のあるProxyを設定する方法を紹介します。

Visual Studio Codeのインストールと日本語化

2019/05/17 0:34

                    Visual Studio Code(VSCode)のインストールと日本語化の方法を紹介します。

(7)Visual Studio CodeでAnacondaの仮想環境を割り当てる

2019/03/26 23:02

                    Pythonによるソフトウェア開発を行うにあたって、コードエディタは必須のアイテムです。

今回は、マイクロソフトが提供しているVisual Studio…