ご協力ください¶
Zettlrをより良いアプリケーションにしたいとお考えですか？素晴らしい！新たに翻訳を提供したい方、開発に参加したい方は、このページをご覧ください。
全般的なリソース¶
Zettlrは、インターネット中で互いに助け合う活発なコミュニティを有しています。あなたが抱いた疑問を投げかけることができる場所を、以下の一覧に示します。
- Zettlr user forum — 一般的な質問、ワークフローやZettlrのコンセプトに関する議論、カスタムテーマの共有まで、このサイトで投稿してください。
- Zettlr subreddit — コミュニティ内のRedditorを対象としたサイトです。
- 公式Twitterアカウント — アプリケーションの更新をリアルタイムに確認することができます。これが、私たちの活動を定期的に知らせる唯一の場所です。さらに、ほとんどの議論もここで行われます。質問がある場合は、ここに投げてください。
- 公式Facebookページ — ツイッターのアカウントを持っていない場合、ここからメッセージを送ることができます。
- YouTubeチャンネル — 視覚からの情報を好む方は、こちらで入門用の動画をいくつか見ることができます。
- The GitHub issue tracker — アプリケーションをより良くしようとする私たちの努力の結晶です。バグの指摘や新機能の提案を行うならこちらです。しかしながら、特にユーザのワークフローや新機能に関わる質問については、まず、フォーラムやRedditで話し合うのが最善です。
ユーザの貢献¶
あなたが、見た目が良くて適切に機能するアプリケーションを求めるユーザーであるならば、エラーが発生したときに見逃さないように、ちゃんと見ていてください。そしてさらに重要なことは、ワークフローをより効率的にする方法を私たちに教えてください。私たちは、私たち自身のワークフローについて判断することしかできません。あなたがより使いやすいアプリケーションとするために、私たちに、その方法を教えてください。ただし、ワークフローをそのままの形で設計に乗せることはできず、他のワークフローとの折り合いをつける必要があることを記憶に留めておいてください。しかし、既存の機能と新提案の機能とのトレードオフが大きくなければ、可能な限り便利でスムーズに動作する機能となるように努力します。
バグ報告は、GitHubリポジトリでIssueをオープンしてください。この方法であれば、私たちが報告に素早く対応できて、直接問題に対処できます。
アプリケーションの翻訳¶
アプリケーションを、地球上に存在するあらゆる言語に翻訳するための協力を歓迎します。翻訳は翻訳サーバにて管理されています。翻訳を行うためには、アカウントの作成が必要です。これは、スパム対策のために行っています。加えて、生成された翻訳データに（あなたが希望するならば）あなたのユーザー名がクレジットされます。
翻訳方法は単純です。メインページで任意の言語をクリックして、現在存在する識別子の一覧を表示します。
左の列に書いてあるのが翻訳IDです。これらは概ね、自己説明的な名前になっています。どのように始めたら良いか分からない場合は、英語の翻訳文と、実際のアプリケーションを見比べてれば、翻訳IDがどの要素に対応しているかが分かると思います。
ユーザベースの品質マネジメントシステムが実装されていて、これは、みなさんが既存の翻訳文に投票することで機能します。つまり、自分で翻訳をしたいと思わなくても、翻訳文の中から適切だと思うものに投票することができるのです。誰かが翻訳をダウンロードする際には、得票数の最も多い翻訳文がシステムにより自動的に選択されることで、翻訳の検証が反映されます。
開発¶
開発を始めるには、リポジトリをフォークし、機能の開発やバグ修正などを行います。それから、プルリクエストをオープンします。developブランチに対してのみプルリクを出すということを覚えておいてください。masterブランチへは、新しいリリースが準備されるときのみpushされます。ですので、新機能を開発しているときにZettlrの新バージョンがリリースされたなら、単純にupstream masterをpullして最新化すれば、機能の開発を続けられます。
機能の開発を始めようと思ったら、新規のissueを作成して他の人に知らせるのが良いでしょう。誰かがすでに取り掛かっていると知らせることで効率を最大化できます。
開発環境のセットアップ¶
すべて準備ができたら、お好きなIDEとターミナルを起動してください。ZettlrはNodeJSスタックに基づいているので、現行のNodeサーバとNodeパッケージマネージャがシステムにインストールされている必要があります。ZettlrではYarnの利用を推奨します。
続いて、初期化を行います。
Yarnを使用
$ git clone https://github.com/Zettlr/Zettlr.git
$ cd Zettlr
$ yarn install
$ cd source
$ yarn install
sourceディレクトリで行う、2回目のinstallは、electron-builderのtwo-directories-structureを使うために必要です。
installコマンドにより、すべてのアセットの初回のプレコンパイルが実行されるので、その後、startコマンドを実行すれば、すぐにアプリケーションを起動することができます。しかし、これらのアセットを編集した場合は、変更点を反映するために再度コンパイルする必要があります。開発用コマンドの説明を読んで、必要なコマンドを探してください。
開発用コマンド¶
ここでは、アプリケーションの開発中に使用できるすべてのコマンドを紹介します。これらは、package.json中に定義されていて、使用するパッケージマネージャに合わせて、npm runまたはyarnに続けて入力することで実行することができます。コマンドは、リポジトリのベースディレクトリで実行してください。
build:quick¶
アプリケーションをローカルでビルドしますが、パッケージは生成しません。使用中のOSに応じてプレビルドされたバイナリが、releaseディレクトリに格納されます。
csl:refresh¶
Citation Style Language(CLS)のファイルをダウンロードし、source/main/assets/csl-localesとsource/main/assets/csl-stylesのディレクトリに、それぞれ格納します。更新の有無をリポジトリに問い合わせるために、必要に応じて実行してください。
handlebars¶
Handlebars.jsのテンプレートファイルの再コンパイルを行い、プレコンパイル済みのテンプレートをsource/common/assets/handlebarsに配置します。
lang:refresh¶
4つのデフォルト翻訳をZettlr Translateからダウンロードします。ファイルは、source/common/langディレクトリに格納されます。現在のところ、デフォルトの言語は、ドイツ語（ドイツ）、英語（USA）、英語（UK）、フランス語（フランス）です。
less¶
LESSソースファイルからCSSを再生成し、source/common/assets/cssに配置します。LESSソースを編集するたびに、このコマンドを実行して変更内容をアプリケーションに反映する必要があります。注意：開発規模が大きい場合は、LESSファイルの変更を監視して自動的に再コンパイルするほうが便利かもしれません。その場合はwatchコマンドを使用してください。
lint¶
設定に従ってESLintを実行し、結果をベースディレクトリのeslint_report.htmに出力します。AtomやVisual Studio Codeのようなアプリケーションでは、バックグラウンドで自動的にESLintが実行されますが、プルリクエストを作成する前には、このコマンドを念のために実行してください。
release:this¶
このコマンドは基本的にはbuild:quickと同じですが、使用しているプラットフォーム向けのパッケージ作成を追加で行います。使用しているOSに応じて.deb、.rpm、.dmg、.exe形式のパッケージが出力されます。
release:app-image¶
AppImageインストーラを明示的に作成します。32bit、64bitの両方のバージョンがコンパイルされます。
release:linux¶
Linux向けのインストーラパッケージを明示的に作成します。.debと.rpmの2つが作成されます。
release:mac¶
macOS向けのインストーラを明示的に作成します。注意：このコマンドはmacOSでのみ動作します。
release:win¶
Windows向けのインストーラを明示的に作成します。electron-builderは32bitと64bitの両方のバージョンのアプリケーションを含めるため、このインストーラは他のインストーラよりも明らかに巨大です。注意：このコマンドはWindowsベースのOS、もしくはLinuxディストリビューションで実行できます。WINEの開発者がライブラリを64bitにポートしない限り、このコマンドはmacOS Catalina以降では失敗します。
reveal:build¶
このコマンドは、reveal.jsプレゼンテーションのエクスポート機能のビルドで必要となるソースファイルを再コンパイルします。Pandocがプレゼンテーションを出力する処理の性質上、ZettlrはPandocの出力を修正する必要があるため、これらのファイルを事前にコンパイルしておきます。
start¶
このコマンドは、Electronを起動しアプリケーションを立ち上げます。開発中に頻繁に使うことになるコマンドです。
test¶
./testディレクトリに配置されたユニットテストを実行します。プルリクエストの送信に先立ってこのコマンドを実行するようにしてください。これは、プルリクエストにコミットが追加されるたびに実行されるので、変更点がテストを破壊していないことを確認することができます。これにより、プルリクエストのプロセス全体を簡単にすることができます。
test-gui¶
テストディレクトリを./resourcesに作成し、シンプルな設定でZettlrを起動します。これにより、実際の自分のファイルに触れることなく、ファイルを破壊する可能性のあるテストを実行することができます。
watch¶
LESSソースの変更を監視するプロセスを起動します。このプロセスが起動している間、LESSファイルに変更があるたびにビルドが実行され、実行中のElectronアプリケーションでF5を押してGUIを更新すると、すぐに変更点を確認することができます。
wp:dev¶
resourcesディレクトリのVue.jsアセットをコンパイルします。Webpackに対して開発モードでコンパイルするように指示するため、ログ出力が多くなりデバッグが容易になります。リリースように出力する場合はwp:prodを実行してください。
wp:prod¶
resourcesディレクトリのVueアセットをコンパイルします。Webpackに対してプロダクションモードでコンパイルするように指示するため、ログ出力が少なくなり、生成されたスクリプトの実行速度が上がります。Vueファイルをデバッグする場合は、wp:devを実行することをおすすめします。
コマンドラインフラグ¶
Zettlrには、いくつかのコマンドラインフラグがあり、開発バージョンと最終ビルドバージョンのいずれでも使用することができます。アプリケーション起動時にフラグを与えてください。開発中はyarn start --flagとすれば使用することができます("flag"を実際のフラグに置き換えてください)。
--config <configFile.json>¶
このフラグにより、普段と異なる設定ファイルを一時的に使用することができます。設定ファイルは、Zettlrの要求する正しいフォーマット(ConfigProviderクラスのコードを参照)である必要があります。しかし、例えば、設定したい項目だけを含むような最小限の内容でもかまいません。設定ファイル中にZettlrの必要とする設定項目が無い場合は、それぞれデフォルト値が設定されます。これは、例えばテスト目的で、アプリケーションに読み込むファイルツリーを簡単に入れ替えたいような場合に、非常に便利です。test-guiコマンドでは、--configフラグを利用して、読み込まれるファイルを安全に触ることのできるものと入れ替えています。
注意: このフラグに渡すパスは、絶対パスである必要があります。相対パスを渡すと意図した動作をしない可能性があります(Good:
--config /Users/name/Documents/custom-config.json; Bad:--config ../resources/my-custom-config.json)。
--clear-cache¶
このフラグを渡すと、強制的にFSALのキャッシュをクリアすることができます。これは、ファイルシステムの基本的な構造を変更しようとする際に非常に便利です。アプリケーションは常にキャッシュを参照しているため、ファイルを編集しない限りは、追加したプロパティが存在しないような振る舞いをします。また、予想外の問題が発生した場合にも役立つかもしれません。
プロジェクト構造¶
技術的な内容に移ります、プロジェクトの構造です。ほとんどの点において、Electronアプリケーション開発のベストプラクティスに従った構造をしています。しかしながら、このアプリケーションは巨大です。それゆえ、いくつかのガイダンスが必要となります。
まずは、ディレクトリ構造を抑えましょう。（これは網羅的なリストではありませんが、必要になるフォルダとファイルはほとんどカバーしています。）
Zettlr // ルートディレクトリ
|
+ release // アプリケーションをビルドすると作成されます。
|
+ resources // 開発用のあらゆる物が格納されています。リリースには含まれません。
| |
| + less // CSSを生成するソースファイルが格納されています。
| |
| + templates // ダイアログとポップアップ用のテンプレートが格納されています。
| |
| + vue // Vueコンポーネントが格納されています。
|
+ scripts // 上述の開発用スクリプトが格納されています。
|
+ source // 実際のアプリケーションソースが格納されています。
| |
| + common // 共通的に使われるファイルです。
| | |
| | + assets // CSS, フォント, HBランタイム, 画像, JS, テンプレート。
| | |
| | + lang // デフォルト言語とi18nモジュール。
| | |
| | + util // アプリケーション全体で使われるユーティリティ関数。
| | |
| | + data.json // アプリケーション用の静的データ。
| | |
| | + validate.js // バリデーションモジュール
| | |
| | + validation.json // バリデーションルール
| |
| + main // メインプロセスのファイル
| | |
| | + assets // メインプロセス用asset
| | |
| | + commands // 実行可能なすべてのコマンド
| | |
| | + modules // モジュール
| | |
| | + providers // アプリケーション用のサービスプロバイダー
| |
| + print // 印刷ウィンドウのソースコード
| |
| + quicklook // QuickLookのソースコード
| |
| + renderer // メインウィンドウのコード
| | |
| | + assets // 描画処理でのみ使われるasset
| | | |
| | | + codemirror // CodeMirrorプラグイン
| | | |
| | | + context // コンテキストメニューで必要なすべてのファイル
| | | |
| | | + toolbar // ツールバーのテンプレート
| | |
| | + dialog // アプリケーションのすべてのダイアログ用のモジュール
| | |
| | + util // 描画処理でのみ使われるユーティリティ関数
| |
| + main.js // アプリケーションのエントリーポイント
|
+ CHANGELOG.md // すべての変更の詳細履歴
用語解説¶
モジュールは常にモジュールを意味するとは限りません、一方でディレクトリとフォルダは同じ意味の場合があります。文脈的なあいまいさが存在するため、ここにZettlrのエコシステムでよく使われる用語を理解するための用語集を用意しました。
フォルダ(Folder)/ディレクトリ(Directory)¶
いずれもファイルシステム上のフォルダの意味で使われます。Zettlrでは、なるべく「ディレクトリ」を使うようにしていますが、フォルダも同じ意味で使われています。
サイドバー(Sidebar)¶
読み込まれたルートディレクトリを表示するための、GUI上で左に表示されるサイドバーを意味しています。
ルート(root)（ディレクトリ/ファイル）¶
アプリケーションで表示できる最上位のディレクトリを意味します。ファイルシステム全体のルートのことではありません。例えば、Linuxで/homeがルートレベルのディレクトリであるのに対して、Zettlrの文脈では、/home/user/Zettlrがルートディレクトリとして読み込まれているなら、それをルートディレクトリと呼びます。その中に含まれているディレクトリやファイルはルートではありません。
添付ファイルサイドバー(Attachment Sidebar)¶
追加のファイルや参考文献を表示するための、GUI上で右側に表示されるサイドバーを意味しています。この名称に満足しているわけではないので、改善案があればお知らせください。
モジュール(Module)¶
基本的にはNPMのモジュールの定義に従っていますが、メインプロセス内には、ファイルシステム抽象化レイヤやエクスポート機能などの「サブモジュール」も存在しています。これらも、独立したモジュールとしてAPIを介してアプリケーションから使用されているため、モジュールとして取り扱われています。
サービスプロバイダ(Service Provider)¶
サービスプロバイダとは、起動中にインスタンス化され、アプリケーションの終了まで実行され続けるクラスのことです。これらは、globalオブジェクトに何らかの機能オブジェクト(ある種の内部API)を加えることで、その機能を提供します。例えば、ログ出力を可能にするログプロバイダは、global.log.verbose('A message!')のように使用できます。他には、global.config.get('config.value')で設定値にアクセスすることができます。
コマンド(Command)¶
Zettlrのエコシステムにおいてコマンドとは、一般的にソフトウェアエンジニアリングの文脈で使われる用語と同じ意味ですが、特別なクラスcommandsが存在ます。コマンドと言えば多くの場合、source/main/commandsディレクトリに存在するコマンドのことです。これらは、ユーザがファイルを開いたりエクスポートしたり保存したりなどの明示的な操作を行うと実行されるコマンドです。
ウィンドウ(Window)¶
Zettlrの文脈では、ウィンドウとはアプリケーションが開いている文字通りのウィンドウを意味するにとどまりません。一般的に、Electronアプリケーションの構造に起因して、ウィンドウはメインプロセスの1つのコントロールクラス、各ウィンドウに対して起動されるレンダラープロセスごとに1つのコントロールクラス、付随してウィンドウにロードされるHTMLファイルで構成されます。
ダイアログ(Dialog)¶
Zettlrにおいてダイアログとは、メインウィンドウに重ねて情報を表示したり、設定フォームを提供したりするウィンドウのことです。例えば、設定ダイアログや、タグ管理、タグクラウド、PDF設定などです。
ポップアップ(Popup)¶
ポップアップはダイアログに似ていますが、ページ全体に重なるのではなく、参照要素を示す矢印が付いた小さなウィンドウを画面に表示します。インタラクティブではないtippy.jsによるツールチップと混同しないでください。
通知(Notification)¶
通知とは、画面に重ねてアプリケーションの右上に表示される通知のことです。
ツールバー(Toolbar)¶
ツールバーとは、Zettlrのメインウィンドウの上部に表示されるボタンが並んだ領域のことです。
エディタ(Editor)¶
エディタとはZettlrのメインウィンドウに表示されるCodeMirrorインスタンスのことです。カスタムCSSダイアログや、QuickLookウィンドウに開かれた他のCodeMirrorインスタンスはエディタとは呼びません。
QuickLook¶
macOSのQuickLook機能と同様に、小さなウィンドウでファイルをプレビューすることができます。編集は行えません。
開発者ツール(DevTools / Development Tools)¶
開発者ツールは、Zettlrのウィンドウ内に表示してGUIのデバッグを行うことができるものです。Chromeブラウザに付属のDevToolsと同じように機能します。デバッグモードが有効の場合に開くことができます。
テーマ(Theme)¶
Zettlrにおけるテーマとは、一般的に使われるテーマと同じ意味ですが、追加で読み込まれるCSSファイルであるgeometry.cssが存在するため、ここに取り上げました。後者は要素の配置とサイズを提供しますが、テーマはほとんど色を提供するためのものです。