AquesTalk風記法定義参照

[tarepan]

質問の内容

質問概要：「AquesTalk風記法」の定義として参照すべき単一ソースはどこか

AquesTalk風記法 は VOICEVOX で定義・利用される音声テキスト記法である。
この記法は Frontend / Engine / Core に横断して利用されており、各所に記法に関する注釈が存在している。
各注釈では「定義・詳細はこのリンクへ」という形式ではなく、各所で（その場に必要な）部分的説明がなされている。

例:

voicevox_engine/README.md

Lines 58 to 61 in 16845ab

	`/audio_query`のレスポンスにはエンジンが判断した読み方が AquesTalk ライクな記法([本家の記法](https://www.a-quest.com/archive/manual/siyo_onseikigou.pdf)とは一部異なります)で記録されています。
	記法は次のルールに従います。
	- 全てのカナはカタカナで記述される

https://github.com/VOICEVOX/voicevox/blob/37d52de4647b7e19bbac7d42cde06deb295c5050/src/openapi/apis/DefaultApi.ts#L826

これを踏まえて次の質問があります。

• Q1. 「AquesTalk風記法」の定義文章はありますか？
• Q2. 「記法詳細はこちら」に利用可能な、静的かつ安定的な参照先は存在しますか？

VOICEVOXのバージョン

0.14.10

OSの種類/ディストリ/バージョン

• Windows
• macOS
• Linux

関連issues

• 「AquesTalkライクな記法」や「kana」をドメイン用語「AquesTalk風記法」に統一する #720

[Hiroshiba]

質問ありがとうございます！！

静的リンクはないと思われます。というより表記を完全にまとめた場所もないと思います･･･。なので

Q1. 「AquesTalk風記法」の定義文章はありますか？
Q2. 「記法詳細はこちら」に利用可能な、静的かつ安定的な参照先は存在しますか？

どちらも現状なさそうです。。

書くべきだと感じました。
一旦になってしまうかもですが、エンジンのREADMEに書くのが一番適してるのかなと思いました。
あるいはAPIドキュメント内に書けたらかっこよさそうですが、ちょっと詳しくない感じです！

[tarepan]

どちらも現状なさそう

把握しました。

一旦になってしまうかもですが、エンジンのREADMEに書くのが一番適してるのかなと

ユーザー向けドキュメントとしてREADMEを（一旦）案内するのには賛成です。

エンジニア向けに（例えばコードコメントとして）「詳細はココ見ろ」と書ける場所/リンクがあると有難いです。
READMEだとREADME編集時の節名称変更等でURLが飛んでしまうのでちょっと不向きです。

「AquesTalk風記法詳細」という issue で（一旦）管理するのはどうでしょうか？
議論用ではなく、現行の口語的定義・仕様詳細・参照実装などを周知するためのissue、という形です。
GitHubのissueは静的（リンクが切れない）ので、サッと作って暫く使うのに向くと考えます。
もしこれを採用するなら、メンテナさんが voicevox_project レポあたりに置くのが丸いと思います。

[Hiroshiba]

なるほどです！　とりあえずissueを作るのが丸いのかなと思いました！

projectのissueはプロジェクトを作ることに使っているので、候補としてはエンジンのissue・.githubのissue・新しくドキュメント用のリポジトリを作ってそこのissueあたりが検討対象になりそうかなと！
とりあえず需要が発生しているのがエンジンなのでここにissueを作り、将来移動が必要になったらtransfer issueするとかが良いのかなと思いました！

そしてすみません、定義文章はあげられているREADMEの箇所に書かれていました。。

voicevox_engine/README.md

Lines 58 to 65 in 16845ab

	`/audio_query`のレスポンスにはエンジンが判断した読み方が AquesTalk ライクな記法([本家の記法](https://www.a-quest.com/archive/manual/siyo_onseikigou.pdf)とは一部異なります)で記録されています。
	記法は次のルールに従います。
	- 全てのカナはカタカナで記述される
	- アクセント句は`/`または`、`で区切る。`、`で区切った場合に限り無音区間が挿入される。
	- カナの手前に`_`を入れるとそのカナは無声化される
	- アクセント位置を`'`で指定する。全てのアクセント句にはアクセント位置を 1 つ指定する必要がある。
	- アクセント句末に`？`(全角)を入れることにより疑問文の発音ができる

なのでこちらを転記したissueを作ることになりそうです。
（長いけどこのパーマネントリンクでもいいのかも？とちょっとだけ思いました）

[tarepan]

定義文章はあげられているREADMEの箇所に

把握しました。

このパーマネントリンクでも

READMEに ### AquesTalk風記法 独立節を作るのはどうでしょうか？
現在はサンプルコード内の記述として混在しているため安定性が低いですが、独立節とすれば変更に強くなります。
幸い #818 で記法正式名がfixしたため、節名称自体は暫く不変で安定になるはずです。

追記:
サンプルとして draftPR (#820) を作成しました。
提案受け入れ可否判断の一助としてご利用ください。

[Hiroshiba]

ありがとうございます！！　ちょっとどうしようか考えてみたいと思います。

---

@y-chan メンテナ判断として相談です！
「AquesTalk風記法」を参照できる先のリンクを作りたいという話なのですが、どうしようかで迷っています。問題はリンク先が変わってしまう可能性がある点です。

今のところREADMEに専用の項目を設けるか、専用のissueを作るかかなと思ってます。
（ドキュメントページを作るという点もありますが、まだ定まってないのでリンク先が一番変わりやすいかなと。。）
それぞれの長所短所があるので、そこをまとめて相談したい感じです。

• READMEに書く場合
  • 👍 ドキュメントっぽい
  • 🤔 リンクが移動する可能性がある（過去のコードからそのリンクへ飛べない）
• issueに書く場合
  • 👍 必ずそのリンクにたどり着ける
  • 🤔 ドキュメントぽくない（後でドキュメント化して案内することはできる）

個人的には、まあそこまで深く考えることでもないので一旦どっちでも良いかなと思っています。必ずリーチできるという点ではissueの方に軍配が上がるかも･･･？って感じですが、どうでしょう 🙇

[Hiroshiba]

こちらに関してですが、特にどちらにしてもそう問題はないので、とりあえずREADMEに追記して、必要に応じてリンクする形で良いのかなと思いました！！