diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile new file mode 100644 index 0000000..98942ca --- /dev/null +++ b/.devcontainer/Dockerfile @@ -0,0 +1,4 @@ +FROM ghcr.io/huideyeren/vivliostyle-review-docker:latest + +RUN pnpm install +RUN bundle install \ No newline at end of file diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 0000000..568f44f --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1,52 @@ +// For format details, see https://aka.ms/devcontainer.json. For config options, see the README at: +// https://github.com/microsoft/vscode-dev-containers/tree/v0.191.0/containers/debian +{ + "name": "Re:VIEW", + "build": { + "dockerfile": "Dockerfile", + }, + + // Set *default* container specific settings.json values on container create. + "settings": { + "editor.renderWhitespace": "all", + "editor.renderControlCharacters": true, + "git.suggestSmartCommit": true, + "textlint.languages": [ + "review" + ] + }, + + // Add the IDs of extensions you want installed when the container is created. + "extensions": [ + "atsushieno.language-review", + "taichi.vscode-textlint", + "8amjp.charactercount", + "mhutchie.git-graph", + "donjayamanne.githistory", + "felipecaputo.git-project-manager", + "github.vscode-pull-request-github", + "eamodio.gitlens", + "ms-ceintl.vscode-language-pack-ja", + "yzhang.markdown-all-in-one", + "bierner.markdown-mermaid", + "darkriszty.markdown-table-prettify", + "bpruitt-goddard.mermaid-markdown-syntax-highlighting", + "yzane.markdown-pdf", + "christian-kohler.path-intellisense", + "cssho.vscode-svgviewer", + "takanotume24.pdf", + "kisstkondoros.vscode-gutter-preview" + ], + + // Use 'forwardPorts' to make a list of ports inside the container available locally. + // "forwardPorts": [], + + // Uncomment to use the Docker CLI from inside the container. See https://aka.ms/vscode-remote/samples/docker-from-docker. + // "mounts": [ "source=/var/run/docker.sock,target=/var/run/docker.sock,type=bind" ], + + // Uncomment when using a ptrace-based debugger like C++, Go, and Rust + // "runArgs": [ "--cap-add=SYS_PTRACE", "--security-opt", "seccomp=unconfined" ], + + // Comment out connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root. + // "remoteUser": "vscode" +} diff --git a/.github/workflows/jobs.yml b/.github/workflows/jobs.yml new file mode 100644 index 0000000..7205eda --- /dev/null +++ b/.github/workflows/jobs.yml @@ -0,0 +1,309 @@ +# This is a basic workflow to help you get started with Actions + +name: Build books. + +# Controls when the workflow will run +on: + # Triggers the workflow on push or pull request events but only for the main branch + push: + branches: + - main + pull_request: + branches: + - main + + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + +env: + SIZE: a6 # 対応はa4, a5, a6, b5, shinsho + # tateが縦組み、yokoが横組み + # config.ymlのdirectionの設定変更も忘れずに。 + MUKI: tate +# A workflow run is made up of one or more jobs that can run sequentially or in parallel +jobs: + # reviewdog-github-check: + # name: reviewdogによる簡易校正 + # runs-on: ubuntu-latest + # steps: + # #reviewdogのアクション + # - uses: reviewdog/action-setup@v1 + # with: + # reviewdog_version: latest + + # #textlintを動かすためのnodeアクション + # - uses: actions/setup-node@v4 + + # - name: リポジトリのチェックアウト + # uses: actions/checkout@v3 + # with: + # submodules: recursive + + # - name: cache-node-modules + # #stepsが失敗(文章の乱れ)した場合でもcacheを取得するようにする + # uses: pat-s/always-upload-cache@v2.1.3 + # env: + # cache-name: cache-node-modules + # with: + # path: ~/.npm + # key: node-${{ hashFiles('**/package-lock.json') }} + # restore-keys: | + # node- + + # - name: Install textlint + # run: 'npm install --save-dev textlint textlint-rule-preset-smarthr textlint-rule-prh textlint-plugin-review' + + # - name: Install dependent module + # run: npm install + + # - name: Execute textlint + # env: + # REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }} + # run: | + # npx textlint -f checkstyle chapter/*.re wiki/*.md README.md \ + # | reviewdog -f=checkstyle -name="textlint" -diff="git diff ${{ github.event.pull_request.base.ref }}" -reporter=github-pr-review -level="error" + + epub: + # needs: reviewdog-github-check + name: EPUB版組 + runs-on: ubuntu-latest + container: + image: ghcr.io/huideyeren/vivliostyle-review-docker:latest + steps: + # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it + - name: リポジトリのチェックアウト + uses: actions/checkout@v4 + - name: 現在時刻を取得 + env: + TZ: "Asia/Tokyo" # タイムゾーンを指定 + id: date + run: echo "::set-output name=date::$(date +'%Y-%m-%d_%H%M')" + # '%Y-%m-%d %H:%M'の部分を書き換えれば、任意の表示に変更できる。 + - name: 現在時刻を確認 + run: echo ${{ steps.date.outputs.date }} # 2022-01-03 10:42 + - name: Node.jsのパッケージをインストール + run: pnpm install + - name: SCSSのコンパイル + run: pnpm run style:${{ env.SIZE }}-${{ env.MUKI }}-no-bleed + - name: Rubyのパッケージをインストール + run: bundle install + - name: Playwrightのインストール + run: ./node_modules/.bin/playwright install --with-deps + - name: EPUBの生成 + run: REVIEW_CONFIG_FILE=config-epub-${{ env.MUKI }}.yml bundle exec rake epub + - name: 成果物のアップロード + uses: actions/upload-artifact@v4 + with: + name: ${{ format('inokashira-template_{0}_{1}_{2}', 'epub', env.MUKI, steps.date.outputs.date) }} + path: book.epub + + print-pdf: + # needs: reviewdog-github-check + name: 塗り足しのある印刷用PDF + runs-on: ubuntu-latest + container: + image: ghcr.io/huideyeren/vivliostyle-review-docker:latest + steps: + # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it + - name: リポジトリのチェックアウト + uses: actions/checkout@v4 + - name: 現在時刻を取得 + env: + TZ: "Asia/Tokyo" # タイムゾーンを指定 + id: date + run: echo "::set-output name=date::$(date +'%Y-%m-%d_%H%M')" + # '%Y-%m-%d %H:%M'の部分を書き換えれば、任意の表示に変更できる。 + - name: 現在時刻を確認 + run: echo ${{ steps.date.outputs.date }} # 2022-01-03 10:42 + - name: Node.jsのパッケージをインストール + run: pnpm install + - name: SCSSのコンパイル + run: pnpm run style:${{ env.SIZE }}-${{ env.MUKI }} + - name: Rubyのパッケージをインストール + run: bundle install + - name: Pythonのセットアップ + uses: actions/setup-python@v5 + with: + python-version: '3.12' + - name: 画像の白黒化 + run: | + python -m pip install --upgrade pip + python -m pip install anshitsu + pwd | python grayscaling.py >> .grayscaling.log + - name: 画像白黒化のログ確認 + run: cat .grayscaling.log + - name: Playwrightのインストール + run: ./node_modules/.bin/playwright install --with-deps + - name: PDFの生成 + run: REVIEW_CONFIG_FILE=config-print-${{ env.MUKI }}.yml REVIEW_VSCLI_USESANDBOX=true REVIEW_VSCLI_GRAYSCALE=true REVIEW_VSCLI_OPTIONS="--timeout 900" bundle exec rake vivliostyle + - name: 成果物のアップロード + uses: actions/upload-artifact@v4 + with: + name: ${{ format('inokashira-template_{0}_{1}_{2}', 'print-pdf', env.MUKI, steps.date.outputs.date) }} + path: book.pdf + + print-pdf-no-bleed: + # needs: reviewdog-github-check + name: 塗り足しのない印刷用PDF + runs-on: ubuntu-latest + container: + image: ghcr.io/huideyeren/vivliostyle-review-docker:latest + steps: + # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it + - name: リポジトリのチェックアウト + uses: actions/checkout@v4 + - name: 現在時刻を取得 + env: + TZ: "Asia/Tokyo" # タイムゾーンを指定 + id: date + run: echo "::set-output name=date::$(date +'%Y-%m-%d_%H%M')" + # '%Y-%m-%d %H:%M'の部分を書き換えれば、任意の表示に変更できる。 + - name: 現在時刻を確認 + run: echo ${{ steps.date.outputs.date }} # 2022-01-03 10:42 + - name: Node.jsのパッケージをインストール + run: pnpm install + - name: SCSSのコンパイル + run: pnpm run style:${{ env.SIZE }}-${{ env.MUKI }}-no-bleed + - name: Rubyのパッケージをインストール + run: bundle install + - name: Pythonのセットアップ + uses: actions/setup-python@v5 + with: + python-version: '3.12' + - name: 画像の白黒化 + run: | + python -m pip install --upgrade pip + python -m pip install anshitsu + pwd | python grayscaling.py >> .grayscaling.log + - name: 画像白黒化のログ確認 + run: cat .grayscaling.log + - name: Playwrightのインストール + run: ./node_modules/.bin/playwright install --with-deps + - name: PDFの生成 + run: REVIEW_CONFIG_FILE=config-print-${{ env.MUKI }}.yml EVIEW_VSCLI_USESANDBOX=true REVIEW_VSCLI_GRAYSCALE=true bundle exec rake vivliostyle + - name: 成果物のアップロード + uses: actions/upload-artifact@v4 + with: + name: ${{ format('inokashira-template_{0}_{1}_{2}', 'print-pdf-no-bleed', env.MUKI, steps.date.outputs.date) }} + path: book.pdf + + ebook-pdf: + # needs: reviewdog-github-check + name: 電子書籍用PDF + runs-on: ubuntu-latest + container: + image: ghcr.io/huideyeren/vivliostyle-review-docker:latest + steps: + - name: リポジトリのチェックアウト + uses: actions/checkout@v4 + - name: 現在時刻を取得 + env: + TZ: "Asia/Tokyo" # タイムゾーンを指定 + id: date + run: echo "::set-output name=date::$(date +'%Y-%m-%d_%H%M')" + # '%Y-%m-%d %H:%M'の部分を書き換えれば、任意の表示に変更できる。 + - name: 現在時刻を確認 + run: echo ${{ steps.date.outputs.date }} # 2022-01-03 10:42 + - name: Node.jsのパッケージをインストール + run: pnpm install + - name: SCSSのコンパイル + run: pnpm run style:${{ env.SIZE }}-${{ env.MUKI }}-no-bleed + - name: Rubyのパッケージをインストール + run: bundle install + - name: Playwrightのインストール + run: ./node_modules/.bin/playwright install --with-deps + - name: PDFの生成 + run: REVIEW_CONFIG_FILE=config-ebook-${{ env.MUKI }}.yml REVIEW_VSCLI_USESANDBOX=true REVIEW_VSCLI_OPTIONS="--timeout 900" bundle exec rake vivliostyle + - name: 成果物のアップロード + uses: actions/upload-artifact@v4 + with: + name: ${{ format('inokashira-template_{0}_{1}_{2}', 'ebook-pdf', env.MUKI, steps.date.outputs.date) }} + path: book.pdf + + udonbook: + # needs: reviewdog-github-check + name: UDON Book用画像 + runs-on: ubuntu-latest + container: + image: ghcr.io/huideyeren/vivliostyle-review-docker:latest + steps: + - name: リポジトリのチェックアウト + uses: actions/checkout@v4 + - name: 現在時刻を取得 + env: + TZ: "Asia/Tokyo" # タイムゾーンを指定 + id: date + run: echo "::set-output name=date::$(date +'%Y-%m-%d_%H%M')" + # '%Y-%m-%d %H:%M'の部分を書き換えれば、任意の表示に変更できる。 + - name: 現在時刻を確認 + run: echo ${{ steps.date.outputs.date }} # 2022-01-03 10:42 + - name: Node.jsのパッケージをインストール + run: pnpm install + - name: SCSSのコンパイル + run: pnpm run style:${{ env.SIZE }}-${{ env.MUKI }}-no-bleed + - name: Rubyのパッケージをインストール + run: bundle install + - name: Playwrightのインストール + run: ./node_modules/.bin/playwright install --with-deps + - name: PDFの生成 + run: REVIEW_CONFIG_FILE=config-udonbook-${{ env.MUKI }}.yml REVIEW_VSCLI_USESANDBOX=true REVIEW_VSCLI_OPTIONS="--timeout 900" bundle exec rake vivliostyle + - name: 画像の生成 + run: mkdir distimages && cp images/frontcover.png images/backcover.png ./distimages && pdftoppm -png book.pdf ${{ github.repository }} -scale-to-y 1024 && ls -la ./distimages + - name: 成果物のアップロード + uses: actions/upload-artifact@v4 + with: + name: ${{ format('inokashira-template_{0}_{1}_{2}', 'udonbook-png', env.MUKI, steps.date.outputs.date) }} + path: ./distimages/*.png + + # paper: + # # 校正ツールによるチェックが通らないとダメにするにはチェックを外す + # # needs: reviewdog-github-check + # name: 旧LaTeX版PDF + # runs-on: ubuntu-latest + # container: + # image: ghcr.io/huideyeren/review-docker:latest + # steps: + # - name: リポジトリのチェックアウト + # uses: actions/checkout@v4 + # - name: 現在時刻の取得 + # env: + # TZ: "Asia/Tokyo" # タイムゾーンを指定 + # id: date + # run: echo "::set-output name=date::$(date +'%Y-%m-%d_%H%M')" + # # '%Y-%m-%d %H:%M'の部分を書き換えれば、任意の表示に変更できる。 + # - name: 現在時刻を確認 + # run: echo ${{ steps.date.outputs.date }} # 2022-01-03 10:42 + # - name: Rubyのパッケージをインストール + # run: bundle install + # - name: Node.jsのパッケージをインストール + # run: npm install + # - name: Playwrightのインストール + # run: ./node_modules/.bin/playwright install + # - name: pdfcropコマンドを使えるようにする + # run: apt install texlive-extra-utils + # - name: PlantUMLのコピー + # run: cp /java/plantuml.jar . + # - name: ツールのチェック + # run: dot -V && blockdiag --version && java -jar plantuml.jar -version + # - name: PlantUMLを図に変換する + # run: pwd | bash ./plantuml.sh >> .plantuml.log + # - name: PlantUMLの変換ログを確認する + # run: cat .plantuml.log + # - name: SVGをPDFに変換する + # run: pwd | python3 svg.py >> .svg.log + # - name: SVGをPDFに変換したときのログを確認する + # run: cat .svg.log + # - name: MermaidのPNG化 + # run: ./mmdtopng.sh images/*.mermaid + # - name: 画像の白黒化 + # run: pwd | python3 grayscaling.py >> .grayscaling.log + # - name: 画像白黒化のログ確認 + # run: cat .grayscaling.log + # - name: PDFの生成 + # run: REVIEW_CONFIG_FILE=config-print-pdf.yml bundle exec rake pdf + # - name: 成果物のアップロード + # uses: actions/upload-artifact@v4 + # with: + # name: ${{ format('inokashira-template_{0}_{1}_{2}', 'print-pdf', env.MUKI, steps.date.outputs.date) }} + # path: book.pdf + diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..f5820e8 --- /dev/null +++ b/.gitignore @@ -0,0 +1,169 @@ +/*.pdf +/*.epub +/*.html +/webroot +/*-pdf +/*-epub +/*-text +/*-idgxml + +/vendor +/.bundle + +# Created by https://www.gitignore.io/api/vim,linux,macos,emacs,windows +# Edit at https://www.gitignore.io/?templates=vim,linux,macos,emacs,windows + +### Emacs ### +# -*- mode: gitignore; -*- +*~ +\#*\# +/.emacs.desktop +/.emacs.desktop.lock +*.elc +auto-save-list +tramp +.\#* + +# Org-mode +.org-id-locations +*_archive + +# flymake-mode +*_flymake.* + +# eshell files +/eshell/history +/eshell/lastdir + +# elpa packages +/elpa/ + +# reftex files +*.rel + +# AUCTeX auto folder +/auto/ + +# cask packages +.cask/ +dist/ + +# Flycheck +flycheck_*.el + +# server auth directory +/server/ + +# projectiles files +.projectile + +# directory configuration +.dir-locals.el + +# network security +/network-security.data + + +### Linux ### + +# temporary files which can be created if a process still has a handle open of a deleted file +.fuse_hidden* + +# KDE directory preferences +.directory + +# Linux trash folder which might appear on any partition or disk +.Trash-* + +# .nfs files are created when an open file is removed but is still being accessed +.nfs* + +### macOS ### +# General +.DS_Store +.AppleDouble +.LSOverride + +# Icon must end with two \r +Icon + +# Thumbnails +._* + +# Files that might appear in the root of a volume +.DocumentRevisions-V100 +.fseventsd +.Spotlight-V100 +.TemporaryItems +.Trashes +.VolumeIcon.icns +.com.apple.timemachine.donotpresent + +# Directories potentially created on remote AFP share +.AppleDB +.AppleDesktop +Network Trash Folder +Temporary Items +.apdisk + +### Vim ### +# Swap +[._]*.s[a-v][a-z] +[._]*.sw[a-p] +[._]s[a-rt-v][a-z] +[._]ss[a-gi-z] +[._]sw[a-p] + +# Session +Session.vim +Sessionx.vim + +# Temporary +.netrwhist +# Auto-generated tag files +tags +# Persistent undo +[._]*.un~ + +### Windows ### +# Windows thumbnail cache files +Thumbs.db +Thumbs.db:encryptable +ehthumbs.db +ehthumbs_vista.db + +# Dump file +*.stackdump + +# Folder config file +[Dd]esktop.ini + +# Recycle Bin used on file shares +$RECYCLE.BIN/ + +# Windows Installer files +*.cab +*.msi +*.msix +*.msm +*.msp + +# Windows shortcuts +*.lnk + +# End of https://www.gitignore.io/api/vim,linux,macos,emacs,windows + +style.css +style.css.map +/_refiles/ +/node_modules +sty/old/ + +# pnpm-lock.yaml +pnpm-lock.yaml + +# Gemfile.lock +Gemfile.lock + +# mermaid SVG +images/html/ \ No newline at end of file diff --git a/.textlintrc b/.textlintrc new file mode 100644 index 0000000..5ae7ddd --- /dev/null +++ b/.textlintrc @@ -0,0 +1,47 @@ +{ + "rules": { + "preset-smarthr":{ + "no-mixed-zenkaku-and-hankaku-alphabet": false, + "sentence-length": false + }, + "prh": { + "rulePaths": [ + "dict/smarthr-prh-basic.yml", + "dict/smarthr-prh-tech-word.yml" + ] + }, + "general-novel-style-ja": { + "chars_leading_paragraph": " 「『【〈《((“\"‘'[[〔{{<<●", + "no_punctuation_at_closing_quote": true, + "space_after_marks": true, + "even_number_ellipsises": true, + "even_number_dashes": true, + "appropriate_use_of_punctuation": true, + "appropriate_use_of_interpunct": true, + "appropriate_use_of_choonpu": true, + "appropriate_use_of_minus_sign": true, + "max_arabic_numeral_digits": 5 + }, + "common-misspellings": { + "ignore": [] + }, + "max-ten": { + "max" : 3 + }, + "no-doubled-conjunctive-particle-ga": true, + "no-dropping-the-ra": true + }, + "plugins": [ + "review" + ], + "filters": { + "comments": { + // enable comment directive + // if comment has the value, then enable textlint rule + "enablingComment": "textlint-enable", + // disable comment directive + // if comment has the value, then disable textlint rule + "disablingComment": "textlint-disable" + } + } +} \ No newline at end of file diff --git a/.vscode/extensions.json b/.vscode/extensions.json new file mode 100644 index 0000000..8c0c97f --- /dev/null +++ b/.vscode/extensions.json @@ -0,0 +1,22 @@ +{ + "recommendations": [ + "atsushieno.language-review", + "taichi.vscode-textlint", + "8amjp.charactercount", + "mhutchie.git-graph", + "donjayamanne.githistory", + "felipecaputo.git-project-manager", + "github.vscode-pull-request-github", + "eamodio.gitlens", + "ms-ceintl.vscode-language-pack-ja", + "yzhang.markdown-all-in-one", + "bierner.markdown-mermaid", + "darkriszty.markdown-table-prettify", + "bpruitt-goddard.mermaid-markdown-syntax-highlighting", + "yzane.markdown-pdf", + "christian-kohler.path-intellisense", + "cssho.vscode-svgviewer", + "takanotume24.pdf", + "kisstkondoros.vscode-gutter-preview" + ] +} \ No newline at end of file diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..d7fc985 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,35 @@ +{ + "yaml.customTags": [ + "!And", + "!And sequence", + "!If", + "!If sequence", + "!Not", + "!Not sequence", + "!Equals", + "!Equals sequence", + "!Or", + "!Or sequence", + "!FindInMap", + "!FindInMap sequence", + "!Base64", + "!Join", + "!Join sequence", + "!Cidr", + "!Ref", + "!Sub", + "!Sub sequence", + "!GetAtt", + "!GetAZs", + "!ImportValue", + "!ImportValue sequence", + "!Select", + "!Select sequence", + "!Split", + "!Split sequence" + ], + "textlint.languages": [ + "review", + "markdown" + ] +} \ No newline at end of file diff --git a/Gemfile b/Gemfile new file mode 100644 index 0000000..d4987c2 --- /dev/null +++ b/Gemfile @@ -0,0 +1,13 @@ +source 'https://rubygems.org' + +gem 'rake' +gem 'psych' +gem 'rubyzip' +gem 'mecab' +gem 'nokogiri' +gem 'review' +gem 'rexml' +gem 'math_ml' +gem 'rubocop' +gem 'pandoc2review' +gem 'playwright-runner' \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..fa7d301 --- /dev/null +++ b/README.md @@ -0,0 +1,37 @@ +# 井の頭文芸部 本文テンプレート + +[![Build books.](https://github.com/huidetang/XiandaiFenshuTemplate/actions/workflows/jobs.yml/badge.svg)](https://github.com/huidetang/XiandaiFenshuTemplate/actions/workflows/jobs.yml) + +Sorry, but the book will be written in Japanese, and the project is in Japanese as an official language. If you can read and write Japanese, you are welcome to contribute. + +井の頭文芸部で作った、[Re:VIEW](https://github.com/kmuto/review)用日本語縦書きテンプレートです。 + +ビルドに[Vivliostyle](https://vivliostyle.org/ja/)を使用します。 + +旧LaTeX版の設定も併記しています。 + +図は[Mermaid](https://mermaid.js.org/)が使えます。 + +もちろん、PNG形式などの画像ファイルにも対応しています。これらの画像ファイルは `images` フォルダーに配置してください。 + +なお、印刷用PDFではカラー画像はモノクロ画像に変換されます。 + +本文はRe:VIEW記法の他に、MarkdownとMicrosoft Wordに対応しています。しかし、Microsoft Word文書では書式が全て無視される上、縦中横が効かないなどいろいろな制約がありますのでご注意ください。これらの本文ファイルは `chapter` フォルダーに配置し、 `catalog.yml` ファイルに記載してください。なお、記載する際にMarkdownとMicrosoft Word文書の拡張子は `.re` に変更する必要があります。 + +後は、[Re:VIEWのドキュメント](https://github.com/kmuto/review/blob/master/doc/format.ja.md)を参照の上で書籍を書いてみてください。 + +なお、GitHub Actionsによるビルドを自動で実行する設定がついていますので、GitとGitHubの使い方を覚えれば執筆できる環境が揃うと思います。 + +## おすすめの環境 + +おすすめの環境は以下の通りです。 + +- エディタ : Visual Studio Code +- Linuxコンテナ環境 : Docker Desktop +- ソースコード管理 : GitHub + +詳しい説明は別途追記します。 + +## ライセンスについて (About LICENSE) + +このテンプレートはMITライセンスです。 \ No newline at end of file diff --git a/Rakefile b/Rakefile new file mode 100644 index 0000000..07b7219 --- /dev/null +++ b/Rakefile @@ -0,0 +1,3 @@ +Dir.glob('lib/tasks/*.rake').sort.each do |file| + load(file) +end diff --git a/backcover.tex b/backcover.tex new file mode 100644 index 0000000..0c91f91 --- /dev/null +++ b/backcover.tex @@ -0,0 +1 @@ +\includefullpagegraphics[width=\paperwidth,height=\paperheight,keepaspectratio]{images/backcover.pdf} \ No newline at end of file diff --git a/backcover.xhtml b/backcover.xhtml new file mode 100644 index 0000000..8021e05 --- /dev/null +++ b/backcover.xhtml @@ -0,0 +1,15 @@ + + + + + + + + 裏表紙 + + +
+ +
+ + \ No newline at end of file diff --git a/catalog.yml b/catalog.yml new file mode 100644 index 0000000..61809ff --- /dev/null +++ b/catalog.yml @@ -0,0 +1,17 @@ +PREDEF: + - preface.re + +CHAPS: + - ReVIEW独自マークアップ言語: + - how-to-use.re + - Markdown: + - markdown.re + - Microsoft word: + - word-ref.re + - custom-reference.re + +APPENDIX: + +POSTDEF: + - postscript.re + - bib.re \ No newline at end of file diff --git a/chapter/bib.re b/chapter/bib.re new file mode 100644 index 0000000..ec3526f --- /dev/null +++ b/chapter/bib.re @@ -0,0 +1,21 @@ += 参考文献 + +//embed[latex]{ +\begin{thebibliography}{99} +//} + +//bibpaper[第1巻][VR小説集第1巻]{ + るいざ・しゃーろっと『VR小説作品集 第1巻 2022年−2023年』, 東京・恢徳堂 2023年 +//} + +//bibpaper[第2巻][並行現実小説集第2巻]{ + るいざ・しゃーろっと『並行現実作品集 第2巻 2023年夏・初秋』, 東京・恢徳堂 2023年 +//} + +//bibpaper[第3巻][並行現実小説集第3巻]{ + るいざ・しゃーろっと『並行現実作品集 第3巻 2023年秋〜2024年年始』, 東京・恢徳堂 2023年 +//} + +//embed[latex]{ +\end{thebibliography} +//} \ No newline at end of file diff --git a/chapter/custom-reference.docx b/chapter/custom-reference.docx new file mode 100644 index 0000000..4e5e38f Binary files /dev/null and b/chapter/custom-reference.docx differ diff --git a/chapter/how-to-use.re b/chapter/how-to-use.re new file mode 100644 index 0000000..0270eb7 --- /dev/null +++ b/chapter/how-to-use.re @@ -0,0 +1,238 @@ += このテンプレートの使い方 + +この章ではこのテンプレートの使い方について説明します。 + +== このテンプレートを使うのに必要なもの + +このテンプレートは以下のツール・サービスを使用します。 + + * GitHub + * テキストエディタ(おすすめはVisual Studio Code) + * Docker(あれば) + +Dockerを使わない場合は以下のプログラミング言語環境が必要になりますが、@{非推奨}です。 + + * Node.js + ** パッケージマネージャーはpnpmを推奨 + * Ruby + * Python + * poppler + +ビルドする際は以下の順番でコマンドを入力してください。これはEPUBと塗り足し・トンボ無しの電子書籍用PDFを生成する手順です。OSはLinuxを想定しています。 + +//cmd{ +# Node.jsのパッケージをインストール +$ pnpm install + +# SCSSのコンパイル(ここでは文庫・縦・塗り足し無し) +$ pnpm run style:a6-tate-no-bleed + +# popplerのインストール +$ apt install poppler-utils + +# Playwrightのインストール +$ ./node_modules/.bin/playwright install --with-deps + +# Rubyのパッケージをインストール +$ bundle install + +# Pythonのパッケージをインストール +$ python -m pip install anshitsu + +# 画像の白黒化 +$ python grayscaling.py >> .grayscaling.log + +# EPUBの生成 +$ REVIEW_CONFIG_FILE=config-epub-tate.yml bundle exec rake epub + +# VivliostyleによるPDFの生成 +$ REVIEW_CONFIG_FILE=config-ebook-tate.yml \ + REVIEW_VSCLI_USESANDBOX=true bundle exec rake vivliostyle +//} + +なお、できる限りGitHubか、Dockerコンテナ上のLinuxで行うことを推奨いたします。 + +== このテンプレートの仕組み + +このテンプレートは以下の仕組みでPDFを生成します。 + +//graph[shikumi][mermaid][このテンプレートの仕組み]{ +%%{init:{'theme':'neutral'}}%% +graph TD + docx[Microsoft Wordファイル] --> pandoc[Pandoc] + md[Markdownファイル] --> pandoc + pandoc --> review[Re:VIEW] + re[.reファイル] --> review + image[画像ファイル] --> review + scss[.scssファイル] --> sass[Sass] + sass --> css[CSS] + css --> review + review --> epub[EPUB] + review --> uplatex[upLaTeX] + epub --> vivliostyle[Vivliostyle] + vivliostyle --> pdf[PDF] + uplatex --> pdf +//} + +なお、デフォルトではVivliostyleによるPDF生成が選択されていますが、 @{jobs.yml} のコメントアウトを外すことによりupLaTeXでもPDF生成も可能になります。 + +== 対応ファイル形式 + +本文は以下のファイル形式に対応しています。 + + * Re:VIEWフォーマット(.re)形式 + * Markdownファイル + * Microsoft Wordファイル + +なお、Microsoft Wordファイルで設定した書式は全てこのテンプレートの書式に上書きされますのでご注意ください。 + +画像ファイルは以下の形式に対応しています。 + + * PNGファイル + * GIFファイル + * JPEGファイル + +//image[sign][PNG画像]{ +//} + +SVGファイルは対応していません。 + +図表はMermaidで作成した図を入れることができます。Mermaidの図は @{//graph} 命令で取り込むことができます。 + +印刷用PDFでは全て白黒化されます。 + +== 使える書式 + +詳しくは @{https://github.com/kmuto/review/blob/master/doc/format.ja.md,Re:VIEW公式の書式についての説明} をご参照ください。 + +== 以下注意事項 + +ここから先はこのテンプレート独自の注意事項です。 + +=== 対応する紙のサイズ + +以下の紙サイズに対応しています。 + + * A4 + * B5 + * A5 + * A6(文庫サイズ) + * 新書版(縦書きのみ) + +紙のサイズは @{jobs.yml} の @{ENV} の @{SIZE} 項目で設定できます。 + +=== 組み方向 + +縦書きと横書きに対応しています。 + +組み方向を変更するには、以下の2点の設定をする必要があります。 + +まず、 @{config.yml} の @{direction} という項目の設定を変更しましょう。 + +設定項目の値は以下の通りです。 + + : @{rtl} + ページは右から左に流れます。右綴じで、日本語縦書きの本はこちらを指定してください。 + : @{ltr} + ページは左から右に流れます。左綴じで、欧文や日本語横書きの本はこちらを指定してください。 + +その後、 @{jobs.yml} の @{ENV} の @{MUKI} 項目を設定しましょう。これで、組み方向が変わるはずです。 + +=== 対応文字種 + +EPUBおよびVivliostyle版は以下の文字種に対応しています。 + + * ラテン文字 + * ラテン文字拡張 + * キリル文字 + * キリル文字拡張 + * ギリシャ文字 + * ひらがな + * カタカナ + * 漢字 + * ハングル + +なお、漢字は日本の字体で表示されますのでご注意ください。 + +以下は世界の言葉で「こんにちは」を表示させるものです。 + + : 英語 + Hello! + + : 日本語 + こんにちは! + + : 韓国語 + 안녕하세요! + + : 中国語 + 你好! + + : ベトナム語 + Xin chào! + + : モンゴル語 + Сайн байна уу? + + : ギリシャ語 + Γειά σου! + + : ウクライナ語 + Привіт! + + : ポーランド語 + Cześć! + +=== 表紙 + +表紙は350dpiの画像ファイルで作ってください。 + +それぞれに画像サイズを提示いたします。 + + : A4 + 2894 × 4093 ピクセル + : B5 + 2508 × 3541 ピクセル + : A5 + 2039 × 2894 ピクセル + : A6 + 1447 × 2039 ピクセル + : 新書版 + 1557 × 2494 ピクセル + +=== Word文書のスタイル + +消えます。このテンプレートで設定したスタイルに変更されます。 + +なお、文字のサイズを変更する形で見出しを設定すると、地の文になってしまいます。 + +見出しはちゃんと見出しとして設定して使ってください。 + +=== 絵文字 + +一応Cicaフォントに含まれる絵文字は使える……はずです。 + +🍣 ← これはお寿司ですか? + +なおLaTeX版では何も表示されないはずです。 + +=== 索引 + +Re:VIEWには索引という機能がありますが、このテンプレートには対応していません。 + +EPUBからPDFを作るというフローですが、残念ながらEPUBでは索引機能に対応していません。 + +LaTeXなら対応しているのですが……。 + +=== コードブロック + +コードブロックは直前のページで改ページされ、次のページに表示されます。 + +なるべくキャプションを付けることをおすすめします。 + +=== 参考文献 + +参考文献の機能を使うことができます。 + +@{第1巻}、@{第2巻}、@{第3巻} のように指定すると表示されます。 + diff --git a/chapter/markdown.md b/chapter/markdown.md new file mode 100644 index 0000000..29486b0 --- /dev/null +++ b/chapter/markdown.md @@ -0,0 +1,165 @@ +# Markdown文書の変換仕様 + +参考: [https://github.com/kmuto/pandoc2review/blob/main/markdown-format.ja.md](https://github.com/kmuto/pandoc2review/blob/main/markdown-format.ja.md) + +## 基本 + +`config.yml`には拡張子を`.md`ではなく、`.re`で記述する。 + +## 段落 + +Markdownの段落はそのままRe:VIEWでも段落になる。 + +## 空行 + +Re:VIEW の `//blankline` を入れるには、`\` を行末とその次の行の2回記述する。 + +空行にする行に全角スペースを入れるという方法もある。 + +## 見出し + +6レベルまで。 + +## 引用 + +引用はMarkdownの機能がそのまま使えるが、Re:VIEW の `//quote` は段落のみをサポートしているため、段落以外の要素 (箇条書きなど) は期待の出力にならない。 + +なお、引用の入れ子は使えない。 + +> 人生は長い、疲れたら休め。 +> 脇道を行くのも又良し。 +> +> ——エリナとプリン + +## コードブロック + +バッククォート3つで表記する。 + +詳しくは https://github.com/kmuto/pandoc2review/blob/main/markdown-format.ja.md 参照。 + +```typescript {caption="コードブロックの表示"} +const variable = 0; + +if (variable) { + console.log(variable); +} +``` + +## リスト + +- 普通に使える +- 入れ子も…… + - 多分できるかもしれない +- これで良し + +## 順序付きリスト + +1. 順序付きリストは最初の数値を元に採番される + 2. 途中から始めるとその数から始まる + 3. こういうこと +2. `#.` でも機能する + +## 定義リスト + +定義リスト +: 使える + +書き方は以下の通り。 + +```markdown {caption="Markdownでの定義リストの書き方"} +定義リスト +: 使える +``` + +## 水平線 + +使えるらしい。 + +--- + +が、めったに使わないらしい。 + +## 表 + +期待の結果にならないおそれがある。 + +詳しくは https://github.com/kmuto/pandoc2review/blob/main/markdown-format.ja.md 参照。 + +## メタデータブロック + +Frontmatterは使えない。 + +YAMLから参照することはできなくはないかもしれない。詳しくは https://github.com/kmuto/pandoc2review/blob/main/markdown-format.ja.md 参照。 + +## インライン修飾 + +以下のものが使える。 + +- 斜体 `*` +- 太字 `**` +- 取り消し線 `~~` +- 上付き文字 `^` +- 下付き文字 `~` +- バッククォート + +## 数式 + +TeX数式形式が使える。 + +## リンク + +普通に変換される。 + +## 画像 + +キャプションがあるときには //image、ないときには //indepimage に変換される。 + +`images` フォルダに配置する必要があるが、パスを指定するときは省略する。 + +```markdown {caption="Markdownでの画像の貼り方"} +![与謝野晶子](yosano_akiko_is_always_watching_you.png) +``` + +width、height、scale の属性が付けられているときには、scale パラメータに変換される。 + +```markdown {caption="Markdownでのスケール指定しての画像の貼り方"} +![与謝野晶子](yosano_akiko_is_always_watching_you.png){scale=2} +``` + +前また後に文字があるときには、インライン画像と見なし、アイコンに変換される。 + +```markdown {caption="Markdownでのインライン画像の貼り方"} +レターパックで ![与謝野晶子](yosano_akiko_is_always_watching_you.png) 送れ +``` + +レターパックで ![与謝野晶子](yosano_akiko_is_always_watching_you.png) 送れ + +## Div と Span + +HTML の生タグであるブロック `
`、インライン `` の属性情報を使って Re:VIEW の命令に変換できる。 + +縦中横はspanタグを使える。 + +```markdown {caption="MarkdownでのHTMLタグの使用"} +万物のすべての答えは42である。 +``` + +万物のすべての答えは42である。 + +## 脚注 + +脚注[^1]は使える。 + +[^1]: 脚注 + +## 生のHTMLとLaTeX + +使えるらしい。 + +DivタグとSpanタグ以外は生のHTMLとして使える。 + +## 絵文字 + +Cicaフォントに入っているものなら使える……はず。 + +🍣 diff --git a/chapter/postscript.re b/chapter/postscript.re new file mode 100644 index 0000000..2154352 --- /dev/null +++ b/chapter/postscript.re @@ -0,0 +1,32 @@ += あとがき + +これを機に、本を作ってみませんか? + +なお連絡は louisa.vrc@gmail.com までお願いいたします。 + +== カンパしたい方 + +カンパは難しいですが、以下の方法で支援を受け付けております。 + +=== note + +noteでは、以下のプランを開設しています。 + +@{https://note.com/louisa_charlotte/membership} + +=== Amazonのほしいものリスト + +Amazonでは、以下のほしいものリストからプレゼントを贈ることが可能です。 + +//image[amazon_books_qr][@{https://www.amazon.jp/hz/wishlist/ls/QH9G256RU2HN?ref_=wl_share,Amazonの書籍のほしい物リスト}]{ +//} + +//image[amazon_goods_qr][@{https://www.amazon.jp/hz/wishlist/ls/34F3UNKGH92UY?ref_=wl_share,Amazonの書籍以外のほしい物リスト}]{ +//} + +=== BOOTH + +BOOTHのほしい物リストでも、BOOTHでプレゼントを贈ることができます。 + +//image[booth_qr][@{https://booth.pm/wish_list_names/8MBTGjgp,BOOTHのほしい物リスト}]{ +//} \ No newline at end of file diff --git a/chapter/preface.re b/chapter/preface.re new file mode 100644 index 0000000..803b810 --- /dev/null +++ b/chapter/preface.re @@ -0,0 +1,9 @@ += はじめに + +井の頭文芸部で作った、@{https://github.com/kmuto/review,Re:VIEW}で書籍を作るためのテンプレートです。 + +GitHubにあるこのテンプレートを使うことで、印刷に向くPDF文書やEPUBフォーマットの電子書籍を作ることができます。 + +縦書きと横書きに対応しています。 + +使用する前にこの文章をご一読いただけると幸いです。 \ No newline at end of file diff --git a/chapter/word-ref.docx b/chapter/word-ref.docx new file mode 100644 index 0000000..47a319a Binary files /dev/null and b/chapter/word-ref.docx differ diff --git a/colophon.xhtml b/colophon.xhtml new file mode 100644 index 0000000..8a4a5a8 --- /dev/null +++ b/colophon.xhtml @@ -0,0 +1,31 @@ + + + + + + + + 奥付 + + +
+
+
+
+

+ 井の頭文芸部 Re:VIEW テンプレート
縦書き・横書き両用 +

+
    +
  • 2024年9月16日 初版 刊行
  • +
+ + + + +
著者るいざ・しゃーろっと
連絡先るいざ・しゃーろっと < louisa.vrc@gmail.com >
印刷所○○印刷所
+ +
+
+
+ + \ No newline at end of file diff --git a/config-ebook-tate.yml b/config-ebook-tate.yml new file mode 100644 index 0000000..552cc40 --- /dev/null +++ b/config-ebook-tate.yml @@ -0,0 +1,23 @@ +# EPUB・電子書籍PDF用設定ファイル +# 元々の設定ファイルから項目を継承する +inherit: ["config.yml"] + +# 表紙を作る +cover: cover.xhtml + +# 縦書き +direction: "rtl" + +# 裏表紙を作る +backcover: backcover.xhtml + +# 大扉は画像で作る +# XHTMLなので、編集すれば自前の大扉が入る +titlefile: title.xhtml + +# 奥付は自作したXMTMLファイルを使う +colophon: colophon.xhtml + +# 著者紹介は自作したXMTMLファイルを使う +profile: profile.xhtml +profiletitle: 著者紹介 diff --git a/config-ebook-yoko.yml b/config-ebook-yoko.yml new file mode 100644 index 0000000..6e26282 --- /dev/null +++ b/config-ebook-yoko.yml @@ -0,0 +1,23 @@ +# EPUB・電子書籍PDF用設定ファイル +# 元々の設定ファイルから項目を継承する +inherit: ["config.yml"] + +# 横書き +direction: "ltr" + +# 表紙を作る +cover: cover.xhtml + +# 裏表紙を作る +backcover: backcover.xhtml + +# 大扉は画像で作る +# XHTMLなので、編集すれば自前の大扉が入る +titlefile: title.xhtml + +# 奥付は自作したXMTMLファイルを使う +colophon: colophon.xhtml + +# 著者紹介は自作したXMTMLファイルを使う +profile: profile.xhtml +profiletitle: 著者紹介 \ No newline at end of file diff --git a/config-epub-tate.yml b/config-epub-tate.yml new file mode 100644 index 0000000..e2c3781 --- /dev/null +++ b/config-epub-tate.yml @@ -0,0 +1,28 @@ +# EPUB・電子書籍PDF用設定ファイル +# 元々の設定ファイルから項目を継承する +inherit: ["config.yml"] + +# 表紙を作る +cover: cover.xhtml +coverimage: frontcover.png +epubmaker: + cover_linear: yes + +# 縦書き +direction: "rtl" + +# 裏表紙を作る +backcover: backcover.xhtml + +# 大扉は画像で作る +# XHTMLなので、編集すれば自前の大扉が入る +titlefile: title.xhtml + +# 奥付は自作したXMTMLファイルを使う +colophon: colophon.xhtml + +# 著者紹介は自作したXMTMLファイルを使う +profile: profile.xhtml +profiletitle: 著者紹介 + +debug: true \ No newline at end of file diff --git a/config-epub-yoko.yml b/config-epub-yoko.yml new file mode 100644 index 0000000..5fb8f2d --- /dev/null +++ b/config-epub-yoko.yml @@ -0,0 +1,26 @@ +# EPUB・電子書籍PDF用設定ファイル +# 元々の設定ファイルから項目を継承する +inherit: ["config.yml"] + +# 横書き +direction: "ltr" + +# 表紙を作る +cover: cover.xhtml +coverimage: frontcover.png +epubmaker: + cover_linear: yes + +# 裏表紙を作る +backcover: backcover.xhtml + +# 大扉は画像で作る +# XHTMLなので、編集すれば自前の大扉が入る +titlefile: title.xhtml + +# 奥付は自作したXMTMLファイルを使う +colophon: colophon.xhtml + +# 著者紹介は自作したXMTMLファイルを使う +profile: profile.xhtml +profiletitle: 著者紹介 \ No newline at end of file diff --git a/config-latex-pdf.yml b/config-latex-pdf.yml new file mode 100644 index 0000000..b32fe1e --- /dev/null +++ b/config-latex-pdf.yml @@ -0,0 +1,134 @@ +# upLaTexによるPDF用設定ファイル +# 元々の設定ファイルから項目を継承する +inherit: ["config.yml"] + +# 印刷所 +prt: ○○印刷所 + +# 表紙を作る場合はコメントを外す。 +# コメントアウトした場合は表紙は作られない。 +# cover: cover.tex + +# 裏表紙を作る場合はコメントを外す。 +# コメントアウトした場合は裏表紙は作られない。 +# backcover: backcover.tex + +# 大扉は作る +titlepage: true + +# 大扉で画像を使う場合はコメントを外す。 +# コメントアウトした場合はupLaTexによる大扉となる。 +# titlefile: title.tex + +# 奥付はデフォルトのものを使う +colophon: true + +# LaTeX用のスタイルファイル(styディレクトリ以下に置くこと) +texstyle: ["reviewmacro"] + +# LaTeX用のdocumentclassを指定する +# オプションについてはsty/README.mdを参照 +# デフォルトは印刷用。電子配布版を作るには media=ebook とする +texdocumentclass: ["review-jlreq", "media=print,paper=a6,fontsize=8pt,baselineskip=1.4,head_space=17mm,foot_space=15mm,gutter=18mm,fore_edge=12mm,serial_pagination=true,hiddenfolio=shippo,startpage=3,tate,twoside,onecolumn,openany"] # 印刷用 +# texdocumentclass: ["review-jlreq", "media=ebook,paper=a6,fontsize=8pt,baselineskip=1.4,head_space=17mm,foot_space=15mm,gutter=18mm,fore_edge=12mm,serial_pagination=true,tate,twoside,onecolumn"] # 電子配布用 + +# LaTeX用のdvi変換コマンドのオプションを指定する。変換が遅い場合は`-d 5 -z 3`等にする +# dvioptions: "-d 5 -z 9" +dvioptions: "-d 5 -z 9 -r 600" + +# 以下のパラメータを有効にするときには、 +# pdfmaker: +# パラメータ: 値 +# パラメータ: 値 +# ... +# という構成にする必要がある(インデントさせる) +# +pdfmaker: + # + # TeX版で利用する表紙画像。 + # 仕上がりサイズ+塗り足し3mmありのPDFまたはIllustratorファイル(PDF互換オプション付き)を推奨。 + # 拡縮はされず「そのまま」貼り付けられる + coverimage: null + # + # TeXコンパイル前に実行するプログラム。変換後のTeXソースを調整したいときに使用する。 + # 渡される引数1=作業用展開ディレクトリ、引数2=呼び出しを実行したディレクトリ + # hook_beforetexcompile: null + # + # 索引処理前に実行するプログラム。idxファイルを加工したいときなどに使用する。 + # 渡される引数1=作業用展開ディレクトリ、引数2=呼び出しを実行したディレクトリ + # hook_beforemakeindex: null + # + # 索引処理後に実行するプログラム。indファイルを加工したいときなどに使用する。 + # 渡される引数1=作業用展開ディレクトリ、引数2=呼び出しを実行したディレクトリ + # hook_aftermakeindex: null + # + # ひととおりのコンパイル後に実行するプログラム。目次を加工して再度コンパイルしたいときなどに使用する。 + # 渡される引数1=作業用展開ディレクトリ、引数2=呼び出しを実行したディレクトリ + # hook_aftertexcompile: null + # + # PDF(__REVIEW_BOOK__.pdf)作成後に実行するプログラム。PDFに加工を施したいときに使用する。 + # 渡される引数1=作業用展開ディレクトリ、引数2=呼び出しを実行したディレクトリ + # hook_afterdvipdf: null + # + # 画像のscale=X.Xという指定を画像拡大縮小率からページ最大幅の相対倍率に変換する + # image_scale2width: true + # + # 画像のデフォルトのサイズを、版面横幅合わせではなく、原寸をそのまま利用する + # use_original_image_size: null + # + # PDFやIllustratorファイル(.ai)の画像のBoudingBoxの抽出に指定のボックスを採用する + # cropbox(デフォルト), mediabox, artbox, trimbox, bleedboxから選択する。 + # Illustrator CC以降のIllustratorファイルに対してはmediaboxを指定する必要がある + # bbox: mediabox + # + # 索引を作成するか。trueにすると索引作成が有効になる + # makeindex: null + makeindex: true + # 索引作成コマンド + # makeindex_command: mendex + # 索引作成コマンドのオプション + # makeindex_options: "-f -r -I utf8" + # 索引作成コマンドのスタイルファイル + makeindex_sty: index.ist + # 索引作成コマンドの辞書ファイル + # makeindex_dic: null + makeindex_dic: sakuin.dic + # MeCabによる索引読み探索を使うか + makeindex_mecab: true + # MeCabの読みの取得オプション + makeindex_mecab_opts: "-Oyomi" + # 奥付を作成するか。trueを指定するとデフォルトの奥付、ファイル名を指定するとそれがcolophon.htmlとしてコピーされる + colophon: true + # 表紙挿入時に表紙のページ番号名を「cover」とし、偶数ページ扱いにして大扉前に白ページが入るのを防ぐ。デフォルトはtrue + # use_cover_nombre: true + # + # 囲み表現の切り替え設定 + # column, note, memo, tip, info, warning, important, caution, noticeを設定可 + # styleはreview-tcbox.styまたは独自に作成したスタイルで定義済みの囲みスタイル名 + # optionsはキャプションなし囲みに対するtcolorboxの追加・上書きオプション + # options_with_captionはキャプション付き囲みのtcolorboxの追加・上書きオプション(省略した場合はoptionsと同じ) + # + boxsetting: + column: + style: marker + note: + style: marker + memo: + style: marker + tip: + style: marker + info: + style: marker + warning: + style: marker + important: + style: marker + caution: + style: marker + notice: + style: marker + # style: squarebox + # options: "colback=black!5!white" + # options_with_caption: "colbacktitle=black!25!white" + # + # pdfmaker:階層を使うものはここまで \ No newline at end of file diff --git a/config-print-tate.yml b/config-print-tate.yml new file mode 100644 index 0000000..92f1e26 --- /dev/null +++ b/config-print-tate.yml @@ -0,0 +1,28 @@ +# 印刷PDF用設定ファイル +# 元々の設定ファイルから項目を継承する +inherit: ["config.yml"] + +# 印刷所の名前を設定する +prt: ○○印刷所 + +# 縦書き +direction: "rtl" + +# 表紙と裏表紙は作らない +cover: false + +# 大扉は画像で作る +titlefile: title.xhtml + +# 奥付は自作したXMTMLファイルを使う +colophon: colophon.xhtml + +# 著者紹介は自作したXMTMLファイルを使う +profile: profile.xhtml +profiletitle: 著者紹介 + +# 目次の章立ての部分にリンクを作らない +chapterlink: null + +# 外部リンクを無効にする +externallink: false \ No newline at end of file diff --git a/config-print-yoko.yml b/config-print-yoko.yml new file mode 100644 index 0000000..3cc406e --- /dev/null +++ b/config-print-yoko.yml @@ -0,0 +1,28 @@ +# 印刷PDF用設定ファイル +# 元々の設定ファイルから項目を継承する +inherit: ["config.yml"] + +# 横書き +direction: "ltr" + +# 印刷所の名前を設定する +prt: ○○印刷所 + +# 表紙と裏表紙は作らない +cover: false + +# 大扉は画像で作る +titlefile: title.xhtml + +# 奥付は自作したXMTMLファイルを使う +colophon: colophon.xhtml + +# 著者紹介は自作したXMTMLファイルを使う +profile: profile.xhtml +profiletitle: 著者紹介 + +# 目次の章立ての部分にリンクを作らない +chapterlink: null + +# 外部リンクを無効にする +externallink: false \ No newline at end of file diff --git a/config-udonbook-tate.yml b/config-udonbook-tate.yml new file mode 100644 index 0000000..3734cc4 --- /dev/null +++ b/config-udonbook-tate.yml @@ -0,0 +1,24 @@ +# 印刷PDF用設定ファイル +# 元々の設定ファイルから項目を継承する +inherit: ["config.yml"] + +# 印刷所の名前は設定しない + +# 表紙と裏表紙は作らない +cover: false + +# 大扉は画像で作る +titlefile: title.xhtml + +# 奥付は自作したXMTMLファイルを使う +colophon: colophon.xhtml + +# 著者紹介は自作したXMTMLファイルを使う +profile: profile.xhtml +profiletitle: 著者紹介 + +# 目次の章立ての部分にリンクを作らない +chapterlink: null + +# 外部リンクを無効にする +externallink: false \ No newline at end of file diff --git a/config-udonbook-yoko.yml b/config-udonbook-yoko.yml new file mode 100644 index 0000000..9685ded --- /dev/null +++ b/config-udonbook-yoko.yml @@ -0,0 +1,27 @@ +# 印刷PDF用設定ファイル +# 元々の設定ファイルから項目を継承する +inherit: ["config.yml"] + +# 横書き +direction: "ltr" + +# 印刷所の名前は設定しない + +# 表紙と裏表紙は作らない +cover: false + +# 大扉は画像で作る +titlefile: title.xhtml + +# 奥付は自作したXMTMLファイルを使う +colophon: colophon.xhtml + +# 著者紹介は自作したXMTMLファイルを使う +profile: profile.xhtml +profiletitle: 著者紹介 + +# 目次の章立ての部分にリンクを作らない +chapterlink: null + +# 外部リンクを無効にする +externallink: false \ No newline at end of file diff --git a/config.yml b/config.yml new file mode 100644 index 0000000..eac12ff --- /dev/null +++ b/config.yml @@ -0,0 +1,478 @@ +# review-epubmaker向けの設定ファイルの例。 +# yamlファイルをRe:VIEWファイルのある場所に置き、 +# 「review-epubmaker yamlファイル」を実行すると、.epubファイルが +# 生成されます。 +# このファイルはUTF-8エンコーディングで記述してください。 + +# この設定ファイルでサポートするRe:VIEWのバージョン番号。 +review_version: 5.0 + +# ほかの設定ファイルの継承を指定できる。同じパラメータに異なる値がある場合は、 +# 呼び出し元の値が優先される。 +# A.yml、B.ymlのパラメータを継承する例。A.ymlとB.ymlに同じパラメータがある +# 場合、B.ymlの値が優先される。さらに今このファイルに同じパラメータがあるなら、 +# その値がB.ymlよりも優先される。 +# 同様にA.yml、B.yml内でさらにinherit:パラメータを使うこともできる。 +# inherit: ["A.yml", "B.yml"] + +# ブック名(ファイル名になるもの。ASCII範囲の文字を使用) +bookname: book +# 記述言語。省略した場合はja +language: ja + +# 書名 +# 読みを入れる例 booktitle: {name: "Re:VIEW EPUBサンプル", file-as: "リビューイーパブサンプル"} +booktitle: "井の頭文芸部Re:VIEWテンプレート" +subtitle: "縦書き・横書き両用" + +# 著者名。「, 」で区切って複数指定できる +# 読みを入れる例 aut: [{name: "青木峰郎", file-as: "アオキミネロウ"}, {name: "武藤健志", file-as: "ムトウケンシ"}, {name: "高橋征義", file-as: "タカハシマサヨシ"}, {name: "角征典", file-as: "カドマサノリ"}] +aut: ["るいざ・しゃーろっと"] + +# 以下はオプション +# 以下はオプション(autと同じように配列書式で複数指定可能)。 +# 読みの指定はaut:の例を参照。 +# a-が付いているものはcreator側、 +# 付いていないものはcontributor側(二次協力者)に入る +# a-adp, adp: 異なるメディア向けに作り直した者 +# a-ann, ann: 注釈記述者 +# a-arr, arr: アレンジした者 +# a-art, art: グラフィックデザインおよび芸術家 +# a-asn, asn: 関連・かつての所有者・関係者 +# a-aqt, aqt: 大きく引用された人物 +# a-aft, aft: 後書き・奥付の責任者 +# a-aui, aui: 序論・序文・前書きの責任者 +# a-ant, ant: 目録責任者 +# a-bkp, bkp: メディア制作責任者 +# a-clb, clb: 限定参加または補足者 +# a-cmm, cmm: 解釈・分析・考察者 +# a-csl, csl: 監修者 +# a-dsr, dsr: デザイナ +# a-edt, edt: 編集者 +# a-ill, ill: イラストレータ +# a-lyr, lyr: 歌詞作成者 +# a-mdc, mdc: メタデータセットの一次的責任者 +# a-mus, mus: 音楽家 +# a-nrt, nrt: 語り手 +# a-oth, oth: その他 +# a-pht, pht: 撮影責任者 +# a-pbl, pbl: 出版社(発行所) ※ サークル名はここに設定するとよい +a-pbl: 井の頭文芸部 +# a-prt, prt: 印刷所 ※ 印刷所は config-print.yml で指定する。 +# a-red, red: 項目の枠組起草者 +# a-rev, rev: 評論者 +# a-spn, spn: 援助者 +# a-ths, ths: 監督者 +# a-trc, trc: 筆記・タイプ作業者 +# a-trl, trl: 翻訳者 + +contact: "るいざ・しゃーろっと < louisa.vrc@gmail.com >" + +# 刊行日(省略した場合は実行時の日付) +date: 2024-09-01 +# 発行年月。YYYY-MM-DD形式による配列指定。省略した場合はdateを使用する +# 複数指定する場合は次のように記述する +# [["初版第1刷の日付", "初版第2刷の日付"], ["第2版第1刷の日付"]] +# 日付の後ろを空白文字で区切り、任意の文字列を置くことも可能。 +history: [["二〇二四年九月一日"]] +# 権利表記(配列で複数指定可) +rights: (C) 二〇二四 井の頭文芸部 +# description: 説明 +# subject: 短い説明用タグ(配列で複数指定可) +# type: 書籍のカテゴリーなど(配列で複数指定可) +# format: メディアタイプおよび特徴(配列で複数指定可) +# source: 出版物生成の重要なリソース情報(配列で複数指定可) +# relation: 補助的リソース(配列で複数指定可) +# coverage: 内容の範囲や領域(配列で複数指定可) + +# デバッグフラグ。nullでないときには一時ファイルをカレントディレクトリに作成し、削除もしない +debug: null + +# 固有IDに使用するドメイン。指定しない場合には、時刻に基づくランダムUUIDが入る +# urnid: urn:uuid:http://example.com/book-title/ +# +# ISBN。省略した場合はurnidが入る +# isbn: null +# +# @, @, @, @<hd>命令をハイパーリンクにする(nullでハイパーリンクにしない) +# chapterlink: true + +# HTMLファイルの拡張子(省略した場合はhtml) +# htmlext: html +htmlext: xhtml +# +# CSSファイル(配列で複数指定可) +stylesheet: ["style.css"] + +# ePUBのバージョン (2か3) +epubversion: 3 +# +# HTMLのバージョン (4か5。epubversionを3にしたときには5にする) +htmlversion: 5 + +# 目次として抽出する見出しレベル +toclevel: 1 + +# 採番の設定。採番させたくない見出しには「==[nonum]」のようにnonum指定をする +# +# 本文でセクション番号を表示する見出しレベル +secnolevel: 1 + +# 本文中に目次ページを作成するか。省略した場合はnull (作成しない) +toc: true + +# EPUB2標準の目次(NCX)以外に物理目次ファイルを作成するか。省略した場合はnull (作成しない) +# ePUB3においてはこの設定によらず必ず作成される +# mytoc: true + +# 表紙にするファイル。ファイル名を指定すると表紙として入る (PDFMaker向けにはLaTeXソース断片、EPUBMaker向けにはHTMLファイル) +# cover: cover.xhtml +# +# 表紙に配置し、書籍の影絵にも利用する画像ファイル。省略した場合はnull (画像を使わない)。画像ディレクトリ内に置いてもディレクトリ名は不要(例: cover.jpg) +# PDFMaker 固有の表紙設定は pdfmaker セクション内で上書き可能 +# coverimage: cover.png +# +# 表紙の後に大扉ページを作成するか。省略した場合はtrue (作成する) +# titlepage: false +# +# 自動生成される大扉ページを上書きするファイル。ファイル名を指定すると大扉として入る (PDFMaker向けにはLaTeXソース断片、EPUBMaker向けにはHTMLファイル) +# titlefile: title.xhtml +# +# 原書大扉ページにするファイル。ファイル名を指定すると原書大扉として入る (PDFMaker向けにはLaTeXソース断片、EPUBMaker向けにはHTMLファイル) +# originaltitlefile: null +# +# 権利表記ページファイル。ファイル名を指定すると権利表記として入る (PDFMaker向けにはLaTeXソース断片、EPUBMaker向けにはHTMLファイル) +# creditfile: null + +# 奥付を作成するか。デフォルトでは作成されない。trueを指定するとデフォルトの奥付、ファイル名を指定するとそれがcolophon.htmlとしてコピーされる +# デフォルトの奥付における各項目の名前(「著 者」など)を変えたいときにはlocale.ymlで文字列を設定する(詳細はdoc/format.ja.mdを参照) +# colophon: colophon.xhtml +# デフォルトの奥付における、各項目の記載順序 +# colophon_order: ["aut", "csl", "trl", "dsr", "ill", "cov", "edt", "pbl", "contact", "prt"] + +# 裏表紙データファイル (PDFMaker向けにはLaTeXソース断片、EPUBMaker向けにはHTMLファイル) +# backcover: backcover.xhtml + +# プロフィールページファイル (PDFMaker向けにはLaTeXソース断片、EPUBMaker向けにはHTMLファイル)。ファイル名を指定すると著者紹介として入る +# profile: profile.xhtml +# プロフィールページの目次上の見出し +# profiletitle: 著者紹介 + +# 広告ファイル。ファイル名を指定すると広告として入る (PDFMaker向けにはLaTeXソース断片、EPUBMaker向けにはHTMLファイル) +# advfile: null + +# 取り込む画像が格納されているディレクトリ。省略した場合は以下 +# imagedir: images + +# 取り込むフォントが格納されているディレクトリ。省略した場合は以下 +# fontdir: fonts + +# imagedir内から取り込まれる対象となるファイル拡張子。省略した場合は以下 +# image_ext: ["png", "gif", "jpg", "jpeg", "svg", "ttf", "woff", "otf"] +image_ext: ["png", "gif", "jpg", "jpeg", "svg", "ttf", "woff", "otf"] + +# fontdir内から取り込まれる対象となるファイル拡張子。省略した場合は以下 +# font_ext: ["ttf", "woff", "otf"] + +# ソースコードハイライトを利用する (rouge,pygmentsには外部gemが必要) +highlight: + html: "rouge" +# latex: "listings" + +# カタログファイル名を指定する +# catalogfile: catalog.yml + +# reファイルを格納するディレクトリ。省略した場合は以下 (. はカレントディレクトリを示す) +# contentdir: chapter +contentdir: _refiles + +# @<w>命令で使用する単語ファイルのパス。["common.csv", "mybook.csv"]のように配列指定も可 +# words_file: words.csv + +# //table命令における列の区切り文字。tabs (1文字以上のタブ文字区切り。デフォルト), singletab (1文字のタブ文字区切り), spaces (1文字以上のスペースまたはタブ文字の区切り), verticalbar ("0個以上の空白 | 0個以上の空白"の区切り) +# table_row_separator: tabs + +# 複数行から段落を結合する際、前後のUnicode文字種に基づき必要に応じて空白文字を挿入するか +# 省略した場合はnull (挿入しない)。別途unicode-eaw gemファイルが必要 +# join_lines_by_lang: null + +# 図・表・コードリスト・数式のキャプション位置。 +# 値はtop(上)またはbottom(下)でデフォルトは以下のとおり +# caption_position: +# image: bottom +# table: top +# list: top +# equation: top + +# review-toc向けのヒント情報 +# (文字幅を考慮した行数計測には、別途unicode-eaw gemファイルが必要) +# ページあたりの行数文字数を用紙サイズで指定する(A5 or B5) +# page_metric: A5 +page_metric: A6 +# +# あるいは、配列で指定することもできる +# 各数字の意味は、順にリストの行数、リストの1行字数、テキストの行数、テキストの1行字数 +# page_metric: [40,34,29,34] + +# @<m>, //texequation に記述したTeX数式の表現方法 (PDFMaker (LaTeX) 以外) +# null: TeX式をそのまま文字列として出力 (デフォルト) +# mathml: MathML変換。別途math_ml gemファイルが必要。EPUBMaker/WebMakerのみ効果 +# imgmath: 画像化。オプションはimgmath_optionsで設定する +# mathjax: MathJax変換。EPUBMaker/WebMakerのみ効果。なお、MathJaxに必要なデータはインターネットから取得される。EPUBで利用できるかはEPUBリーダ依存 +math_format: imgmath + +# math_formatがimgmathの場合の設定 +# 以下のパラメータを有効にするときには、 +# imgmath_options: +# パラメータ: 値 +# パラメータ: 値 +# ... +# という構成にする必要がある(インデントさせる) +imgmath_options: + # 使用する画像拡張子。通常は「png」か「svg」(svgの場合は、pdfcrop_pixelize_cmdの-pngも-svgにする) + format: png + # 変換手法。pdfcrop または dvipng + converter: pdfcrop + # プリアンブルの内容を上書きするファイルを指定する(デフォルトはupLaTeX+jsarticle.clsを前提とした、lib/review/makerhelper.rbのdefault_imgmath_preambleメソッドの内容) + # preamble_file: null + # 基準のフォントサイズ + fontsize: 14 + # 基準の行間 + lineheight: 12 + # converterにpdfcropを指定したときのpdfcropコマンドのコマンドライン。プレースホルダは + # %i: 入力ファイル、%o: 出力ファイル + pdfcrop_cmd: "pdfcrop --hires %i %o" + # PDFから画像化するコマンドのコマンドライン。プレースホルダは + # %i: 入力ファイル、%o: 出力ファイル、%O: 出力ファイルから拡張子を除いたもの + # %p: 対象ページ番号、%t: フォーマット + pdfcrop_pixelize_cmd: "pdftocairo -%t -r 90 -f %p -l %p -singlefile %i %O" + # pdfcrop_pixelize_cmdが複数ページの処理に対応していない場合に単ページ化するか + extract_singlepage: true + # extract_singlepageがtrueの場合に単ページ化するコマンドのコマンドライン + pdfextract_cmd: "pdfjam -q --outfile %o %i %p" + # converterにdvipngを指定したときのdvipngコマンドのコマンドライン + # dvipng_cmd: "dvipng -T tight -z 9 -p %p -l %p -o %o %i" + # + # PDFで保存したいときにはたとえば以下のようにする + # format: pdf + # extract_singlepage: true + # pdfextract_cmd: "pdftk A=%i cat A%p output %o" + # pdfcrop_pixelize_cmd: "mv %i %o" + +# EPUBにおけるページ送りの送り方向、page-progression-directionの値("ltr"|"rtl"|"default") +direction: "ltr" # 横書き用 +# direction: "rtl" # 縦書き用 + +# EPUBのOPFへの固有の追加ルール +# <package>要素に追加する名前空間 +# opf_prefix: {ebpaj: "http://www.ebpaj.jp/"} +# 追加する<meta>要素のプロパティとその値 +# opf_meta: {"ebpaj:guide-version": "1.1.3"} + +# 以下のパラメータを有効にするときには、 +# epubmaker: +# パラメータ: 値 +# パラメータ: 値 +# ... +# という構成にする必要がある(インデントさせる) + +epubmaker: + # HTMLファイルの拡張子 + htmlext: xhtml + # + # 目次を要素の階層表現にしない。省略した場合(null)は階層化する。 + # 特に部扉が入るなどの理由で、構成によっては階層化目次でepubcheckに + # パスしない目次ができるが、そのようなときにはこれをtrueにする + # flattoc: null + # + # 目次のインデントレベルをスペース文字で表現する(flattocがtrueのときのみ) + # flattocindent: true + # + # NCX目次の見出しレベルごとの飾り(配列で設定)。EPUB3ではNCXは作られない + # ncxindent: + #- + #- - + # フックは、各段階で介入したいときのプログラムを指定する。自動で適切な引数が渡される + # プログラムには実行権限が必要 + # ファイル変換処理の前に実行するプログラム。スタイルシートのコンパイルをしたいときなどに利用する。 + # 渡される引数1=作業用展開ディレクトリ + # hook_beforeprocess: null + # + # 前付の作成後に実行するプログラム。作業用展開ディレクトリにある目次ファイル(toc-html.txt)を操作したいときなどに利用する。 + # 渡される引数1=作業用展開ディレクトリ + # hook_afterfrontmatter: null + # + # 本文の変換後に実行するプログラム。作業用展開ディレクトリにある目次ファイル(toc-html.txt)を操作したいときなどに利用する。 + # 渡される引数1=作業用展開ディレクトリ + # hook_afterbody: null + # + # 後付の作成後に実行するプログラム。作業用展開ディレクトリにある目次ファイル(toc-html.txt)を操作したいときなどに利用する。 + # 渡される引数1=作業用展開ディレクトリ + # hook_afterbackmatter: null + # + # 画像およびフォントをコピーした後に実行するプログラム。別の画像やフォントを追加したいときなどに利用する。 + # 渡される引数1=作業用展開ディレクトリ + # hook_aftercopyimage: null + # + # ePUB zipアーカイブ直前に実行するプログラム。メタ情報などを加工したいときなどに利用する。 + # 渡される引数1=ePUB準備ディレクトリ + # hook_prepack: null + # + # 変換したHTMLファイルおよびCSSを解析して厳密に使用している画像ファイルだけを取り込むか。デフォルトはnull(imagesディレクトリすべてを取り込む) + # なお、フォント、カバー、広告についてはこの設定によらずディレクトリ内のものがすべて取り込まれる + # verify_target_images: null + # + # verify_target_imagesがtrueの状態において、解析で発見されなくても強制的に取り込むファイルの相対パスの配列 + # force_include_images: [] + # + # 画像ファイルの縦x横の最大ピクセル数許容値 + # image_maxpixels: 4000000 + # + # Re:VIEWファイル名を使わず、前付にpre01,pre02...、本文にchap01,chap02l...、後付にpost01,post02...という名前付けルールにするか + # rename_for_legacy: null + # + # ePUBアーカイブの非圧縮実行 + # zip_stage1: "zip -0Xq" + # + # ePUBアーカイブの圧縮実行 + # zip_stage2: "zip -Xr9Dq" + # + # ePUBアーカイブに追加するパス(デフォルトはmimetype、META-INF、OEBPS) + # zip_addpath: null + # + # EPUBで表紙をコンテンツに含めるか。デフォルトでは作成されない。yesにするとiBooks等でも最初に表紙が表示されるようになる + # cover_linear: yes + # + # @<href>タグでの外部リンクを禁止し、地の文にする(falseで禁止する) + # externallink: true + # + # 脚注に「戻る」リンクを追加する(trueで追加)。脚注の記号および戻るリンクの記号はlocale.ymlで変更可能 + # back_footnote: null + # 見出しに応じて<section>で囲むようにする(trueで<section>を利用) + use_section: true + # epubmaker:階層を使うものはここまで + +# LaTeX用のスタイルファイル(styディレクトリ以下に置くこと) +texstyle: ["reviewmacro"] +# +# LaTeX用のdocumentclassを指定する +# オプションについてはsty/README.mdを参照 +# デフォルトは印刷用。電子配布版を作るには media=ebook とする +# texdocumentclass: ["review-jsbook", "paper=b5,serial_pagination=true,cameraready=ebook,cover=false,hiddenfolio=shippo,fontsize=10pt,line_length=40zw,number_of_lines=34,baselineskip=25.5H"] +# texdocumentclass: ["review-jlreq", "media=print,paper=b5,fontsize=10pt,serial_pagination=true,hiddenfolio=shippo,startpage=3,tate,twoside,onecolumn,openany"] +# +# LaTeX用のコマンドを指定する +# texcommand: "uplatex" +# +# LaTeXのコマンドに渡すオプションを指定する +# texoptions: "-interaction=nonstopmode -file-line-error -halt-on-error" +# +# LaTeX用のdvi変換コマンドを指定する(dvipdfmx) +# dvicommand: "dvipdfmx" +# +# LaTeX用のdvi変換コマンドのオプションを指定する。変換が遅い場合は`-d 5 -z 3`等にする +# dvioptions: "-d 5 -z 9" +# dvioptions: "-d 5 -z 9 -r 600" + +# # 以下のパラメータを有効にするときには、 +# # pdfmaker: +# # パラメータ: 値 +# # パラメータ: 値 +# # ... +# # という構成にする必要がある(インデントさせる) +# # +# pdfmaker: +# # +# # TeX版で利用する表紙画像。 +# # 仕上がりサイズ+塗り足し3mmありのPDFまたはIllustratorファイル(PDF互換オプション付き)を推奨。 +# # 拡縮はされず「そのまま」貼り付けられる +# coverimage: null +# # +# # TeXコンパイル前に実行するプログラム。変換後のTeXソースを調整したいときに使用する。 +# # 渡される引数1=作業用展開ディレクトリ、引数2=呼び出しを実行したディレクトリ +# # hook_beforetexcompile: null +# # +# # 索引処理前に実行するプログラム。idxファイルを加工したいときなどに使用する。 +# # 渡される引数1=作業用展開ディレクトリ、引数2=呼び出しを実行したディレクトリ +# # hook_beforemakeindex: null +# # +# # 索引処理後に実行するプログラム。indファイルを加工したいときなどに使用する。 +# # 渡される引数1=作業用展開ディレクトリ、引数2=呼び出しを実行したディレクトリ +# # hook_aftermakeindex: null +# # +# # ひととおりのコンパイル後に実行するプログラム。目次を加工して再度コンパイルしたいときなどに使用する。 +# # 渡される引数1=作業用展開ディレクトリ、引数2=呼び出しを実行したディレクトリ +# # hook_aftertexcompile: null +# # +# # PDF(__REVIEW_BOOK__.pdf)作成後に実行するプログラム。PDFに加工を施したいときに使用する。 +# # 渡される引数1=作業用展開ディレクトリ、引数2=呼び出しを実行したディレクトリ +# # hook_afterdvipdf: null +# # +# # 画像のscale=X.Xという指定を画像拡大縮小率からページ最大幅の相対倍率に変換する +# # image_scale2width: true +# # +# # 画像のデフォルトのサイズを、版面横幅合わせではなく、原寸をそのまま利用する +# # use_original_image_size: null +# # +# # PDFやIllustratorファイル(.ai)の画像のBoudingBoxの抽出に指定のボックスを採用する +# # cropbox(デフォルト), mediabox, artbox, trimbox, bleedboxから選択する。 +# # Illustrator CC以降のIllustratorファイルに対してはmediaboxを指定する必要がある +# # bbox: mediabox +# # +# # 索引を作成するか。trueにすると索引作成が有効になる +# # makeindex: null +# makeindex: true +# # 索引作成コマンド +# # makeindex_command: mendex +# # 索引作成コマンドのオプション +# # makeindex_options: "-f -r -I utf8" +# # 索引作成コマンドのスタイルファイル +# makeindex_sty: index.ist +# # 索引作成コマンドの辞書ファイル +# # makeindex_dic: null +# makeindex_dic: sakuin.dic +# # MeCabによる索引読み探索を使うか +# makeindex_mecab: true +# # MeCabの読みの取得オプション +# makeindex_mecab_opts: "-Oyomi" +# # 奥付を作成するか。trueを指定するとデフォルトの奥付、ファイル名を指定するとそれがcolophon.htmlとしてコピーされる +# colophon: true +# # 表紙挿入時に表紙のページ番号名を「cover」とし、偶数ページ扱いにして大扉前に白ページが入るのを防ぐ。デフォルトはtrue +# # use_cover_nombre: true +# # +# # 囲み表現の切り替え設定 +# # column, note, memo, tip, info, warning, important, caution, noticeを設定可 +# # styleはreview-tcbox.styまたは独自に作成したスタイルで定義済みの囲みスタイル名 +# # optionsはキャプションなし囲みに対するtcolorboxの追加・上書きオプション +# # options_with_captionはキャプション付き囲みのtcolorboxの追加・上書きオプション(省略した場合はoptionsと同じ) +# # +# boxsetting: +# column: +# style: marker +# note: +# style: marker +# memo: +# style: marker +# tip: +# style: marker +# info: +# style: marker +# warning: +# style: marker +# important: +# style: marker +# caution: +# style: marker +# notice: +# style: marker +# # style: squarebox +# # options: "colback=black!5!white" +# # options_with_caption: "colbacktitle=black!25!white" +# # +# # pdfmaker:階層を使うものはここまで + +playwright_options: + playwright_path: "./node_modules/.bin/playwright" + selfcrop: true + pdfcrop_path: "pdfcrop" + pdftocairo_path: "pdftocairo" diff --git a/cover.tex b/cover.tex new file mode 100644 index 0000000..064fa0e --- /dev/null +++ b/cover.tex @@ -0,0 +1 @@ +\includefullpagegraphics[width=\paperwidth,height=\paperheight,keepaspectratio]{images/frontcover.pdf} \ No newline at end of file diff --git a/cover.xhtml b/cover.xhtml new file mode 100644 index 0000000..bd36135 --- /dev/null +++ b/cover.xhtml @@ -0,0 +1,15 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE html> +<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" xmlns:ops="http://www.idpf.org/2007/ops" xml:lang="ja"> +<head> + <meta charset="UTF-8" /> + <link rel="stylesheet" type="text/css" href="style.css" /> + <meta name="generator" content="Re:VIEW" /> + <title>表紙 + + +
+ +
+ + \ No newline at end of file diff --git a/dict/smarthr-prh-basic.yml b/dict/smarthr-prh-basic.yml new file mode 100644 index 0000000..53affdf --- /dev/null +++ b/dict/smarthr-prh-basic.yml @@ -0,0 +1,80 @@ +# SmartHR全体で使われる、基本辞書セット +rules: + - expected: あらかじめ + pattern: 予め + - expected: いたします + pattern: 致します + - expected: いただく + pattern: 頂く + - expected: および + pattern: 及び + - expected: ください + pattern: 下さい + - expected: ご存じ + pattern: ご存知 + - expected: さきほど + pattern: 先程 + - expected: さまざま + pattern: 様々 + - expected: すでに + pattern: 既に + - expected: すなわち + pattern: 即ち + - expected: すべて + pattern: 全て + - expected: そば$1 + pattern: /(? + …… + 1.1.3 +``` + +ただし、Re:VIEW の生成する EPUB は、ファイルやフォルダの構成、スタイルシートの使い方などにおいて電書協ガイドラインには準拠していません。 + +## iBooks ストア +デフォルトでは、iBooks で EPUB を見開きで開くと、左右ページの間に影が入ります。 +これを消すには、次のように指定します。 + +```yaml +opf_prefix: {ibooks: "http://vocabulary.itunes.apple.com/rdf/ibooks/vocabulary-extensions-1.0/"} +opf_meta: {"ibooks:binding": "false"} +``` + +すでにほかの定義があるときには、たとえば次のように追加してください。 + +```yaml +opf_prefix: {ebpaj: "http://www.ebpaj.jp/", ibooks: "http://vocabulary.itunes.apple.com/rdf/ibooks/vocabulary-extensions-1.0/"} +opf_meta: {"ebpaj:guide-version": "1.1.3", "ibooks:binding": "false"} +``` + +## Amazon Kindle + +EPUB を作成したあと、mobi ファイルにする必要があります。これには Amazon が無料で配布している KindleGen を使用します。 + +- https://www.amazon.com/gp/feature.html?ie=UTF8&docId=1000765211 + +OS に合わせたインストーラでインストールした後、`kindlegen EPUBファイル` で mobi ファイルに変換できます。 + +Kindle Previewer にも内包されています。 + +- https://kdp.amazon.co.jp/ja_JP/help/topic/G202131170 + +注意点として、KindleGen は論理目次だけだとエラーを報告します。物理目次ページを付けるために、次のように config.yml に設定します。 + +```yaml +epubmaker: + toc: true +``` + +CSS によっては、Kindle では表現できないことについての警告が表示されることがあります。「Amazon Kindle パブリッシング・ガイドライン」では、使用可能な文字・外部ハイパーリンクの制約・色の使い方・画像サイズなどが詳細に説明されています。 + +- http://kindlegen.s3.amazonaws.com/AmazonKindlePublishingGuidelines_JP.pdf diff --git a/doc/customize_epub.md b/doc/customize_epub.md new file mode 100644 index 0000000..4684a62 --- /dev/null +++ b/doc/customize_epub.md @@ -0,0 +1,70 @@ +# Supporting local rules of EPUB files + +EPUB files that generated by Re:VIEW (review-epubmaker) should be valid in eubcheck in IDPF. + +But some e-book stores have their own rules, so they reject EPUB files by Re:VIEW. To pass their rules, you can customize OPF file with config.yml. + +## EBPAJ EPUB 3 File Creation Guide + +* http://ebpaj.jp/counsel/guide + +EBPAJ, the Electronic Book Publishers Association of Japan, releases the guide for publishers to create EPUB files that make nothing of trouble in major EPUB readers. + +To pass their guide, you can add some settings into config.yml: + +```yaml +opf_prefix: {ebpaj: "http://www.ebpaj.jp/"} +opf_meta: {"ebpaj:guide-version": "1.1.3"} +``` + +With this settings, Re:VIEW generates OPF files with epbaj attributes: + +```xml + + ... + 1.1.3 +``` + +But EPUB files that Re:VIEW generates are not the same of name and structure to EBPAJ guide. + + +## iBookStore + +Without special setting, iBooks has a margin between right page and left page in double-page spread. + +To remove it, you can add some settings in config.yml. + +```yaml +opf_prefix: {ibooks: "http://vocabulary.itunes.apple.com/rdf/ibooks/vocabulary-extensions-1.0/"} +opf_meta: {"ibooks:binding": "false"} +``` + +If you have already some settings, merge them: + +```yaml +opf_prefix: {ebpaj: "http://www.ebpaj.jp/", ibooks: "http://vocabulary.itunes.apple.com/rdf/ibooks/vocabulary-extensions-1.0/"} +opf_meta: {"ebpaj:guide-version": "1.1.3", "ibooks:binding": "false"} +``` + +## Amazon Kindle + +For Kindle, you need to convert EPUB to mobi format using KindleGen, which Amazon distributes. + +- https://www.amazon.com/gp/feature.html?ie=UTF8&docId=1000765211 + +After installation, you can convert EPUB with `kindlegen EPUB file`. + +KindleGen is also included in Kindle Previewer. + +- https://kdp.amazon.co.jp/ja_JP/help/topic/G202131170 + +Note: if there is only a "logical" table of contents, KindleGen reports a strange error. To include "physical" table of contents, set config.yml as follows. + +```yaml +epubmaker: + toc: true +``` + +You may be warned about some CSS can't be handled in Kindle. "Amazon Kindle Publishing Guidelines" describes in detail the usable characters, restrictions on hyperlinks to the outside, usage of colors, image size, and so on. + +- http://kindlegen.s3.amazonaws.com/AmazonKindlePublishingGuidelines_JP.pdf diff --git a/doc/format.ja.md b/doc/format.ja.md new file mode 100644 index 0000000..6317aef --- /dev/null +++ b/doc/format.ja.md @@ -0,0 +1,1277 @@ +# Re:VIEW フォーマットガイド + +Re:VIEW フォーマットの文法について解説します。Re:VIEW フォーマットはアスキー社(現カドカワ)の EWB を基本としながら、一部に RD や各種 Wiki の文法を取り入れて簡素化しています。 + +このドキュメントは、Re:VIEW 5.8 に基づいています。 + +## 段落 + +段落(本文)の間は1行空けて表現します。空けずに次の行を記述した場合は、1つの段落として扱われます。 + +例: + +``` +だんらくだんらく〜〜〜 +この行も同じ段落 + +次の段落〜〜〜 +``` + +* 2行以上空けても、1行空きと同じ意味になります。 +* 空行せずに改行して段落の記述を続ける際、英文の単語間スペースについては考慮されないことに注意してください。Re:VIEW は各行を単純に連結するだけであり、TeX のように前後の単語を判断してスペースを入れるようなことはしません。 + +## 章・節・項・目・段(見出し) + +章・節・項・目といった見出しは「`=`」「`==`」「`===`」「`====`」「`=====`」で表します。7 レベル以上は使えません。`=`のあとにはスペースを入れます。 + +例: + +```review += 章のキャプション + +== 節のキャプション + +=== 項のキャプション + +==== 目のキャプション + +===== 段のキャプション + +====== 小段のキャプション +``` + +見出しは行の先頭から始める必要があります。行頭に空白を入れると、ただの本文と見なされます。 + +また、見出しの前に文があると、段落としてつながってしまうことがあります。このようなときには空行を見出しの前に入れてください。 + +## コラムなど + +節や項の見出しに `[column]` を追加すると以降がコラムとして扱われ、見出しはコラムのキャプションになります。 + +例: + +```review +===[column] コンパイラコンパイラ +``` + +このとき、「=」と「[column]」は間を空けず、必ず続けて書かなければなりません。 + +コラムは、そのコラムのキャプションの見出しと同等か上位のレベル(コラムキャプションが `===` であれば、`=`〜`===`)の見出しが登場するかファイル末尾に達した時点で終了します。これを待たずにコラムを終了する場合は、「`===[/column]`」と記述します(`=`の数はコラムキャプションと対応)。 + +例: + +```review +===[column] コンパイラコンパイラ + +コラムの内容 + +===[/column] +``` + +より下位の見出しを使うことでコラム内に副見出しを入れることができますが、それが必要になるほど長いコラムはそもそも文章構造に問題がある可能性があります。 + +このほか、次のような見出しオプションがあります。 + +* `[nonum]` : これを指定している章・節・項・段には連番を振りません。見出しは目次に含まれます。 +* `[nodisp]` : これを指定している章・節・項・段の見出しは変換結果には表示されず、連番も振りません。ただし、見出しは目次に含まれます。 +* `[notoc]` : これを指定している章・節・項・段には連番を振りません。見出しは目次に含まれません。 + +## 箇条書き + +箇条書き(HTML で言う ul、ビュレット箇条書きともいう)は「` *`」で表現します。ネストは「` **`」のように深さに応じて数を増やします。 + +例: + +``` + * 第1の項目 + ** 第1の項目のネスト + * 第2の項目 + ** 第2の項目のネスト + * 第3の項目 +``` + +箇条書きには行頭に1つ以上の空白が必要です。行頭に空白を入れず「*」と書くと、ただのテキストと見なされるので注意してください。 + +通常の段落との誤った結合を防ぐため、箇条書きの前後には空行を入れることをお勧めします(他の箇条書きも同様)。 + +## 番号付き箇条書き + +番号付きの箇条書き(HTML で言う ol)は「` 1. 〜`」「` 2. 〜`」「` 3. 〜`」のように示します。`1-1` のようなネスト出力は標準では提供していません( `//beginchild` 〜 `//endchild` を使った入れ子の表現は可能です)。 + +例: + +``` + 1. 第1の条件 + 2. 第2の条件 + 3. 第3の条件 +``` + +番号付き箇条書きも、ただの箇条書きと同様、行頭に1つ以上の空白が必要です。 + +数字が実際にそのとおり出るかは、出力を行うソフトウェアに依存します。 + +- HTML (EPUB), TeX: 記入の数字にかかわらず1から始まる番号になります。 +- IDGXML, テキスト: 記入したとおりの番号が出力されます。よって、すべて「1.」にするといった形にしてしまうとおかしな結果になります。 + +HTML (EPUB) や TeX ビルダにおいて最初の番号を 1 ではないものにしたいときには、`//olnum[番号]` を指定します。なお、番号箇条書きの途中の番号を変えることはできません。 + +例: + +``` +//olnum[10] + + 1. この箇条書きの番号は出力ソフトウェア上では10になる + 2. これは11になる + 6. 記入上で飛ばしても連続数で12となる +``` + +## 用語リスト + +用語リスト(HTML で言う dl)は空白→「:」→空白、で始まる行を使って示します。 + +例: + +```review + : Alpha + DEC の作っていた RISC CPU。 + 浮動小数点数演算が速い。 + : POWER + IBM とモトローラが共同製作した RISC CPU。 + 派生として POWER PC がある。 + : SPARC + Sun が作っている RISC CPU。 + CPU 数を増やすのが得意。 +``` + +「`:`」それ自体はテキストではないので注意してください。その後に続く文字列が用語名(HTML での dt 要素)になります。 + +そして、その行以降、空白で始まる行が用語内容(HTML では dd 要素)になります。次の用語名か空行になるまで、1つの段落として結合されます。 + +## ブロック命令とインライン命令 + +見出しと箇条書きは特別な記法でしたが、それ以外の Re:VIEW の命令はほぼ一貫した記法を採用しています。 + +ブロック命令は1〜複数行の段落に対して何らかのアクション(たいていは装飾)を行います。ブロック命令の記法は次のとおりです。 + +``` +//命令[オプション1][オプション2]…{ +対象の内容。本文と同じような段落の場合は空行区切り + … +//} +``` + +オプションを取らなければ単に `//命令{` という開始行になります。いずれにせよ、開始と終了は明確です。オプション内で「]」という文字が必要であれば、`\]` でリテラルを表現できます。 + +亜種として、一切段落を取らないブロック命令もごく少数あります。 + +``` +//命令[オプション1][オプション2]… +``` + +インライン命令は段落、見出し、ブロック内容、一部のブロックのオプション内で利用でき、文字列内の一部に対してアクション(装飾)を行います。 + +``` +@<命令>{対象の内容} +``` + +内容に「}」という文字が必要であれば、`\}` でリテラルを表現できます。なお、内容の末尾を「\」としたい場合は、`\\` と記述する必要があります(たとえば `@{\\}`)。 + +記法および処理の都合で、次のような制約があります。 + +* ブロック命令内には別のブロック命令をネストできません。 +* ブロック命令内には見出しや箇条書きを格納できません。 +* インライン命令には別のインライン命令をネストできません。 + +### インライン命令のフェンス記法 + +インライン命令において `}` や 末尾 `\` を多用したい場合、それぞれ `\}` や `\\` のようにエスケープするのはわずらわしいことがあります。そのようなときには、インライン命令の囲みの `{ }` の代わりに `$ $` あるいは `| |` を使って内容を囲むことで、エスケープ表記せずに記述できます。 + +``` +@<命令>$対象の内容$ +@<命令>|対象の内容| +``` + +例: + +```review +@$\Delta = \frac{\partial^2}{\partial x_1^2}+\frac{\partial^2}{\partial x_2^2} + \cdots + \frac{\partial^2}{\partial x_n^2}$ +@|if (exp) then { ... } else { ... }| +@|\| +``` + +あくまでも代替であり、推奨する記法ではありません。濫用は避けてください。 + +## ソースコードなどのリスト + +ソースコードなどのリストには `//list` を使います。連番を付けたくない場合は先頭に `em`(embedded の略)、行番号を付ける場合は末尾に `num` を付加します。まとめると、以下の4種類になります。 + +* `//list[識別子][キャプション][言語指定]{ 〜 //}` + * 通常のリスト。言語指定は省略できます。 +* `//listnum[識別子][キャプション][言語指定]{ 〜 //}` + * 通常のリストに行番号をつけたもの。言語指定は省略できます。 +* `//emlist[キャプション][言語指定]{ 〜 //}` + * 連番がないリスト。キャプションと言語指定は省略できます。 +* `//emlistnum[キャプション][言語指定]{ 〜 //}` + * 連番がないリストに行番号を付けたもの。キャプションと言語指定は省略できます。 + +例: + +```review +//list[main][main()][c]{ ←「main」が識別子で「main()」がキャプション +int +main(int argc, char **argv) +{ + puts("OK"); + return 0; +} +//} +``` + +例: + +```review +//listnum[hello][ハローワールド][ruby]{ +puts "hello world!" +//} +``` + +例: + +```review +//emlist[][c]{ +printf("hello"); +//} +``` + +例: + +```review +//emlistnum[][ruby]{ +puts "hello world!" +//} +``` + +言語指定は、ハイライトを有効にしたときに利用されます。 + +コードブロック内でもインライン命令は有効です。 + +また本文中で「リスト X.X を見てください」のようにリストを指定する場合は、インライン命令 `@` を使います。`//list` あるいは `//listnum` で指定した識別子を指定し、たとえば「`@{main}`」と表記します。 + +他章のリストを参照するには、後述の「章ID」を指定し、たとえば `@{advanced|main}`(`advanced.re` ファイルの章にあるリスト `main` を参照する)と記述します。 + +### 行番号の指定 + +行番号を指定した番号から始めるには、`//firstlinenum`を使います。 + +例: + +```review +//firstlinenum[100] +//listnum[hello][ハローワールド][ruby]{ +puts "hello world!" +//} +``` + +### ソースコード専用の引用 + +ソースコードを引用するには次のように記述します。 + +例: + +```review +//source[/hello/world.rb]{ +puts "hello world!" # キャプションあり +//} + +//source{ +puts "hello world!" # キャプションなし +//} + +//source[/hello/world.rb][ruby]{ +puts "hello world!" # キャプションあり、ハイライトあり +//} + +//source[][ruby]{ +puts "hello world!" # キャプションなし、ハイライトあり +//} +``` + +ソースコードの引用は、`//emlist` とほぼ同じです。HTML の CSS などでは区別した表現ができます。 + +## 本文中でのソースコード引用 + +本文中でソースコードを引用して記述するには、`code` を使います。 + +例: + +```review +@{p = obj.ref_cnt} +``` + +## コマンドラインのキャプチャ + +コマンドラインの操作を示すときは `//cmd{ 〜 //}` を使います。インライン命令を使って入力箇所を強調するのもよいでしょう。 + +例: + +``` +//cmd{ +$ @{ls /} +//} +``` + +## 図 + +図は `//image{ 〜 //}` で指定します。後述するように、識別子に基づいて画像ファイルが探索されます。 + +ブロック内の内容は単に無視されますが、アスキーアートや、図中の訳語などを入れておくといった使い道があります。 + +例: + +``` +//image[unixhistory][UNIX系OSの簡単な系譜]{ + System V 系列 + +----------- SVr4 --> 各種商用UNIX(Solaris, AIX, HP-UX, ...) +V1 --> V6 --| + +--------- 4.4BSD --> FreeBSD, NetBSD, OpenBSD, ... + BSD 系列 + + --------------> Linux +//} +``` + +3番目の引数として、画像の倍率・大きさを指定することができます。今のところ「scale=X」で倍率(X 倍)を指定でき、HTML、TeX ともに紙面(画面)幅に対しての倍率となります(0.5 なら半分の幅になります)。3番目の引数をたとえば HTML と TeX で分けたい場合は、`html::style="transform: scale(0.5);",latex::scale=0.5` のように `::` でビルダを明示し、`,` でオプションを区切って指定できます。 + +※TeX において原寸からの倍率にしたいときには、`config.yml` に `image_scale2width: false` を指定してください。 + +また、本文中で「図 X.X を見てください」のように図を指定する場合は、インライン命令 `@` を使います。`//image` で指定した識別子を用いて「`@{unixhistory}`」のように記述します(`//image` と `@` でつづりが違うので注意してください)。 + +他章の図を参照するには、リストと同様に「章ID」を指定します。たとえば `@{advanced|unixhistory}`(`advanced.re` ファイルの章にある図 `unixhistory` を参照する)と記述します。 + +### 画像ファイルの探索 + +図として貼り込む画像ファイルは、次の順序で探索され、最初に発見されたものが利用されます。 + +``` +1. ///. +2. //-. +3. //. +4. //. +5. /-. +6. /. +``` + +* `` はデフォルトでは images ディレクトリです。 +* `` は利用しているビルダ名(ターゲット名)で、たとえば `--target=html` としているのであれば、images/html ディレクトリとなります。各 Maker におけるビルダ名は epubmaker および webmaker の場合は `html`、pdfmaker の場合は `latex`、textmaker の場合は `top` です。 +* `` は章 ID です。たとえば ch01.re という名前であれば「ch01」です。 +* `` は //image[〜] の最初に入れた「〜」のことです(つまり、ID に日本語や空白交じりの文字を使ってしまうと、後で画像ファイル名の名前付けに苦労することになります!)。 +* `` は Re:VIEW が自動で判別する拡張子です。ビルダによってサポートおよび優先する拡張子は異なります。 + +各ビルダでは、以下の拡張子から最初に発見した画像ファイルが使われます。 + +* HTMLBuilder (EPUBMaker、WEBMaker)、MARKDOWNBuilder: .png、.jpg、.jpeg、.gif、.svg +* LATEXBuilder (PDFMaker): .ai、.eps、.pdf、.tif、.tiff、.png、.bmp、.jpg、.jpeg、.gif +* それ以外のビルダ・Maker: .ai、.psd、.eps、.pdf、.tif、.tiff、.png、.bmp、.jpg、.jpeg、.gif、.svg + +### インラインの画像挿入 + +段落途中などに画像を貼り込むには、インライン命令の `@{識別子}` を使います。ファイルの探索ルールは同じです。 + +## 番号が振られていない図 + +`//indepimage[ファイル名][キャプション]` で番号が振られていない画像ファイルを生成します。キャプションは省略できます。 + +例: + +``` +//indepimage[unixhistory2] +``` + +同様のことは、`//numberlessimage`でも使えます。 + +例: + +``` +//numberlessimage[door_image_path][扉絵] +``` + +## グラフ表現ツールを使った図 + +`//graph[ファイル名][コマンド名][キャプション]` で各種グラフ表現ツールを使った画像ファイルの生成ができます。キャプションは省略できます。 + +例: gnuplotの使用 + +``` +//graph[sin_x][gnuplot][Gnuplotの使用]{ +plot sin(x) +//} +``` + +コマンド名には、「`graphviz`」「`gnuplot`」「`blockdiag`」「`aafigure`」「`plantuml`」「`mermaid`」のいずれかを指定できます。ツールはそれぞれ別途インストールし、インストール先のフォルダ名を指定することなく実行できる (パスを通す) 必要があります。 + +* Graphviz ( https://www.graphviz.org/ ) : `dot` コマンドへのパスを OS に設定すること +* Gnuplot ( http://www.gnuplot.info/ ) : `gnuplot` コマンドへのパスを OS に設定すること +* Blockdiag ( http://blockdiag.com/ ) : `blockdiag` コマンドへのパスを OS に設定すること。PDF を生成する場合は ReportLab もインストールすること +* aafigure ( https://launchpad.net/aafigure ) : `aafigure` コマンドへのパスを OS に設定すること +* PlantUML ( http://plantuml.com/ ) : `java` コマンドへのパスを OS に設定し、`plantuml.jar` が作業フォルダ、または `/usr/share/plantuml` あるいは `/usr/share/java` フォルダにあること +* Mermaid ( https://mermaid.js.org/ ) : 以下を参照 + +### Mermaid の利用 + +Mermaid は Web ブラウザ上で動作する JavaScript ベースの図形描画ツールです。EPUB や LaTeX 経由の PDF で利用するには、Web ブラウザを内部的に呼び出して画像化する必要があります。現時点で、Linux 以外の動作は確認していません。 + +1. プロジェクトに次のように `package.json` を作成します(既存のファイルがあるときには、`dependencies` に `"playwright"〜` の行を追加します)。 + ``` + { + "name": "book", + "dependencies": { + "playwright": "^1.32.2" + } + } + ``` +2. Playwright ライブラリをインストールします。`npm` がない場合は、[Node.js](https://nodejs.org/) の環境をセットアップしてください。 + ``` + npm install + ``` +3. Playwright ライブラリを Ruby から呼び出すモジュールである [playwright-runner](https://github.com/kmuto/playwright-runner) をインストールします。 + ``` + gem install playwright-runner + ``` +4. (オプション) EPUB には SVG 形式を作成する必要がありますが、SVG に変換するには、[poppler](https://gitlab.freedesktop.org/poppler/poppler) に含まれる `pdftocairo` コマンドが必要です。Debian およびその派生物では以下のようにしてインストールできます。 + ``` + apt install poppler-utils + ``` +5. (オプション) デフォルトでは図の周囲に大きめの余白ができてしまいます。これを詰めるには、TeXLive に含まれる `pdfcrop` コマンドが必要です。Debian およびその派生物では以下のようにしてインストールできます。 + ``` + apt install texlive-extra-utils + ``` + +プロジェクトの `config.yml` を適宜調整します。デフォルト値は以下のとおりです。 + +``` +playwright_options: + playwright_path: "./node_modules/.bin/playwright" + selfcrop: true + pdfcrop_path: "pdfcrop" + pdftocairo_path: "pdftocairo" +``` + +- `playwright_path`: `playwright` コマンドのパスを相対パスまたは絶対パスで指定する +- `selfcrop`: `playwright-runner` の画像切り出しを使う。`pdfcrop` が不要になるが、周囲に余白が生じる。`pdfcrop` を使うときには `false` に設定する +- `pdfcrop_path`: `pdfcrop` コマンドのパス。`selfcrop` が `true` のときには無視される +- `pdftocairo_path`: `pdftocairo` コマンドのパス + +Re:VIEW 側の記法としては `//graph[ID][mermaid][キャプション]` または `//graph[ID][mermaid]` となりますが、この ID に基づき、`images/html/ID.svg`(EPUB の場合)や `images/latex/ID.pdf`(LaTeX PDF の場合)が生成されます。 + +## 表 + +表は `//table[識別子][キャプション]{ 〜 //}` という記法です。ヘッダと内容を分ける罫線は「`------------`」(12個以上の連続する `-` または `=`)を使います。 + +表の各列のセル間は「1つ」のタブで区切ります。空白のセルには「`.`」と書きます。セルの先頭の「`.`」は削除されるので、先頭文字が「`.`」の場合は「`.`」をもう1つ余計に付けてください。たとえば「`.`」という内容のセルは「`..`」と書きます。 + +例: + +``` +//table[envvars][重要な環境変数]{ +名前 意味 +------------------------------------------------------------- +PATH コマンドの存在するディレクトリ +TERM 使っている端末の種類。linux・kterm・vt100など +LANG ユーザのデフォルトロケール。日本語ならja_JP.eucJPやja_JP.utf8 +LOGNAME ユーザのログイン名 +TEMP 一時ファイルを置くディレクトリ。/tmpなど +PAGER manなどで起動するテキスト閲覧プログラム。lessなど +EDITOR デフォルトエディタ。viやemacsなど +MANPATH manのソースを置いているディレクトリ +DISPLAY X Window Systemのデフォルトディスプレイ +//} +``` + +本文中で「表 X.X を見てください」のように表を指定する場合はインライン命令 `@` を使います。たとえば `@
{envvars}` となります。 + +表のセル内でもインライン命令は有効です。 + +「採番なし、キャプションなし」の表は、`//table` ブロック命令に引数を付けずに記述します。 + +``` +//table{ +〜 +//} +``` + +「採番なし、キャプションあり」の表を作りたいときには、`//emtable` ブロック命令を利用します。 + +``` +//emtable[キャプション]{ +〜 +//} +``` + +### 表の列幅 + +LaTeX および IDGXML のビルダを利用する場合、表の各列の幅を `//tsize` ブロック命令で指定できます。 + +``` +//tsize[|ビルダ|1列目の幅,2列目の幅,……] +``` + +* 列の幅は mm 単位で指定します。 +* IDGXML の場合、3列のうち1列目だけ指定したとすると、省略した残りの2列目・3列目は紙面版面の幅の残りを等分した幅になります。1列目と3列目だけを指定する、といった指定方法はできません。 +* LaTeX の場合、すべての列について漏れなく幅を指定する必要があります。 +* LaTeX の場合、「`//tsize[|latex||p{20mm}cr|]`」のように LaTeX の table マクロの列情報パラメータを直接指定することもできます。 +* その他のビルダ (HTML など) においては、この命令は単に無視されます。 + +### 複雑な表 + +現時点では表のセルの結合や、中央寄せ・右寄せなどの表現はできません。 + +複雑な表については、画像を貼り込む `imgtable` ブロック命令を代わりに使用する方法もあります。`imgtable` の表は通常の表と同じく採番され、インライン命令 `@
` で参照できます。 + +例: + +``` +//imgtable[complexmatrix][複雑な表]{ +complexmatrixという識別子に基づく画像ファイルが貼り込まれる。 +探索ルールはimageと同じ +//} +``` + +## 引用・中央揃え・右揃え + +引用は「`//quote{ 〜 //}`」を使って記述します。 + +例: + +``` +//quote{ +百聞は一見に如かず。 +//} +``` + +複数の段落を入れる場合は、空行で区切ります。 + +中央揃えの段落を表現するには、「`//centering{ 〜 //}`」を使います。同様に右寄せにするには「`//flushright{ 〜 //}`」を使います。複数の段落を入れる場合は、空行で区切ります。 + +例: + +``` +//centering{ +これは + +中央合わせ +//} + +//flushright{ +これは + +右寄せ合わせ +//} +``` + +## 囲み記事 + +技術書でよくある、コラムにするほどではないけれども本文から独立したちょっとした記事を入れるために、以下の命令があります。 + +* `//note[キャプション]{ 〜 //}` : ノート +* `//memo[キャプション]{ 〜 //}` : メモ +* `//tip[キャプション]{ 〜 //}` : Tips +* `//info[キャプション]{ 〜 //}` : 情報 +* `//warning[キャプション]{ 〜 //}` : 注意 +* `//important[キャプション]{ 〜 //}` : 重要 +* `//caution[キャプション]{ 〜 //}` : 警告 +* `//notice[キャプション]{ 〜 //}` : 注意 + +いずれも `[キャプション]` は省略できます。 + +内容には、空行で区切って複数の段落を記述可能です。 + +Re:VIEW 5.0 以降では、囲み記事に箇条書きや図表・リストを含めることもできます。 + +``` +//note{ + +箇条書きを含むノートです。 + + 1. 箇条書き1 + 2. 箇条書き2 + +//} +``` + +## 脚注 + +脚注は「`//footnote`」を使って記述します。 + +例: + +``` +パッケージは本書のサポートサイトから入手できます@{site}。 +各自ダウンロードしてインストールしておいてください。 + +//footnote[site][本書のサポートサイト: http://i.loveruby.net/ja/stdcompiler ] +``` + +本文中のインライン命令「`@{site}`」は脚注番号に置換され、「本書のサポートサイト……」という文は実際の脚注に変換されます。 + +注意: TeX PDF において、コラムの中で脚注を利用する場合、`//footnote` 行はコラムの終わり(`==[/column]` など)の後ろに記述することをお勧めします。Re:VIEW の標準提供のコラム表現では問題ありませんが、サードパーティのコラムの実装によってはおかしな採番表現になることがあります。 + +### footnotetext オプション +TeX PDF において、コラム以外の `//note` などの囲み記事の中で「`@{~}`」を使うには、`footnotetext` オプションを使う必要があります。 + +`footnotetext` オプションを使うには、`config.yml` ファイルに`footnotetext: true` を追加します。 + +ただし、通常の脚注(footnote)ではなく、footnotemark と footnotetext を使うため、本文と脚注が別ページに分かれる可能性があるなど、いろいろな制約があります。また、採番が別々になるため、footnote と footnotemark/footnotetext を両立させることはできません。 + +## 後注 + +後注(最後にまとめて出力される注釈)は、「`//endnote`」を使って記述します。 + +``` +パッケージは本書のサポートサイトから入手できます@{site}。 +各自ダウンロードしてインストールしておいてください。 + +//endnote[site][本書のサポートサイト: http://i.loveruby.net/ja/stdcompiler ] +``` + +本文中のインライン命令「`@{site}`」は後注番号に置換され、「本書のサポートサイト……」という文は後注として内部に保存されます。 + +保存されている後注を書き出すには、書き出したい箇所(通常は章の末尾)に「`//printendnotes`」を置きます。 + +``` + … + +==== 注釈 + +//printendnotes +``` + +後注の管理は章 (re ファイル) 単位であり、複数の章にまたがった後注を作ることはできません。 + +## 参考文献の定義 + +参考文献は同一ディレクトリ内の `bib.re` ファイルに定義します。 + +``` +//bibpaper[cite][キャプション]{…コメント…} +``` + +コメントは省略できます。 + +``` +//bibpaper[cite][キャプション] +``` + +例: + +``` +//bibpaper[lins][Lins, 1991]{ +Refael D. Lins. A shared memory architecture for parallel study of +algorithums for cyclic reference_counting. Technical Report 92, +Computing Laboratory, The University of Kent at Canterbury , August +1991 +//} +``` + +本文中で参考文献を参照したい場合は、インライン命令 `@` を使い、次のようにします。 + +例: + +``` +…という研究が知られています(@{lins})。 +``` + +## リード文 + +リード文は `//lead{ 〜 //}` で指定します。歴史的経緯により、`//read{ 〜 //}` も使用可能です。 + +例: + +``` +//lead{ +本章ではまずこの本の概要について話し、 +次にLinuxでプログラムを作る方法を説明していきます。 +//} +``` + +空行区切りで複数の段落を記述することもできます。 + +## TeX 式 + +LaTeX の式を挿入するには、`//texequation{ 〜 //}` を使います。 + +例: + +``` +//texequation{ +\sum_{i=1}^nf_n(x) +//} +``` + +「式1.1」のように連番を付けたいときには、識別子とキャプションを指定します。 + +``` +//texequation[emc][質量とエネルギーの等価性]{ +\sum_{i=1}^nf_n(x) +//} +``` + +参照するにはインライン命令 `@` を使います(たとえば `@{emc}`)。 + +インライン命令では `@{〜}` を使います。インライン命令の式中に「}」を含む場合、`\}` とエスケープする必要があることに注意してください(`{` はエスケープ不要)。長い式を書くときにはフェンス記法(`@$〜$` または `@|〜|`)を使うと、エスケープが不要になり、記述が楽になります。「インライン命令のフェンス記法」を参照してください。 + +LaTeX の数式が正常に整形されるかどうかは処理系に依存します。LaTeX を利用する PDFMaker では問題なく利用できます。 + +EPUBMaker および WEBMaker では、MathML に変換する方法、MathJax に変換する方法、画像化する方法から選べます。 + +### MathML の場合 +MathML ライブラリをインストールしておきます(`gem install math_ml`)。 + +さらに config.yml に以下のように指定します。 + +``` +math_format: mathml +``` + +なお、MathML で正常に表現されるかどうかは、ビューアやブラウザに依存します。 + +### MathJax の場合 +config.yml に以下のように指定します。 + +``` +math_format: mathjax +``` + +MathJax の JavaScript モジュールはインターネットから読み込まれます。現時点で EPUB の仕様では外部からの読み込みを禁止しているため、MathJax を有効にすると EPUB ファイルの検証を通りません。また、ほぼすべての EPUB リーダーで MathJax は動作しません。CSS 組版との組み合わせでは利用できる可能性があります。 + +### 画像化の場合 + +LaTeX を内部で呼び出し、外部ツールを使って画像化する方法です。画像化された数式は、`images/_review_math` フォルダに配置されます。 + +TeXLive などの LaTeX 環境が必要です。必要に応じて config.yml の `texcommand`、`texoptions`、`dvicommand`、`dvioptions` のパラメータを調整します。 + +さらに、画像化するための外部ツールも用意します。現在、以下の2つのやり方をサポートしています。 + +- `pdfcrop`:TeXLive に収録されている `pdfcrop` コマンドを使用して数式部分を切り出し、さらに PDF から画像化します。デフォルトでは画像化には Poppler ライブラリに収録されている `pdftocairo` コマンドを使用します(コマンドラインで利用可能であれば、別のツールに変更することもできます)。 +- `dvipng`:[dvipng](https://ctan.org/pkg/dvipng) を使用します。OS のパッケージまたは `tlmgr install dvipng` でインストールできます。数式中に日本語は使えません。 + +config.yml で以下のように設定すると、 + +``` +math_format: imgmath +``` + +デフォルト値として以下が使われます。 + +``` +imgmath_options: + # 使用する画像拡張子。通常は「png」か「svg」(svgの場合は、pdfcrop_pixelize_cmdの-pngも-svgにする) + format: png + # 変換手法。pdfcrop または dvipng + converter: pdfcrop + # プリアンブルの内容を上書きするファイルを指定する(デフォルトはupLaTeX+jsarticle.clsを前提とした、lib/review/makerhelper.rbのdefault_imgmath_preambleメソッドの内容) + preamble_file: null + # 基準のフォントサイズ + fontsize: 10 + # 基準の行間 + lineheight: 12 + # pdfcropコマンドのコマンドライン。プレースホルダは + # %i: 入力ファイル、%o: 出力ファイル + pdfcrop_cmd: "pdfcrop --hires %i %o" + # PDFから画像化するコマンドのコマンドライン。プレースホルダは + # %i: 入力ファイル、%o: 出力ファイル、%O: 出力ファイルから拡張子を除いたもの + # %p: 対象ページ番号、%t: フォーマット + pdfcrop_pixelize_cmd: "pdftocairo -%t -r 90 -f %p -l %p -singlefile %i %O" + # pdfcrop_pixelize_cmdが複数ページの処理に対応していない場合に単ページ化するか + extract_singlepage: null + # 単ページ化するコマンドのコマンドライン + pdfextract_cmd: "pdfjam -q --outfile %o %i %p" + # dvipngコマンドのコマンドライン + dvipng_cmd: "dvipng -T tight -z 9 -p %p -l %p -o %o %i" +``` + +たとえば SVG を利用するには、次のようにします。 + +``` +math_format: imgmath +imgmath_options: + format: svg + pdfcrop_pixelize_cmd: "pdftocairo -%t -r 90 -f %p -l %p %i %o" +``` + +デフォルトでは、pdfcrop_pixelize_cmd に指定するコマンドは、1ページあたり1数式からなる複数ページの PDF のファイル名を `%i` プレースホルダで受け取り、`%p` プレースホルダのページ数に基づいて `%o`(拡張子あり)または `%O`(拡張子なし)の画像ファイルに書き出す、という仕組みになっています。 + +単一のページの処理を前提とする `sips` コマンドや `magick` コマンドを使う場合、入力 PDF から指定のページを抽出するように `extract_singlepage: true` として挙動を変更します。単一ページの抽出はデフォルトで TeXLive の `pdfjam` コマンドが使われます。 + +``` +math_format: imgmath +imgmath_options: + extract_singlepage: true + # pdfjamの代わりに外部ツールのpdftkを使う場合(Windowsなど) + pdfextract_cmd: "pdftk A=%i cat A%p output %o" + # ImageMagickを利用する例 + pdfcrop_pixelize_cmd: "magick -density 200x200 %i %o" + # sipsを利用する例 + pdfcrop_pixelize_cmd: "sips -s format png --out %o %i" +``` + +textmaker 向けに PDF 形式の数式ファイルを作成したいときには、たとえば以下のように設定します(ページの抽出には pdftk を利用)。 + +``` +math_format: imgmath +imgmath_options: + format: pdf + extract_singlepage: true + pdfextract_cmd: "pdftk A=%i cat A%p output %o" + pdfcrop_pixelize_cmd: "mv %i %o" +``` + +Re:VIEW 2 以前の dvipng の設定に合わせるには、次のようにします。 + +``` +math_format: imgmath +imgmath_options: + converter: dvipng + fontsize: 12 + lineheight: 14.3 +``` + +## 字下げの制御 + +段落の行頭字下げを制御するタグとして、`//noindent` があります。HTML では `noindent` が `class` 属性に設定されます。 + +## 空行 + +1行ぶんの空行を明示して入れるには、`//blankline` を使います。 + +例: + +``` +この下に1行の空行が入る + +//blankline + +この下に2行の空行が入る + +//blankline +//blankline +``` + +## 見出し参照 +章に対する参照は、次の3つのインライン命令を利用できます。章 ID は、各章のファイル名から拡張子を除いたものです。たとえば `advanced.re` であれば `advanced` が章 ID です。 + +* `@{章ID}` : 「第17章」のような、章番号を含むテキストに置換されます。 +* `@{章ID}` : その章の章題に置換されます。 +* `@<chapref>{章ID}` : 『第17章「さらに進んだ話題」』のように、章番号とタイトルを含むテキストに置換されます。 + +節や項といったより下位の見出しを参照するには、`@<hd>` インライン命令を利用します。見出しの階層を「`|`」で区切って指定します。 + +例: + +``` +@<hd>{はじめに|まずは} +``` + +他の章を参照したい場合は、先頭に章 ID を指定してください。 + +例: + +``` +@<hd>{preface|はじめに|まずは} +``` + +参照先にラベルが設定されている場合は、見出しの代わりに、ラベルで参照します。複雑な階層をとるときにはラベルを使うことを推奨します。 + +``` +=={hajimeni} はじめに +… +=== まずは +… +@<hd>{hajimeni|まずは} +``` + +* `@<hd>{見出しまたはラベル}` あるいは `@<secref>{見出しまたはラベル}` : 『「1.1 まずは」』のように、節項番号とタイトルを含むテキストに置換されます。 +* `@<sec>{見出しまたはラベル}` : 「1.1」のような節項番号に置換されます。番号が付かない箇所の場合はエラーになります。 +* `@<sectitle>{見出しまたはラベル}` : 「まずは」のように、節項のタイトル部に置換されます。 + +### コラム見出し参照 + +コラムの見出しの参照は、インライン命令 `@<column>` を使います。 + +例: + +``` +@<column>{Re:VIEWの用途いろいろ} +``` + +ラベルでの参照も可能です。 + +``` +==[column]{review-application} Re:VIEWの応用 +… +@<column>{review-application} +``` + +## リンク + +Web ハイパーリンクを記述するには、リンクに `@<href>`、アンカーに `//label` を使います。リンクの書式は `@<href>{URL, 文字表現}` で、「`, 文字表現`」を省略すると URL がそのまま使われます。URL 中に `,` を使いたいときには、`\,` とエスケープしてください。 + +例: + +``` +@<href>{http://github.com/, GitHub} +@<href>{http://www.google.com/} +@<href>{#point1, ドキュメント内ポイント} +@<href>{chap1.html#point1, ドキュメント内ポイント} +//label[point1] +``` + +## 単語ファイルの展開 + +キーと値のペアを持つ単語ファイルを用意しておき、キーが指定されたら対応するその値を展開するようにできます。`@<w>{キー}` あるいは `@<wb>{キー}` インライン命令を使います。後者は太字にします。 + +現在、単語ファイルは CSV(コンマ区切り)形式で拡張子 .csv のものに限定されます。1列目にキー、2列目に値を指定して列挙します。 + +``` +"LGPL","Lesser General Public License" +"i18n","""i""nternationalizatio""n""" +``` + +単語ファイルのファイルパスは、`config.yml` に `words_file: ファイルパス` で指定します。`word_file: ["common.csv", "mybook.csv"]` のように複数のファイルも指定可能です(同一のキーがあるときには後に指定したファイルの値が優先されます)。 + +例: + +```review +@<w>{LGPL}, @<wb>{i18n} +``` + +テキストビルダを使用している場合: + +``` +Lesser General Public License, ★"i"nternationalizatio"n"☆ +``` + +展開されるときには、ビルダごとに決められたエスケープが行われます。インライン命令を含めるといったことはできません。 + +## コメント + +最終結果に出力されないコメントを記述するには、「`#@#`」を使います。行末までがコメントとして無視されます。 + +例: + +``` +#@# FIXME: あとで調べておくこと +``` + +最終結果に出力するコメントを記述したい場合は、`//comment` または `@<comment>` を使ったうえで、review-compile コマンドに `--draft` オプションを付けて実行します。 + +例: + +``` +@<comment>{あとで書く} +``` + +## 生データ行 + +Re:VIEW のタグ範囲を超えて何か特別な行を挿入したい場合、`//embed`ブロック命令や `@<embed>` インライン命令を使います。ほかに従来の `//raw` ブロック命令および `@<raw>` インライン命令もありますが、IDGXML ビルダ以外での使用は推奨しません。 + +### `//embed`ブロック + +例: + +``` +//embed{ +<div class="special"> +ここは特別なブロックとして扱われます。 +</div> +//} + +//embed[html,markdown]{ +<div class="special"> +ここはHTMLとMarkdownでは特別なブロックとして扱われます。 +</div> +//} +``` + +`//embed`ブロック命令はブロック内の文字列をそのまま文書中に埋め込みます。エスケープされる文字はありません。 + +オプションとして、ビルダ名を指定できます。ビルダ名には「`html`」「`latex`」「`idgxml`」「`markdown`」「`top`」のいずれかが入ります。ビルダ名は「,」で区切って複数指定することも可能です。該当のビルダを使用しているときのみ、内容が出力されます。異なるビルダを使用している場合は無視されます。 + +オプションを省略した場合、すべてのビルダで文字列が埋め込まれます。 + +例: + +HTMLビルダを使用している場合: + +```html +<div class="special"> +ここは特別なブロックとして扱われます。 +</div> + +<div class="special"> +ここはHTMLとMarkdownでは特別なブロックとして扱われます。 +</div> +``` + +LaTeXビルダを使用している場合: + +```tex +<div class="special"> +ここは特別なブロックとして扱われます +</div> + +``` + +### `//raw`行(IDGXML ビルダ以外では非推奨) + +例: + +``` +//raw[|html|<div class="special">\nここは特別な行です。\n</div>] +``` + +ブロック命令は1つだけオプションをとり、「|ビルダ名|そのまま出力させる内容」という書式です。`\n`は改行文字に変換されます。 + +ビルダ名には「`html`」「`latex`」「`idgxml`」「`markdown`」「`top`」のいずれかが入ります。ビルダ名は「,」で区切って複数指定することも可能です。該当のビルダを使用しているときのみ、内容が出力されます。 + +例: + +``` +(HTMLビルダの場合:) +<div class="special"> +ここは特別な行です。 +</div> + +(ほかのビルダの場合は単に無視されて何も出力されない) +``` + +インライン命令は、`@<raw>{|ビルダ名|〜}` という書式で、記述はブロック命令に同じです。 + +`//raw`、`//embed`、`@<raw>` および `@<embed>` は、HTML、XML や TeX の文書構造を容易に壊す可能性があります。使用には十分に注意してください。 + +### 入れ子の箇条書き + +Re:VIEW の箇条書きは `*` 型の箇条書きを除き、基本的に入れ子を表現できません。いずれの箇条書きも、別の箇条書き、あるいは図表・リストを箇条書きの途中に配置することを許容していません。 + +この対策として、Re:VIEW 4.2 以降では `//beginchild`、`//endchild` というブロック命令があります。箇条書きの途中に何かを含めたいときには、それを `//beginchild` 〜 `//endchild` で囲んで配置します。多重に入れ子にすることも可能です。 + +``` + * UL1 + +//beginchild +#@# ここからUL1の子 + + 1. UL1-OL1 + +//beginchild +#@# ここからUL1-OL1の子 + +UL1-OL1-PARAGRAPH + + * UL1-OL1-UL1 + * UL1-OL1-UL2 + +//endchild +#@# ここまでUL1-OL1の子 + + 2. UL1-OL2 + + : UL1-DL1 + UL1-DD1 + : UL1-DL2 + UL1-DD2 + +//endchild +#@# ここまでUL1の子 + + * UL2 +``` + +これをたとえば HTML に変換すると、次のようになります。 + +``` +<ul> +<li>UL1 +<ol> +<li>UL1-OL1 +<p>UL1-OL1-PARAGRAPH</p> +<ul> +<li>UL1-OL1-UL1</li> +<li>UL1-OL1-UL2</li> +</ul> +</li> + +<li>UL1-OL2</li> +</ol> +<dl> +<dt>UL1-DL1</dt> +<dd>UL1-DD1</dd> +<dt>UL1-DL2</dt> +<dd>UL1-DD2</dd> +</dl> +</li> + +<li>UL2</li> +</ul> +``` + +(試験実装のため、命令名や挙動は今後のバージョンで変更になる可能性があります。) + +## インライン命令 +主なインライン命令を次に示します。 + +### 書体 +書体については、適用するスタイルシートなどによって異なることがあります。 + +* `@<kw>{〜}`, `@<kw>{キーワード, 補足}` : キーワード。通常は太字になることを想定しています。2つめの記法では、たとえば `@<kw>{信任状, credential}` と表記したら「信任状(credential)」のようになります。 +* `@<bou>{〜}` : 傍点が付きます。 +* `@<ami>{〜}` : 文字に対して網がかかります。 +* `@<u>{〜}` : 下線を引きます。 +* `@<b>{〜}` : 太字にします。 +* `@<i>{〜}` : イタリックにします。和文の場合、処理系によってはイタリックがかからないこともあります。 +* `@<strong>{〜}` : 強調(太字)にします。 +* `@<em>{〜}` : 強調にします。 +* `@<tt>{〜}` : 等幅にします。 +* `@<tti>{〜}` : 等幅+イタリックにします。 +* `@<ttb>{〜}` : 等幅+太字にします。 +* `@<code>{〜}` : 等幅にします(コードの引用という性質)。 +* `@<tcy>{〜}` : 縦書きの文書において文字を縦中横にします。 +* `@<ins>{〜}` : 挿入箇所を明示します(デフォルトでは下線が引かれます)。 +* `@<del>{〜}` : 削除箇所を明示します(デフォルトでは打ち消し線が引かれます)。 +* `@<sup>{〜}` : 上付き文字にします。 +* `@<sub>{〜}` : 下付き文字にします。 + +### 参照 +* `@<chap>{章ファイル名}` : 「第17章」のような、章番号を含むテキストに置換されます。 +* `@<title>{章ファイル名}` : その章の章題に置換されます。 +* `@<chapref>{章ファイル名}` : 『第17章「さらに進んだ話題」』のように、章番号とタイトルを含むテキストに置換されます。 +* `@<list>{識別子}` : リストを参照します。 +* `@<img>{識別子}` : 図を参照します。 +* `@<table>{識別子}` : 表を参照します。 +* `@<eq>{識別子}` : 式を参照します。 +* `@<hd>{ラベルまたは見出し}` : 節や項を参照します。 +* `@<column>{ラベルまたは見出し}` : コラムを参照します。 + +### その他 +* `@<ruby>{親文字,ルビ}` : ルビを振ります。たとえば `@<ruby>{愕然,がくぜん}` のように表記します。 +* `@<br>{}` : 段落途中で改行します。濫用は避けたいところですが、表のセル内や箇条書き内などで必要になることもあります。 +* `@<uchar>{番号}` : Unicode文字を出力します。引数は16進数で指定します。 +* `@<href>{URL}`, `@<href>{URL, 文字表現}` : ハイパーリンクを作成します(後述)。 +* `@<icon>{識別子}` : インラインの画像を出力します。 +* `@<m>{数式}` : インラインの数式を出力します。 +* `@<w>{キー}` : キー文字列に対応する、単語ファイル内の値文字列を展開します。 +* `@<wb>{キー}` : キー文字列に対応する、単語ファイル内の値文字列を展開し、太字にします。 +* `@<embed>{|ビルダ|〜}` : 生の文字列を埋め込みます。`\}`は`}`に、`\\`は`\`に置き換えられます(`\n`はそのままです)。 +* `@<raw>{|ビルダ|〜}` : 生の文字列を出力します。`\}`は`}`に、`\\`は`\`に、`\n`は改行に置き換えられます(非推奨)。 +* `@<idx>{文字列}` : 文字列を出力するとともに、索引として登録します。索引の使い方については、makeindex.ja.md を参照してください。 +* `@<hidx>{文字列}` : 索引として登録します (idx と異なり、紙面内に出力はしません)。`親索引文字列<<>>子索引文字列` のように親子関係にある索引も定義できます。 +* `@<balloon>{〜}` : コードブロック (emlist など) 内などでのいわゆる吹き出しを作成します。たとえば「`@<balloon>{ABC}`」とすると、「`←ABC`」となります。デフォルトの挙動および表現は簡素なので、より装飾されたものにするにはスタイルシートを改変するか、`review-ext.rb` を使って挙動を書き換える必要があります。 + +## 著者用タグ(プリプロセッサ命令) + +これまでに説明したタグはすべて最終段階まで残り、見た目に影響を与えます。それに対して以下のタグは著者が使うための専用タグであり、変換結果からは除去されます。 + +* `#@#` : コメント。この行には何を書いても無視されます。 +* `#@warn(〜)` : 警告メッセージ。プリプロセス時にメッセージが出力されます。 +* `#@require`, `#@provide` : キーワードの依存関係を宣言します。 +* `#@mapfile(ファイル名) 〜 #@end` : ファイルの内容をその場に展開します。 +* `#@maprange(ファイル名, 範囲名) 〜 #@end` : ファイル内の範囲をその場に展開します。 +* `#@mapoutput(コマンド) 〜 #@end` : コマンドを実行して、その出力結果を展開します。 + +コメントを除き、プリプロセッサ `review-preproc` コマンドとの併用を前提とします。 + +## 国際化(i18n) + +Re:VIEW が出力する文字列(「第◯章」「図」「表」など)を、指定した言語に合わせて出力することができます。デフォルトは日本語です。 + +ファイルが置かれているディレクトリに `locale.yml` というファイルを用意して、以下のように記述します(日本語の場合)。 + +例: + +``` +locale: ja +``` + +既存の表記を書き換えたい場合は、該当する項目を上書きします。既存の設定ファイルは Re:VIEW の `lib/review/i18n.yml` にあります。 + +例: + +``` +locale: ja +list: 実行例 +``` + +### Re:VIEW カスタムフォーマット + +`locale.yml` ファイルでは、章番号などに以下の Re:VIEW カスタムフォーマットを使用可能です。 + +* `%pA` : アルファベット(大文字)A, B, C, ... +* `%pa` : アルファベット(小文字)a, b, c, ... +* `%pAW` : アルファベット(大文字・いわゆる全角)A, B, C, ... +* `%paW` : アルファベット(小文字・いわゆる全角)a, b, c, ... +* `%pR` : ローマ数字(大文字)I, II, III, ... +* `%pr` : ローマ数字(小文字)i, ii, iii, ... +* `%pRW` : ローマ数字(大文字・単一文字表記)Ⅰ, Ⅱ, Ⅲ, ... +* `%pJ` : 漢数字 一, 二, 三, ... +* `%pdW` : アラビア数字(0〜9まではいわゆる全角、10以降半角)1, 2, ... 10, ... +* `%pDW` : アラビア数字(すべて全角)1, 2, ... 10, ... + +例: + +``` +locale: ja + part: 第%pRW部 + appendix: 付録%pA +``` + +## その他の文法 + +拡張文法は `review-ext.rb` というファイルで指定できます。 + +たとえば、 + +```ruby +# review-ext.rb +ReVIEW::Compiler.defblock :foo, 0..1 +class ReVIEW::HTMLBuilder + def foo(lines, caption = nil) + puts lines.join(",") + end +end +``` + +のような内容のファイルを用意すると、以下のような文法を追加できます。 + +``` +//foo{ +A +B +C +//} +``` + +``` +# 出力結果 +A,B,C +``` + +詳しいことについては、ここでは触れません。 + +## HTML および LaTeX のレイアウト機能 + +ファイルが置かれているディレクトリに layouts/layout.html.erb を置くと、デフォルトの HTML テンプレートの代わりにその HTML が使われます(erb 記法で記述します)。 + +例: + +``` +<html> + <head> + <title><%= @config["booktitle"] %> + + + <%= @body %> +
+ + +``` + +同様に、layouts/layout.tex.erb で、デフォルトの LaTeX テンプレートを置き換えることができます。 diff --git a/doc/format.md b/doc/format.md new file mode 100644 index 0000000..decc7f5 --- /dev/null +++ b/doc/format.md @@ -0,0 +1,1328 @@ +# Re:VIEW Format Guide + +The document is a brief guide for Re:VIEW markup syntax. + +Re:VIEW is based on EWB of ASCII (now KADOKAWA), influenced RD and other Wiki system's syntax. + +This document explains about the format of Re:VIEW 5.8. + +## Paragraph + +Paragraphs are separated by an empty line. + +Usage: + +``` +This is a paragraph, paragraph, +and paragraph. + +Next paragraph here is ... +``` + +Two empty lines or more are same as one empty line. + +## Chapter, Section, Subsection (headings) + +Chapters, sections, subsections, subsubsections use `=`, `==`, `===`, `====`, `=====`, and `======`. +You should add one or more spaces after `=`. + +Usage: + +```review += 1st level (chapter) + +== 2nd level (section) + +=== 3rd level (subsection) + +==== 4th level + +===== 5th level + +====== 6th level +``` + +Headings should not have any spaces before title; if line head has space, it is as paragraph. + +You should add emply lines between Paragraphs and Headings. + +## Column + +`[column]` in a heading are column's caption. + +Usage: + +```review +===[column] Compiler-compiler +``` + +`=` and `[column]` should be closed to. Any spaces are not permitted. + +Columns are closed with next headings. + +``` +== head 01 + +===[column] a column + +== head 02 and the end of 'a column' +``` + +If you want to close column without headings, you can use `===[/column]` + +Usage: + +```review +===[column] Compiler-compiler + +Compiler-compiler is ... + +===[/column] + +blah, blah, blah (this is paragraphs outside of the column) +``` + +There are some more options of headings. + +* `[nonum]` : no numbering, but add it into TOC (Table of Contents). +* `[nodisp]` : not display in document, only in TOC. +* `[notoc]` : no numbering, not in TOC. + +## Itemize + +Itemize (ul in HTML) uses ` *` (one space char and asterisk). + +Nested itemize is like ` **`, ` ***`. + +Usage: + +``` + * 1st item + ** nested 1st item + * 2nd item + ** nested 2nd item + * 3rd item +``` + +In itemize, you must write one more space character at line head. +When you use `*` without spaces in line head, it's just paragraph. + +You should add emply lines between Paragraphs and Itemize (same as Ordered and Non-Orderd). + +## Ordered Itemize + +Ordered itemize (ol in HTML) uses ` 1. ...`, ` 2. ...`, ` 3. ...`. +Nesting output like `1-1` is not supported by default (nesting can be expressed using `//beginchild` - `//endchild`). + +Usage: + +``` + 1. 1st condition + 2. 2nd condition + 3. 3rd condition +``` + +You must write one more space character at line head like itemize. + +Whether the numbers appear as described depends on the software that produces the output. + +* HTML (EPUB), TeX: The number will start from 1 regardless of the number entered. +* IDGXML, text: The numbers will be output as described. Therefore, writing all numbers as "1." will produce strange results. + +In HTML (EPUB) and TeX builders, use `//olnum[number]` to change the first number. Note that the intermediate numbers cannot be changed. + +Usage: + +``` +//olnum[10] + + 1. This number will be 10 + 2. This number will be 11 + 6. 12 in continuity, not 6 or 15. +``` + +## Definition List + +Definition list (dl in HTML) uses ` : ` and indented lines. + +Usage: + +```review + : Alpha + RISC CPU made by DEC. + : POWER + RSIC CPU made by IBM and Motolora. + POWER PC is delivered from this. + : SPARC + RISC CPU made by SUN. +``` + +`:` in line head is not used as a text. +The text after `:` is as the term (dt in HTML). + +In definition list, `:` at line head allow space characters. +After dt line, space-indented lines are descriptions(dd in HTML). + +You can use inline markup in texts of lists. + +## Block Commands and Inline Commands + +With the exception of headings and lists, Re:VIEW supports consistent syntax. + +Block commands are used for multiple lines to add some actions (ex. decoration). + +The syntax of block commands is below: + +``` +//command[option1][option2]...{ +(content lines, sometimes separated by empty lines) + ... +//} +``` + +If there is no options, the begining line is just `//command{`. When you want to use a character `]`, you must use escaping `\]`. + +Some block commands has no content. + +``` +//command[option1][option2]... +``` + +Inline commands are used in block, paragraphes, headings, block contents and block options. + +``` +@{content} +``` + +When you want to use a character `}` in inline content, you must use escaping `\}`. If the content ends with `\`, it must be written `\\`. (ex. `@{\\}`) + +There are some limitations in blocks and inlines. + +* Block commands do not support nestins. You cannot write blocks in another block. +* You cannot write headings and itemize in block contents. +* Inline commands also do not support nestins. You cannot write inlines in another inline. + +### Fence notation for inline commands +You may be tired of escaping when you use a large number of inline commands including `{` and `\`. By surrounding the contents with `$ $` or `| |` instead of `{ }`, you can write without escaping. + +``` +@$content$ +@|content| +``` + +Example: + +```review +@$\Delta = \frac{\partial^2}{\partial x_1^2}+\frac{\partial^2}{\partial x_2^2} + \cdots + \frac{\partial^2}{\partial x_n^2}$ +@|if (exp) then { ... } else { ... }| +@|\| +``` + +Since this notation is substitute, please avoid abuse. + +## Code List + +Code list like source codes is `//list`. If you don't need numbers, you can use ``em`` prefix (as embedded). If you need line numbers, you can use ``num`` postfix. So you can use four types of lists. + +* ``//list[ID][caption][language]{ ... //}`` + * normal list. language is optional. +* ``//listnum[ID][caption][language]{ ... //}`` + * normal list with line numbers. language is optional. +* ``//emlist[caption][language]{ ... //}`` + * list without caption counters. caption and language are optional. +* ``//emlistnum[caption][language]{ ... //}`` + * list with line numbers without caption counters. caption and language are optional. + +Usage: + +```review +//list[main][main()][c]{ ←ID is `main`, caption is `main()` +int +main(int argc, char **argv) +{ + puts("OK"); + return 0; +} +//} +``` + +Usage: + +```review +//listnum[hello][hello world][ruby]{ +puts "hello world!" +//} +``` + +Usage: + +```review +//emlist[][c]{ +printf("hello"); +//} +``` + +Usage: + +```review +//emlistnum[][ruby]{ +puts "hello world!" +//} +``` + +The Language option is used for highlightings. + +You can use inline markup in blocks. + +When you refer a list like `see list X`, you can use an ID in `//list` +such as `@{main}`. + +When you refer a list in the other chapter, you can use an ID with chapter ID, such like `@{advanced|main}`, to refer a list `main` in `advanced.re`. + +### define line number of first line in code block + +If you want to start with specified number as line number, you can use `firstlinenum` command. + +Usage: + +```review +//firstlinenum[100] +//listnum[hello][helloworld][ruby]{ +puts "hello world!" +//} +``` + +### Quoting Source Code + +`//source` is for quoting source code. filename is mandatory. + +Usage: + +```review +//source[/hello/world.rb]{ +puts "hello world!" +//} +``` + +`//source` and `//emlist` with caption is not so different. +You can use them with different style with CSS (in HTML) and style file (in LaTeX). + +`//source` can be referred same as the list. + +Usage: + +``` +When you ..., see @{hello}. +``` + +## Inline Source Code + +You can use `@{...}` in inline context. + +Usage: + +```review +@{p = obj.ref_cnt} +``` + +## Shell Session + +When you want to show command line operation, you can use `//cmd{ ... //}`. +You can use inline commands in this command. + +Usage: + +``` +//cmd{ +$ @{ls /} +//} +``` + +You can use inline markup in `//cmd` blocks. + +## Figure + +You can use `//image{ ... //}` for figures. +You can write comments or Ascii art in the block as an alternative description. +When publishing, it's simply ignored. + +Usage: + +``` +//image[unixhistory][a brief history of UNIX-like OS]{ + System V + +----------- SVr4 --> Commercial UNIX(Solaris, AIX, HP-UX, ...) +V1 --> V6 --| + +--------- 4.4BSD --> FreeBSD, NetBSD, OpenBSD, ... + BSD + + --------------> Linux +//} +``` + +The third option is used to define the scale of images. `scale=X` is scaling for page width (`scale=0.5` makes image width to be half of page width). +If you'd like to use different values for each builders, such as HTML and TeX, you can specify the target builders using `::`. Example: `html::style="transform: scale(0.5);",latex::scale=0.5` + +When you want to refer images such as "see figure 1.", you can use +inline reference markup like `@{unixhistory}`. + +When you refer a image in the other chapter, you can use the same way as a list reference. To refer a image `unixhistory` in `advanced.re`, use `@{advanced|unixhistory}`. + +When you want to use images in paragraph or other inline context, you can use `@`. + +### Finding image pathes + +The order of finding image is as follows. The first matched one is used. + +``` +1. ///. +2. //-. +3. //. +4. //. +5. /-. +6. /. +``` + +* ```` is `images` as default. +* ```` is a builder (target) name to use. When you use review-comile commmand with ``--target=html``, `/` is `images/html`. The builder name for epubmaker and webmaker is `html`, for pdfmaker it is `latex`, and for textmaker it is `top`. +* ```` is basename of *.re file. If the filename is `ch01.re`, chapid is `ch01`. +* ```` is the ID of the first argument of `//image`. You should use only printable ASCII characters as ID. +* ```` is file extensions of Re:VIEW. They are different by the builder you use. + +For each builder, image files are searched in order of the following extensions, and the first hit file is adopted. + +* HTMLBuilder (EPUBMaker, WEBMaker), MARKDOWNBuilder: .png, .jpg, .jpeg, .gif, .svg +* LATEXBuilder (PDFMaker): .ai, .eps, .pdf, .tif, .tiff, .png, .bmp, .jpg, .jpeg, .gif +* Other builders/makers: .ai, .psd, .eps, .pdf, .tif, .tiff, .png, .bmp, .jpg, .jpeg, .gif, .svg + +### Inline Images + +When you want to use images in paragraph, you can use the inline command `@{ID}`. The order of finding images are same as `//image`. + +## Images without caption counter + +`//indepimage[filename][caption]` makes images without caption counter. +caption is optional. + +Usage: + +``` +//indepimage[unixhistory2] +``` + +Note that there are similar markup `//numberlessimage`, but it is deprecated. + + +## Figures with graph tools + +Re:VIEW generates image files using graph tool with command `//graph[filename][commandname][caption]`. The caption is optional. + +Usage: using with Gnuplot + +``` +//graph[sin_x][gnuplot]{ +plot sin(x) +//} +``` + +You can use `graphviz`, `gnuplot`, `blockdiag`, `aafigure`, `plantuml`, and `mermaid` as the command name. +Before using these tools, you should installed them and configured path appropriately. + +* Graphviz ( https://www.graphviz.org/ ) : set path to `dot` command +* Gnuplot ( http://www.gnuplot.info/ ) : set path to `gnuplot` command +* Blockdiag ( http://blockdiag.com/ ) : set path to `blockdiag` command. Install ReportLab also to make a PDF +* aafigure ( https://launchpad.net/aafigure ) : set path to `aafigure` command +* PlantUML ( http://plantuml.com/ ) : set path to `java` command. place `plantuml.jar` on working folder, `/usr/share/plantuml` or `/usr/share/java`. +* Mermaid ( https://mermaid.js.org/ ) : see below + +### using Mermaid + +Mermaid is a JavaScript-based diagram tool that runs in a Web browser. For use with EPUB or LaTeX PDF, Re:VIEW calls the Web browser internally to create images. At this time, we have not confirmed that Mermaid works on any platforms other than Linux. + +1. Create `package.json` in your project (if you have an existing file, add the line `"playwright"...` to the `dependencies`). + ``` + { + "name": "book", + "dependencies": { + "playwright": "^1.32.2" + } + } + ``` +2. Install Playwright library. If you don't have `npm`, set up [Node.js](https://nodejs.org/) first. + ``` + npm install + ``` +3. Install [playwright-runner](https://github.com/kmuto/playwright-runner), a module that calls the Playwright library from Ruby. + ``` + gem install playwright-runner + ``` +4. (Optional) Since EPUB cannot handle PDF, the images must be in SVG format; to convert them to SVG, you need the `pdftocairo` command included in [poppler](https://gitlab.freedesktop.org/poppler/poppler). It can be installed in Debian and its derivatives as follows: + ``` + apt install poppler-utils + ``` +5. (Optional )By default, there will be white margins around the figure. To crop them, you need the `pdfcrop` command included in TeXLive, which can be installed in Debian and its derivatives as follows: + ``` + apt install texlive-extra-utils + ``` + +Adjust `config.yml`. The default values are as follows: + +``` +playwright_options: + playwright_path: "./node_modules/.bin/playwright" + selfcrop: true + pdfcrop_path: "pdfcrop" + pdftocairo_path: "pdftocairo" +``` + +- `playwright_path`: path of the `playwright` command. +- `selfcrop`: use the default cropper of `playwright-runner`. The `pdfcrop` will not be needed, but there will be margins around it. Set to `false` if you can use `pdfcrop`. +- `pdfcrop_path`: path of the `pdfcrop` command. Ignored if `selfcrop` is `true`. +- `pdftocairo_path`: path of the `pdftocairo` command. + +The notation in Re:VIEW is `//graph[ID][mermaid][caption]` or `//graph[ID][mermaid]`. Based on this ID, `images/html/ID.svg` (for EPUB) or `images/latex/ID.pdf` (for LaTeX PDF) will be generated. + +## Tables + +The markup of table is `//table[ID][caption]{ ... //}` +You can separate header and content with `------------`. + +The columns are splitted by TAB character. Write `.` to blank cells. When the first character in the cell is `.`, the character is removed. If you want to write `.` at the first, you should write `..`. + +When you want to use an empty column, you write `.`. + +Usage: + +``` +//table[envvars][Important environment varialbes]{ +Name Comment +------------------------------------------------------------- +PATH Directories where commands exist +TERM Terminal. ex: linux, kterm, vt100 +LANG default local of users. ja_JP.eucJP and ja_JP.utf8 are popular in Japan +LOGNAME login name of the user +TEMP temporary directory. ex: /tmp +PAGER text viewer on man command. ex: less, more +EDITOR default editor. ex: vi, emacs +MANPATH Directories where sources of man exist +DISPLAY default display of X Window System +//} +``` + +When you want to write "see table X", you can write `@
{envvars}`. + +You can use inline markup in the tables. + +`//table` without arguments creates a table without numbering and captioning. + +``` +//table{ +... +//} +``` + +To create a table without numbering but with captioning, use `//emtable`. + +``` +//emtable[caption]{ +... +//} +``` + +### Column width of table +When using LaTeX or IDGXML builder, you can specify each column width of the table with `//tsize` block command. + +``` +//tsize[|builder|width-of-column1,width-of-column2,...] +``` + +* The collumn width is specified in mm. +* For IDGXML, if only 1st of the three columns is specified, the remaining 2nd and 3rd columns will be the width of the remainder of the live area width equally divided. It is not possible to specify that only the 1st and 3rd columns are specified. +* For LaTeX, you have to specify all column widths. +* For LaTeX, you can also directly specify the column parameter of LaTeX table macro like `//tsize[|latex||p{20mm}cr|]`. +* In other builders such as HTML, this command is simply ignored. + +### Complex Table + +If you want to use complex tables, you can use `imgtable` block command with an image of the table. `imgtable` supports numbering and `@
`. + +Usage: + +``` +//imgtable[complexmatrix][very complex table]{ +to use image "complexmatrix". +The rule of finding images is same as image command. +//} +``` + +## Quoting Text + +You can use `//quote{ ... //}` as quotations. + +Usage: + +``` +//quote{ +Seeing is believing. +//} +``` + +You can use inline markup in quotations. + +Center-aligned paragraphs are represented by `//centering{ ~ //}` and right-aligned paragraphs by `//flushright{ ~ //}`. + +To include multiple paragraphs, separate them with a blank line. + +Usage: + +``` +//centering{ +This is + +center aligned. +//} + +//flushright{ +This is + +right aligned. +//} +``` + +## Short column + +Some block commands are used for short column. + +* `//note[caption]{ ... //}` +* `//memo[caption]{ ... //}` +* `//tip[caption]{ ... //}` +* `//info[caption]{ ... //}` +* `//warning[caption]{ ... //}` +* `//important[caption]{ ... //}` +* `//caution[caption]{ ... //}` +* `//notice[caption]{ ... //}` + +`[caption]` is optional. + +The content is like paragraph; separated by empty lines. + +From Re:VIEW 5.0, it is also possible to include itemize, figures and tables in short columns. + +``` +//note{ + +With ordered itemize. + + 1. item1 + 2. item2 + +//} +``` + +## Footnotes + +You can use `//footnote` to write footnotes. + +Usage: + +``` +You can get the packages from support site for the book.@{site} +You should get and install it before reading the book. + +//footnote[site][support site of the book: http://i.loveruby.net/ja/stdcompiler ] +``` + +`@{site}` in source are replaced by footnote marks, and the phrase "support site of .." +is in footnotes. + +Note that in LATEXBuilder, it is highly recommended to place `//footnote` after the end line of column (`==[/column]`) to avoid problems when using third party's style file. + +### `footnotetext` option +Note that in LATEXBuilder, you should use `footnotetext` option to use `@{...}` in `//note` or other short column blocks. + +By adding `footnotetext:true` in config.yml, you can use footnote in tables and short notes. + +Note that there are some constraints that (because of normal footnote ) + +And you cannot use footnote and footnotemark/footnotetext at the same time. + +Note that with this option, Re:VIEW use footnotemark and footnotetext instead of normal footnote. +There are some constraints to use this option. +You cannot use footnote and footnotemark/footnotetext at the same time. + +## Endnotes + +You can use `//endnote` to write endnotes. + +Usage: + +``` +You can get the packages from support site for the book.@{site} +You should get and install it before reading the book. + +//endnote[site][support site of the book: http://i.loveruby.net/ja/stdcompiler ] +``` + +`@{site}` in source are replaced by endnote marks, and the phrase "support site of .." +is stored for printing later. + +To print stored endnotes, place "`//printendnotes`" where you want to write down them (usually at the end of the chapter). + +``` + ... + +==== Endnote + +//printendnotes +``` + +It is not possible to create an endnote that spans multiple chapters. + +## Bibliography + +When you want to use a bibliography, you should write them in the file `bib.re`. + +``` +//bibpaper[cite][caption]{..comment..} +``` + +The comment is optional. + +``` +//bibpaper[cite][caption] +``` + +Usage: + +``` +//bibpaper[lins][Lins, 1991]{ +Refael D. Lins. A shared memory architecture for parallel study of +algorithums for cyclic reference_counting. Technical Report 92, +Computing Laboratory, The University of Kent at Canterbury , August +1991 +//} +``` + +When you want to refer some references, You should write as: + +Usage: + +``` +… is the well-known project.(@{lins}) +``` + +## Lead Sentences + +lead sentences are `//lead{ ... //}`. +You can write as `//read{ ... //}`. + +Usage: + +``` +//lead{ +In the chapter, I introduce brief summary of the book, +and I show the way how to write a program in Linux. +//} +``` + +## TeX Equations + +You can use `//texequation{ ... //}` to insert mathematical equations of LaTeX. + +Usage: + +``` +//texequation{ +\sum_{i=1}^nf_n(x) +//} +``` + +If you'd like to assign a number like 'Equation 1.1`, specify the identifier and caption. + +``` +//texequation[emc][The Equivalence of Mass and Energy]{ +\sum_{i=1}^nf_n(x) +//} +``` + +To reference this, use the inline command `@`. + +There is `@{ ... }` for inline. When writing long expressions, it is convenient to use fence notation (`@$~$` or `@|~|`) to avoid escaping. (see "Fence notation for inline commands" section also). + +Whether LaTeX formula is correctly displayed or not depends on the processing system. PDFMaker uses LaTeX internally, so there is no problem. + +In EPUBMaker and WEBMaker, you can choose between MathML conversion, MathJax conversion, and imaging. + +### MathML case +Install MathML library (`gem install math_ml`). + +Specify in config.yml as follows: + +``` +math_format: mathml +``` + +Whether it is displayed properly in MathML depends on your viewer or browser. + +### MathJax case +Specify in config.yml as follows: + +``` +math_format: mathjax +``` + +MathJax JavaScript module is loaded from the Internet. Because the EPUB specification prohibits loading files from external, enabling this feature will cause the EPUB file to fail validation. Also MathJax will not work in almost all EPUB readers, but may be available with CSS formatting processor. + +### imaging case + +This way calls LaTeX internally and images it with an external tool. Image files will be placed in `images/_review_math` folder. + +You need TeXLive or other LaTeX environment. Modify the parameters of `texcommand`,` texoptions`, `dvicommand`,` dvioptions` in config.yml as necessary. + +In addition, external tools for image conversion are also needed. Currently, it supports the following two methods. + +- `pdfcrop`: cut out the formula using `pdfcrop` command (included in TeXLive) and image it. By default, `pdftocairo` command is used (included in Poppler library). You can change it to another tool if available on the command line. +- `dvipng`: it uses [dvipng](https://ctan.org/pkg/dvipng) to cut out and to image. You can install with OS package or `tlmgr install dvipng`. + +By setting in config.yml, + +``` +math_format: imgmath +``` + +it is set as follows: + +``` +imgmath_options: + # format. png|svg + format: png + # conversion method. pdfcrop|dvipng + converter: pdfcrop + # custom preamble file (default: for upLaTeX+jsarticle.cls, see lib/review/makerhelper.rb#default_imgmath_preamble) + preamble_file: null + # default font size + fontsize: 10 + # default line height + lineheight: 12 + # pdfcrop command. + # %i: filename for input %o: filename for output + pdfcrop_cmd: "pdfcrop --hires %i %o" + # imaging command. + # %i: filename for input %o: filename for output %O: filename for output without the extension + # %p: page number, %t: format + pdfcrop_pixelize_cmd: "pdftocairo -%t -r 90 -f %p -l %p -singlefile %i %O" + # whether to generate a single PDF page for pdfcrop_pixelize_cmd. + extract_singlepage: null + # command line to generate a single PDF page file. + pdfextract_cmd: "pdfjam -q --outfile %o %i %p" + # dvipng command. + dvipng_cmd: "dvipng -T tight -z 9 -p %p -l %p -o %o %i" +``` + +For example, to make SVG: + +``` +math_format: imgmath +imgmath_options: + format: svg + pdfcrop_pixelize_cmd: "pdftocairo -%t -r 90 -f %p -l %p %i %o" +``` + +By default, the command specified in `pdfcrop_pixelize_cmd` takes the filename of multi-page PDF consisting of one formula per page. + +If you want to use the `sips` command or the` magick` command, they can only process a single page, so you need to set `extract_singlepage: true` to extract the specified page from the input PDF. `pdfjam` command (in TeXLive) is used to extract pages. + +``` +math_format: imgmath +imgmath_options: + extract_singlepage: true + # use pdftk instead of default pdfjam (for Windows) + pdfextract_cmd: "pdftk A=%i cat A%p output %o" + # use ImageMagick + pdfcrop_pixelize_cmd: "magick -density 200x200 %i %o" + # use sips + pdfcrop_pixelize_cmd: "sips -s format png --out %o %i" +``` + +To create PDF math images: + +``` +math_format: imgmath +imgmath_options: + format: pdf + extract_singlepage: true + pdfextract_cmd: "pdftk A=%i cat A%p output %o" + pdfcrop_pixelize_cmd: "mv %i %o" +``` + +To set the same setting as Re:VIEW 2: + +``` +math_format: imgmath +imgmath_options: + converter: dvipng + fontsize: 12 + lineheight: 14.3 +``` + +## Spacing + +`//noindent` is a tag for spacing. + +* `//noindent` : ingore indentation immediately following line. (in HTML, add `noindent` class) + +## Blank line + +`//blankline` put an empty line. + +Usage: + +``` +Insert one blank line below. + +//blankline + +Insert two blank line below. + +//blankline +//blankline +``` + +## Referring headings + +There are 3 inline commands to refer a chapter. These references use Chapter ID. The Chapter ID is filename of chapter without extentions. For example, Chapter ID of `advanced.re` is `advance`. + +* `@{ChapterID}` : chapter number (ex. `Chapter 17`). +* `@{ChapterID}` : chapter title +* `@<chapref>{ChapterID}` : chapter number and chapter title (ex. `Chapter 17. other topics`). + +`@<hd>` generate referred section title and section number. +You can use deeper section with separator `|`. + +Usage: + +``` +@<hd>{intro|first section} +``` + +If section title is unique, `|` is not needed. + +``` +@<hd>{first section} +``` + +If you want to refer another chapter (file), you should add the chapter ID. + +Usage: + +``` +@<hd>{preface|Introduction|first section} +``` + +When section has the label, you can use the label. + +``` +=={intro} Introduction +: +=== first section +: +@<hd>{intro|first section} +``` + + +### Heading of columns + +You can refer the heading of a column with `@<column>`. + +Usage: + +``` +@<column>{The usage of Re:VIEW} +``` + +You can refer labels. + +``` +==[column]{review-application} The application of Re:VIEW +: +@<column>{review-application} +``` + +## Links + +You can add a hyperlink with `@<href>` and `//label`. +Notation of the markup is `@<href>{URL, anchor}`. If you can use URL itself +as anchor, use `@<href>{URL}`. +If you want to use `,` in URL, use `\,`. + +Usage: + +``` +@<href>{http://github.com/, GitHub} +@<href>{http://www.google.com/} +@<href>{#point1, point1 in document} +@<href>{chap1.html#point1, point1 in document} +//label[point1] +``` + +## Words file + +By creating a word file with key / value pair, `@<w>{key}` or `@<wb>{key}` will be expanded the key to the corresponding value. `@<wb>` means bold style. + +This word file is a CSV file with extension .csv. This first columns is the key, the second row is the value. + +``` +"LGPL","Lesser General Public License" +"i18n","""i""nternationalizatio""n""" +``` + +Specify the word file path in `words_file` parameter of `config.yml`. You can specify multiple word files as `word_file: ["common.csv", "mybook.csv"]`. + +Usage: + +```review +@<w>{LGPL}, @<wb>{i18n} +``` + +(In HTML:) + +``` +Lesser General Public License, ★"i"nternationalizatio"n"☆ +``` + +Values are escaped by the builder. It is not possible to include inline commands in the value. + +## Comments + +If you want to write some comments that do not output in the document, you can use comment notation `#@#`. + +Usage: + +``` +#@# Must one empty line +``` + +If you want to write some warnings, use `#@warn(...)`. + +Usage: + +``` +#@warn(TBD) +``` + +When you want to write comments in the output document, use `//comment` and `@<comment>` with the option `--draft` of review-compile command. + +Usage: + +``` +@<comment>{TODO} +``` + +## Raw Data Block + +When you want to write non-Re:VIEW line, use `//embed` or `@<embed>`. + +### `//embed` block + +Usage: + +``` +//embed{ +<div class="special"> +this is a special line. +</div> +//} + +//embed[html,markdown]{ +<div class="special"> +this is a special line. +</div> +//} +``` + +In above line, `html` and `markdown` is a builder name that handle raw data. + +Output: + +(In HTML:) + +``` +<div class="special"> +this is a special line. +</div> +``` + +(In other formats, it is just ignored.) + +For inline, use `@<embed>{|builder|raw string}`. + +### `//raw` block + +`//raw` and `@<raw>` is an old notation and should no longer be used (use it only if you want to avoid line breaks in IDGXML builder). + +Usage: + +``` +//raw[|html|<div class="special">\nthis is a special line.\n</div>] +``` + +In above line, `html` is a builder name that handle raw data. +You can use `html`, `latex`, `idgxml` and `top` as builder name. +You can specify multiple builder names with separator `,`. +`\n` is translated into newline(U+000A). + +Output: + +(In HTML:) + +``` +<div class="special"> +this is a special line. +</div> +``` + +(In other formats, it is just ignored.) + +Note: `//embed`, `@<embed>`, `//raw` and `@<raw>` may break structured document easily. + +### Nested itemize block + +Re:VIEW itemize blocks basically cannot express nested items. Also, none of itemize blocks allow to contain another itemize block or paragraph/image/table/list. + +As a workaround, Re:VIEW provides `//beginchild` and `//endchild` since Re:VIEW 4.2. If you want to include something in an itemize block, enclose it with `//beginchild` and `//endchild`. It is also possible to create a multiple nest. + +``` + * UL1 + +//beginchild +#@# child of UL1 start + + 1. UL1-OL1 + +//beginchild +#@# child of UL1-OL1 start + +UL1-OL1-PARAGRAPH + + * UL1-OL1-UL1 + * UL1-OL1-UL2 + +//endchild +#@# child of UL1-OL1 end + + 2. UL1-OL2 + + : UL1-DL1 + UL1-DD1 + : UL1-DL2 + UL1-DD2 + +//endchild +#@# child of UL1 end + + * UL2 +``` + +Output: + +(In HTML:) + +``` +<ul> +<li>UL1 +<ol> +<li>UL1-OL1 +<p>UL1-OL1-PARAGRAPH</p> +<ul> +<li>UL1-OL1-UL1</li> +<li>UL1-OL1-UL2</li> +</ul> +</li> + +<li>UL1-OL2</li> +</ol> +<dl> +<dt>UL1-DL1</dt> +<dd>UL1-DD1</dd> +<dt>UL1-DL2</dt> +<dd>UL1-DD2</dd> +</dl> +</li> + +<li>UL2</li> +</ul> +``` + +(This is an experimental implementation. Names and behaviors may change in future versions.) + +## Inline Commands + +### Styles + +``` +@<kw>{Credential, credential}:: keyword. +@<bou>{appropriate}:: bou-ten. +@<ami>{point}:: ami-kake (shaded text) +@<u>{AB}:: underline +@<b>{Please}:: bold +@<i>{Please}:: italic +@<strong>{Please}:: strong(emphasis) +@<em>{Please}:: another emphasis +@<tt>{foo($bar)}:: teletype (monospaced font) +@<tti>{FooClass}:: teletype (monospaced font) and italic +@<ttb>{BarClass}:: teletype (monospaced font) and bold +@<code>{a.foo(bar)}:: teletype (monospaced font) for fragments of code +@<tcy>{text}:: short horizontal text in vertical text +@<ins>{sentence}:: inserted part (underline) +@<del>{sentence}:: deleted part (strike through) +@<sup>{text}:: superscript +@<sub>{text}:: subscript +``` + +### References + +``` +@<chap>{advanced}:: chapter number like `Chapter 17` +@<title>{advanced}:: title of the chapter +@<chapref>{advanced}:: a chapter number and chapter title like `Chapter 17. advanced topic` +@<list>{program}:: `List 1.5` +@<img>{unixhistory}:: `Figure 1.3` +@<table>{ascii}:: `Table 1.2` +@<eq>{emc2}:: `Equation 1.1` +@<hd>{advanced|Other Topics}:: `7-3. Other Topics` +@<column>{another-column}:: reference of column. +``` + +### Other inline commands + +``` +@<ruby>{Matsumoto,Matz}:: ruby markups +@<br>{}:: linebreak in paragraph +@<uchar>{2460}:: Unicode code point +@<href>{http://www.google.com/, google}:: hyper link(URL) +@<icon>{samplephoto}:: inline image +@<m>{a + \alpha}:: TeX inline equation +@<w>{key}:: expand the value corresponding to the key. +@<wb>{key}:: expand the value corresponding to the key with bold style. +@<embed>{|html|<span>ABC</span>}:: inline raw data inline. `\}` is `}` and `\\` is `\`. +@<raw>{|html|<span>ABC</span>}:: inline raw data inline. `\}` is `}`, `\\` is `\`, and `\n` is newline. (deprecated) +@<idx>{string}:: output a string and register it as an index. See makeindex.md. +@<hidx>{string}:: register a string as an index. A leveled index is expressed like `parent<<>>child` +@<balloon>{abc}:: inline balloon in code block. For example, `@<balloon>{ABC}` produces `←ABC`. This may seem too simple. To decorate it, modify the style sheet file or override a function by `review-ext.rb` +``` + +## Commands for Authors (pre-processor commands) + +These commands are used in the output document. In contrast, +commands as below are not used in the output document, used +by the author. + +``` +#@#:: Comments. All texts in this line are ignored. +#@warn(...):: Warning messages. The messages are showed when pre-process. +#@require, #@provide:: Define dependency with keywords. +#@mapfile(filename) ... #@end:: Insert all content of files. +#@maprange(filename, range name) ... #@end:: Insert some area in content of files. +#@mapoutput(command) ... #@end:: Execute command and insert their output. +``` + +You should use these commands with preprocessor command `review-preproc`. + +## Internationalization (i18n) + +Re:VIEW support I18N of some text like `Chapter`, `Figure`, and `Table`. +Current default language is Japanese. + +You add the file locale.yml in the project directory. + +Sample local.yml file: + +```yaml +locale: en +``` + +If you want to customize texts, overwrite items. +Default locale configuration file is in lib/review/i18n.yml. + +Sample local.yml file: + +```yaml +locale: en +image: Fig. +table: Tbl. +``` + +### Re:VIEW Custom Format + +In `locale.yml`, you can use these Re:VIEW custom format. + +* `%pA` : Alphabet (A, B, C, ...) +* `%pa` : alphabet (a, b, c, ...) +* `%pAW` : Alphabet (Large Width) A, B, C, ... +* `%paW` : alphabet (Large Width) a, b, c, ... +* `%pR` : Roman Number (I, II, III, ...) +* `%pr` : roman number (i, ii, iii, ...) +* `%pRW` : Roman Number (Large Width) Ⅰ, Ⅱ, Ⅲ, ... +* `%pJ` : Chainese Number 一, 二, 三, ... +* `%pdW' : Arabic Number (Large Width for 0..9) 1, 2, ...,9, 10, ... +* `%pDW' : Arabic Number (Large Width) 1, 2, ... 10, ... + +Usage: + +``` +locale: en + part: Part. %pRW + appendix: Appendix. %pA +``` + +## Other Syntax + +In Re:VIEW, you can add your customized blocks and inlines. + +You can define customized commands in the file `review-ext.rb`. + +Usage: + +```ruby +# review-ext.rb +ReVIEW::Compiler.defblock :foo, 0..1 +class ReVIEW::HTMLBuilder + def foo(lines, caption = nil) + puts lines.join(",") + end +end +``` + +You can add the syntax as below: + +``` +//foo{ +A +B +C +//} +``` + +``` +# Result +A,B,C +``` + +## HTML/LaTeX Layout + +`layouts/layout.html.erb` and `layouts/layout.tex.erb` are used as layout file. +You can use ERb tags in the layout files. + +Sample layout file(layout.html.erb): + +```html +<html> + <head> + <title><%= @config["booktitle"] %> + + + <%= @body %> +
+ + +``` diff --git a/doc/format_idg.ja.md b/doc/format_idg.ja.md new file mode 100644 index 0000000..17e87b8 --- /dev/null +++ b/doc/format_idg.ja.md @@ -0,0 +1,108 @@ +# Re:VIEW フォーマット InDesign XML 形式拡張 + +Re:VIEW フォーマットから、Adobe 社の DTP ソフトウェア「InDesign」で読み込んで利用しやすい XML 形式に変換できます (通常の XML とほぼ同じですが、文書構造ではなく見た目を指向した形態になっています)。実際には出力された XML を InDesign のスタイルに割り当てるフィルタをさらに作成・適用する必要があります。 + +基本のフォーマットのほかにいくつかの拡張命令を追加しています。 + +このドキュメントは、Re:VIEW 3.0 に基づいています。 + +## 追加したブロック +これらのブロックは基本的に特定の書籍向けのものであり、将来廃棄する可能性があります。 + +* `//insn[タイトル]{ 〜 //}` または `//box[タイトル]{ 〜 //}` : 書式 +* `//planning{ 〜 //}` または `//planning[タイトル]{ 〜 //}` : プランニング +* `//best{ 〜 //}` または `//best[タイトル]{ 〜 //}` : ベストプラクティス +* `//security{ 〜 //}` または `//security[タイトル]{ 〜 //}` : セキュリティ +* `//expert{ 〜 //}` : エキスパートに訊く +* `//point{ 〜 //}` または `//point[タイトル]{ 〜 //}` : ワンポイント +* `//shoot{ 〜 //}` または `//shoot[タイトル]{ 〜 //}` : トラブルシューティング +* `//term{ 〜 //}` : 用語解説 +* `//link{ 〜 //}` または `//link[タイトル]{ 〜 //}` : 他の章やファイルなどへの参照説明 +* `//practice{ 〜 //}` : 練習問題 +* `//reference{ 〜 //}` : 参考情報 + +## 相互参照 + +`//label[〜]` でラベルを定義し、`@{〜}` で参照します。XML としては `