Hacktoberfest 2026：メンテナが10月に向けて印を付けた、オープンで初心者向けの issue。 Hacktoberfest の issue を見る

Documentation of complicated options

オープン
  • 何か問題がありますか？
#5 コメント 7 件 リアクション 0 件 担当者 0 名 GitHub で見る

まだ誰も着手していません。

評価

難易度
5/5
見積もり時間
1週間以上
初心者へのやさしさ
25/100
issue の種類
ドキュメント
明瞭さ
説明が足りない
活発さ
停滞
領域
data-visualization, documentation

調査の方向性

まず plot のドキュメント、既存のテスト、ギャラリーの例を確認します。特に、issue で言及されている quoted-line、decorated-line、segmentation、front、custom-symbol、error-bar、vector-attribute に関する資料を確認してください。説明用のイラストを含む相互にリンクされた詳細ページを作成し、それらを関連するモジュールのドキュメントおよび HOW-TO エントリに接続すれば完了です。

索引モデルが issue の本文から書いたものです。

説明

The plot module is very powerful and very complicated to fully understand. There is an ocean of complexity between specifying how to plot a circle and how to plot a quoted line. The circle only has size, color, and pen to worry about, while for the quoted line we have six directives that determine where the text will be placed, then up to 20 modifiers to control various aspects of the result, from fonts to alignments to text being placed. Decorated lines are simpler in that there are only 8 modifiers to worry about. The segmentation option (-F) is another plot option that I think is extremely difficult to penetrate without more explanations in the form of examples. The error bar option -E, which includes box-and-whisker specifications, could also need a simple plot to explain the moving parts. There are probably others.

We actually have many examples of these options spread across our tests and gallery. However, I do not think we want to add page-size plots needed to fully cover quoted lines directly in the plot documentation. My proposal is therefore this:

Have more of a teaser figure as a heading for quoted lines and similar complicated options. This has been implemented. Then, there should be a link to a separate page for more details, similar to how we punt off the full explanation for all the modifiers related to vectors. I think the same applies to decorated lines, segmentation, and probably fronts. And custom symbols. We have an appendix on the custom symbol macro but very few pictures. The simpler stuff like error bars can fit in a small figure beneath that option.

The new pages should also form the backbone of another entry to the documentation that does not go through the modules. We have talked about this before as well. E.g., maybe a HOW-TO page that lists various how-tos:

  • How to plot symbols?
  • How to draw lines?
  • How to plot polygons?
  • How to plot text?
  • How to plot grids?

etc. These would cross-link to the detailed pages and back to the corresponding modules. The modules would also link to the same pages. So whether you know you need to use plot of whether you just know you want to plot lines, in either case you will find eventually yourself on the same page discussing the details, with examples. I note the vector attribute page that explains all the modifiers is completely free of illustrations. I think with GMT, a picture really is worth a 1000 words, so there is much to do here. A competent GMT scripter could make many of these illustrations.

主要言語
言語のデータがありません
スター
7
フォーク
1
30日以内にマージされた PR はありません

環境構築

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

GenericMappingTools/gmt-examples のほかの issue

GenericMappingTools/gmt-examples の issue をすべて見る

似ている issue

Data Visualization の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。