ラベル Re:VIEW の投稿を表示しています。 すべての投稿を表示
ラベル Re:VIEW の投稿を表示しています。 すべての投稿を表示

2026年1月17日土曜日

review-retrovert を更新しました

https://github.com/srz-zumix/review-retrovert
review-retrovert は Re:VIEW Starter で作られたプロジェクトを Re:VIEW のプロジェクトに変換するツールです。
昔、執筆したときに作って使ったものなんですが、コメントいただきまして不具合修正しました。コメントありがとうございました!!
https://srz-zumix.blogspot.com/2020/09/review-starterreview-starter-review.html?showComment=1766322318872#c9139258129104742884

変更点としては Ruby 3.1 以降への対応が主です。
また、過去の Re:VIEW で使えるように各バージョンごとに docker image も用意するようにしました。
https://hub.docker.com/repository/docker/srzzumix/review-retrovert/tags

最近、技術書典には参加してませんが、また機会があればやってみたいですね。

2021年7月21日水曜日

Re:VIEW Starter から Re:VIEW のプロジェクトに戻すツール review-retrovert 0.9.9 リリース

ブログズミ: [Re:VIEW Starter][Re:VIEW] 訳あって Starter から素の Re:VIEW に戻すツールをリリースしました

こちらの最新版 0.9.9 をリリースしました。
https://rubygems.org/gems/review-retrovert

以下、今年2月にリリースした 0.9.7 からの更新内容です。

  • Re:VIEW Starter 2021/06/30 版に対応
    • Re:VIEW Starter のサンプルプロジェクトの変換が可能な状態
    • talklist や desclist 、単語展開、用語・索引、CSV テーブルなどサンプルで使われている表現には対応しています
    • 7月の Starter の更新にも対応していると思います
  • Starter でのみキャプションが付けられるコマンドのキャプション部分を代替コマンドの前に文章として出力
  • file パラメータによる埋め込みに対応
  • キャプションなし image は indepimage が出力されるように修正
  • Starter 独自コマンド中の文章が出力されてなかった問題を修正
  • %指定の width 指定を scale に変換
  • Re:VIEW 5.1 以降および 3.2 未満のバージョンでエラーになっていたのを修正
  • その他、めっちゃバグ修正

自分が欲しくて作ったものですが、同じような境遇の方に届けば幸いです。

2021年5月13日木曜日

[技術書典] Re:VIEW Starter で印刷・電子書籍版で config.yml を使い分ける

Re:VIEW Starter (もしくは Re:VIEW)を使ってると電子書籍版と印刷版で設定変えたいことがあります。

たとえば
  ## リンクのURLを脚注に埋め込む(PDFでのみ)。
  linkurl_footnote: false   # trueならリンクのURLを脚注に埋め込む(お勧め)
リンクの URL が自動的に footnote になるのでとても便利なのですが、電子書籍版はリンクで飛べるので false にしてました。
やり方
電子書籍版用の YAML ファイルを用意する
Re:VIEW では config.yml 、Re:VIEW Starter では加えて config-stater.yml がありますが、それぞれ電子書籍用の YAML を用意します。
このとき YAML はコピペではなく、電子書籍版で設定した項目だけ書けば OK です。

例:

ポイントは inherit で優先したい設定の YAML を後ろに書くことです。
また、contentdir はルートの YAML にないと rake でエラーになるので注意してください。

電子書籍版用の yml ファイルを指定してビルドする
Re:VIEW では「config」環境変数に設定した YAML ファイルを読み込んでくれるので、ビルドする際に config=config-e.yml のように指定すれば OK です。
  config=config-e.yml rake preproc pdf
  docker run --rm -e "config=config-e.yml" -v "$(pwd)":/work -w /work kauplan/review2.5 rake preproc all
まとめ
  • YAML を分ける
  • inherit を利用して共通の設定を読み込む
  • config 環境変数に YAML ファイルをセット
これで設定切り替えが簡単にできるようになりました。
宣伝
拙著発売中です。よろしくお願いします。


2021年3月25日木曜日

Re:VIEW の textlint 環境を整える

 Zenn で GitHub 管理された記事投稿ができるようになり、GtiHub Actions で textlint をかける CI 環境を作りましたが、これを技術書典などの書籍作成用リポジトリにも設定したいと思います。

textlint 環境の構築

npm で textlint と Re:VIEW 用のプラグインをインストールします。

npm install textlint
npm install textlint-plugin-review
npm install textlint-rule-preset-ja-technical-writing
npm install textlint-rule-preset-ja-spacing
npm install textlint-filter-rule-allowlist

それぞれのリポジトリはこちら

https://github.com/textlint/textlint
https://github.com/orangain/textlint-plugin-review
https://github.com/textlint-ja/textlint-rule-preset-ja-technical-writing
https://github.com/textlint-ja/textlint-rule-preset-ja-spacing
https://github.com/textlint/textlint-filter-rule-allowlist

.textlintrc をルートに配置
  {
  "plugins": {
    "@textlint/markdown": {
      "extensions": [".md"]
    },
    "review-starter": {
      "extensions": [".re"]
    }
  },
  "rules": {
    "preset-ja-technical-writing": {
      "sentence-length": false
    },
    "preset-ja-spacing": {
      "ja-space-between-half-and-full-width": {
        space: "always",
        exceptPunctuation: true,
      },
      "ja-space-around-code": {
        "before": true,
        "after": true
      }
    }
  },
  "filters": {
      "allowlist": {
        "allow": [
          "/(.|)[0-9]+(ヶ|か)月/",
          "/(.|)[0-9,]+(分|つ|回|時)/",
        ]
      }
  }
}
  

.textlintrc を配置したら
npx textlint <path> で検証できます。

例)

npx textlint -f unix ci-dex/contents/*.re
/ci-dex/contents/c000-preface.re:10:39: 弱い表現: "思います" が使われています。 [Error/ja-technical-writing/ja-no-weak-phrase]
ci-dex/contents/c000-preface.re:29:7: 原則として、全角文字と半角文字の間にスペースを入れます。 [Error/ja-spacing/ja-space-between-half-and-full-width]

GitHub Actions の設定

reviewdog の textlint action があるのでそれを使うと簡単に対応できます。
https://github.com/tsuyoshicho/action-textlint
yaml は以下のようになります。

name: 'Run textlint with reviewdog'
on: [pull_request]
jobs:
  textlint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v1
      - name: textlint-books
        uses: tsuyoshicho/action-textlint@v1
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          reporter: github-pr-review
          textlint_flags: "."  
  
VS Code 環境の設定

vscode-textlint 拡張機能をインストールすると VS Code エディタ上で textlint の指摘を確認できます。

ただし、こちらの拡張機能と「Re:VIEW」拡張機能の相性が悪いようで、「Re:VIEW」拡張機能を有効にしていると textlint の指摘が出てこなくなるので注意してください。
(類似の「yet another Re:VIEW」「Re:VIEW Starter Syntax Highlight」でも同様)


textlint よりも Re:VIEW のシンタックスハイライトがあったほうが便利なので、結局 textlint は CI で確認するようにしました。

Re:VIEW Starter に対応する

自分が執筆する際は Re:VIEW ではなく Re:VIEW Starter を使用しているので、そちらの構文に対応した「textlint-plugin-review-starter」を作成し、リリースしています。
https://github.com/srz-zumix/textlint-plugin-review-starter
https://www.npmjs.com/package/textlint-plugin-review-starter

textlint-plugin-review と同様に npm install すれば使用できます。
textlint-plugin-review にはなかった $/| のフェンス記法と、インラインコマンドの入れ子に対応しています。
もちろん、Re:VIEW Starter 独自のフォーマットにも対応しています。

なにか不具合あれば issue に投げてくださいmm

今回は以上です。では。

2021年1月22日金曜日

[review-retrovert] Re:VIEW Starter → Re:VIEW 4/5 に対応しました

ブログズミ: [Re:VIEW Starter][Re:VIEW] 訳あって Starter から素の Re:VIEW に戻すツールをリリースしました

以前に作った review-retrovert をアップデートしました。
今回も訳あって Re:VIEW Starter -> Re:VIEW をするためのアップデートです。

https://rubygems.org/gems/review-retrovert
https://github.com/srz-zumix/review-retrovert

更新内容としてはタイトルの通りで、Re:VIEW のバージョン 4 と 5 への変換に対応しました。もともと対応していた 3 系も変わらず対応しています。
インストールされている Re:VIEW のバージョンに依存して変換します。

機能としては Re:VIEW Starter の独自拡張を Re:VIEW で表現可能な書式に直したり、削除(コメントアウト)したりします。
また preproc 済みの状態(かつ #@mapfile~#@end を削除)にする --preproc オプションやカタログファイルから参照されている .re ファイルのみに限定する --strict オプションが用意されています。

(※Re:VIEW Starter → Re:VIEW への変換には Nextpublising での制限都合のものも含まれております)
(※書籍に挿入するイメージの制限チェックは GitHub Actions の actions-book-image-check が便利です)

あと変換後だけ config を変えたい場合は config-retrovert.yml を作成し、retrovert キー配下に上書きしたい設定を書いてください。上書きされる方の設定は config-base.yml など別ファイルに移動してください。
そして inherit で "config-base.yml, "config-retrovert.yml" のように読み込みます。
変換前は retrovert キー配下に設定があるので config-retrovert.yml に書いた設定は無視されます。
review-retrovert convert すると retrovert キーが削除され配下の設定がトップレベルになるので、config-retrovert.yml の設定有効になり、inherit 末尾の設定が優先されるので config-base.yml の設定は無視されます。

最後に

Re:VIEW Starter で書いたけど Re:VIEW に直す必要が出てきた方はぜひ使ってみてください。不具合や機能要望は issue へお願いしますmm

宣伝

技術書典10で出品した書籍は現在も技術書典のマーケットで購入できます。
また Booth でも出品してますので何卒よろしくお願いします。

では。

2021年1月14日木曜日

[Re:VIEW] mapfile 中の table が正しく表示されない場合の対応方法

 Re:VIEW で一章のテキスト量が多く書きづらかったので、項単位で複数のファイルに分割して #@mapfile(sub.re) で結合してたのですが、この分割した .re ファイルに table を書いていたのが意図通りの表示になりませんでした。
(※素の Re:VIEW ではなく Re:VIEW Starter を使っています)


こんな感じ。
本来なら FREE/BASIC/STANDARD が列になるはず・・

mapfile の外に出せば問題なく表示されるのですが、table 挿入するところでサブの .re ファイルを分けないといけない(もしくは maprange?)のは面倒なので、調べました。

何が起きていたか?

preproc 後のファイルを見れば、何が起きていたのかは一目瞭然です。
table の列区切り文字であるタブがスペースになっていました。
つまり、行が全部結合されて1列になっていた。

どうしてこうなった?

preproc のソースでこの辺です。

https://github.com/kmuto/review/blob/da817154297474b43c4f13db2e612350ee380b49/lib/review/preprocessor.rb#L454

mapfile で開いたファイルを処理している中で呼ばれるメソッドですが、タブをスペースに変換しています。tabwidth の config がなければ 8 space になっています。
そして、tabwidth が 0 なら変換なしであることがわかります。

これで対応ができそうです!

対応する

@config[tabwidth] は review-preproc の --tabwidth オプションで指定可能なので --tabwidth=0 つければ OK です。
Rake でビルドしてる場合は .rake ファイルも修正してください。

review-preproc --tabwidth=0 file.re

これでちゃんと意図したとおりに出力できました。
(用紙からはみ出ちゃってるのは行が長すぎたから・・リリース版では修正済み)



2020年9月14日月曜日

[Re:VIEW Starter][Re:VIEW] 訳あって Starter から素の Re:VIEW に戻すツールをリリースしました

 技術書典9 が始まりましたね。
私は今回サークル参加しておりませんが、前回初めて参加しました。
来年また参加できたらいいなと思っております。

さて、そんな中今回は執筆環境周りのことを書きたいと思います。
技術書典9が始まったばかりですが、こちらはイベント後に役に立つ内容かと思うので、このタイミングでの公開としました。

紹介するのは表題のとおり、「Re:VIEW Starter」で作成された書籍をただの「Re:VIEW」で扱える状態にコンバートするツールです。
このツールがなぜ必要になったのか?はここでは省略しますが、この変換が必要になる人は今後も少なからず出てくるのではないかな?と思っております。
(私自身も今後の執筆にただの「Re:VIEW」を使うつもりはなく、「Re:VIEW Starter」や他の便利な環境を使いたいと思っているので、またお世話になることもあるかもしれません。)

Re:VIEW Retrovert

ツールは「Re:VIEW Retrovert」といいます。ruby で書かれていて gem install review-retrovert ですぐに使えます。
また、コードは GitHub にて公開中です。
https://rubygems.org/gems/review-retrovert
https://github.com/srz-zumix/review-retrovert

何ができるのか?

review-retrovert convert /path/to/dir/review-starter/config.yml <output directory>

Re:VIEW Starter のプロジェクトの config.yml から Re:VIEW のプロジェクトを生成して出力ディレクトリに書き出します。(Re:VEIW のバージョンは 3.2 です)
テストとして Re:VIEW Starter のテンプレプロジェクトを変換したものが GitHub Actions の成果物として残してあるので、どんな結果になるのかすぐ見てみたい人はダウンロードしてみてください。
https://github.com/srz-zumix/review-retrovert/actions/runs/201132608

制限事項

Re:VIEW Starter は Re:VIEW という名がついていますが、単なる Re:VIEW とはもう別物といっていいくらい便利な機能が拡張されています。
その分、Re:VIEW Retrovert ではこれらの拡張機能を Re:VIEW でも取り扱えるようになるべく、もとの状態を保つように頑張ってます。
ただ、どうしても全く同じ出力にすることはできません。
コンバート後は一通り目を通していただき、不自然な箇所や欠落した場所を調整していただく必要がありますのでご了承ください。

いくつか事例をあげておきます。

出力される Re:VIEW プロジェクトは version 3.2 を想定しています。
4 系が使いたい場合は issue 投げてください。(3.2 から 4.X へアップグレードできるかもしれないので、もしかしたら使えるかもしれません。)

まず Re:VIEW で表現できない命令は削除されます。
文字サイズや修飾はなくなるものと考えてください。(一部は類似の命令に置換します)


次に、ネストされたインライン命令は Re:VIEW では対応してないので、それぞれネストにならないように分解して出力しています。
また、テーブル中のインライン命令も安定しないため、テーブル中の @<br> は削除されます。
空のセルとして . を使用している場合に Re:VIEW の出力がなぜか2行になってしまっていたので、空のセルは . ではなくスペースに置換しています。

また、ブロック命令もネストできないので内側の命令は無視されるので注意してください。


他にもいろいろ無理やり対応しているところがあるので、もし使ってみておかしなところがあれば issue 出してください。
https://github.com/srz-zumix/review-retrovert/issues

最後に

もともとは自分用に書いたツールですが誰かの役に立てば幸いです。
執筆環境の制約はどうしても発生することがありますが、私としてはこのツールのおかげで安心して Re:VIEW Starter を使っていけるようになったかなと思います。

では。


2020/10/3 追記

ミスって gems に publish できてませんでしたmm
v0.9.1 から新しい Re:VIEW Starter に対応してます。
https://rubygems.org/gems/review-retrovert


2020年8月26日水曜日

[技術書典] Re:VIEW Starter でクローバー「♣」を別の文字に変更する

Re:VIEW Stater では節の装飾に「♣」(クローバー)が使用可能です。

技術系同人誌を書く人の味方「Re:VIEW Starter」の紹介 - Qiita

なんとなく個人的に「♣」がしっくりこなかったので、「技術書典8(技術書典 応援祭)」で書いた本では、別の文字に変更しました。
config-starter.yml では変更できないので、変更方法を備忘録として残しておきます。


方法
公開されている「Re:VIEW Starter ユーザーズガイド」に書いてあるとおりにするだけです。

sty/starter-section.sty に \clubsuit があると思いますが、ここの部分が「♣」表示している部分にあたります。
文字を変更する場合は、ここを直接変更することでも可能ですが以下のように対応します。
(技術書典8 のときは知らずに直接編集してた)

sty/mystyle.sty に下記を追加

\renewcommand{\starter@subsection@symbol}{$▶$}

diff を見ていただいたほうが早い気もするので、対応したコミットを載せておきます。

https://github.com/srz-zumix/ci-dex-book/commit/a38b35d279660778a6e8780346f7d2f8c4389e1e

フォントさえあれば LaTex の特殊文字・記号じゃなくても問題なさげ?
(電子書籍用 PDF では問題なさそうだったので "▶" を採用した)

今回は以上。
では。

2020年1月15日水曜日

[技術書典8] Re:VIEW Starter で執筆を開始しました

こんにちは。連休・連休で作業時間があるにも関わらず、進捗乏しいずみっくすです。


ともあれ、本のとてもとても大雑把な目次はできたので、本にするための作業を始めようと思います。
タイトルの通り Re:VIEW Starter を使って執筆をすることにしました。



なぜ Re:VIEW Starter なの?
なんとなくです。
とりあえず、Re:VIEW で始めたらええよという話は聞いていたのですが、この記事「技術系同人誌を書く人の味方「Re:VIEW Starter」の紹介 - Qiita」を読んでなんか良さそうな感じだったので。

まぁ、でも使う前に疑問は解決しておきたいので、ハッシュタグつけてツイートしたら回答いただけました。

Re:VIEW Starter (Re:VIEW 2.5) vs Re:VIEW 4.0
Re:VIEW Starter を始めようとすると、まず目につくのが以下の注意文。
なお、現在のところ Re:VIEW 2.5 のみをサポートしています。
Re:VIEW 3.0 はサポートしていません(2.x との互換性がないため)。ご注意ください。

Re:VIEW の方を確認したところ、2020/1/10 現在は version 4.0 まで更新されているようでした。
Re:VIEW Starter を使う場合、Re:VIEW 3.0 以降の更新の恩恵を受けられないので、デメリットとならないかが気になりました。
また、Re:VIEW の方で review update コマンドで旧バージョンからのアップグレードができるようになっているようだったので、
Re:VIEW Starter with Re:VIEW 4.0 環境でも使える?という疑問がありました。



というわけで、Re:VIEW Starter を採用することにしました。

始める
では、「プロジェクト作成を始める」から作成を開始!

まずはサークル名(もしくは著者名)を入力します。
自分の場合、ぼっちなのでどっちでもどっちでも良さそうですが、とりあえずサークル名を入れました。
(あとで直す場合は config.yml の「aut:」を編集すれば ok みたいなので)


続いて、本のタイトルを入力します。
まだ決めてなかったですので、とりあえず埋めます。
(あとで直す場合は config.yml の「title:」を編集すれば ok )


つぎに本のサイズを決めます。A5 か B5 か。
わかりやすい説明が書かれているのでイメージが付きやすいと思います。アドバイスも参考になります。
今のところどっちでもいいかなーという感じだったので、B5 にしておきます。
(あとで直す場合は config.yml の「texdocumentclass:」を編集すれば ok 。以降も後で設定は変更できるみたいなので、気軽に初期設定を済ませてしまいましょう)




次はフォントサイズと余白。
とりあえず、オススメの設定にしておく。


次はページの設定。
目次は左でもいいやーと思ったので、「章は右ページ始まりにし、目次は左右どちらからでもよい」を選択。(本っぽくなってきましたね)


つづいて章・節・項の見た目を設定します。
デフォルトは、章の行数を2行にだけ変えました。
項のクローバーも別の文字に変えたいなと思ったが、初期設定では変更できそうになかったので、のちのち変えたいと思います(調べてないけどできると思っている)


次は、コードブロック・ターミナル用のフォントフェイスを決めます。
「'」と「`」の違いが分かりづらいのは、自分が書く本の場合困ると思ったので「inconsolata」にしました。


コードブロックの見た目はデフォルトのままにしました。


その他のオプションは、「原稿ファイルを「contents」ディレクトリにまとめる 」を有効にしました。
めちゃくちゃたくさん書く予定はないけど、まとまっていたほうが好みなので。


最後に、もろもろ埋めます。(まだ未定なものがありますが適当に埋めました。あとで変えられますし)


これで完成!!
プロジェクトをダウンロードします。


コンパイルする
ビルド用の Re:VIEW 2.5 の Docker イメージが用意されているので、それを使ってコンパイルしました。
手順どおりすれば問題なくコンパイルできると思います。
(このへんは CI に組み込めそうなので、来週はそれ系の記事を書こうかな・・)

というわけで、ここまで躓くことなくできました!!


まとめ
正直、本を書くのは初めてなので、どれが良いとか悪いとかわからないです。
なので、使い始めたけど自分とは合わなかったから別のものに変える可能性もあります。
まずは、中身が大事ですからね。

というわけで、頑張って内容を埋めるぞー