On Thu, Apr 8, 2021 at 11:57 PM Akihiro Motoki <amoto****@gmail*****> wrote: > > 提案してもらっている内容だと、ページを開いたときに、 git repo の準備で画面が専有されてしまいます。 > たぶん慣れてきてから、このページを参照すると、このページは必要な情報がスクロールしないと > 参照できないよね、と思ってしまうでしょう。ドキュメントはこういうバランスも考えて書いています。 > 知ってる人で、ちょっと忘れたから見直すだと、完全に上半分はじゃま、だと思ってしまいます。 > > 改善はいろいろあるけど、どうやってレビューすればいいのかな。 > これを考えるのが面倒なので、放置します。 一応もう少し見てみました。 自分がちゃんとこのページを書くならこんな感じですかね。 (GitHub は Sphinx 記法を全部理解するわけではないので、その辺は多めに見てください) https://github.com/amotoki/jm/blob/guide-help-update/guide/document_help.rst 差分はこんな感じ → https://github.com/amotoki/jm/commit/4aa24ac816a20afbc833b4548bb548040934306e # osdn.net の pull request はヘボ過ぎて話にならない。 # linuxjm をなぜ GitHub でホストしなかったのか後悔しかない・・・・ # (理由は一応あるけど、今となってはミラーサイトとして使っておけばよかった) > > 以下は質問。 > > > 「全体を俯瞰する資料」をお書きになるとおっしゃっていましたが > > "https://osdn.net/users/ribbon/pf/linuxjm/wiki/概要案" が、 > > それなのですか。それについては別のメールに書きます。 > > ふと、思ったのですが、上記のページの話題はメーリングリストでは > 一度も出ていないですよね。なぜ俎上に上がっているのか不思議でしたが、 > https://osdn.net/users/ribbon/pf/linuxjm/wiki/FrontPage を見に行ったときに > 更新履歴で出てきて気になったのかなと思いました。 > このスレッドは、あくまで「ドキュメント編集メモ」 > http://linuxjm.osdn.jp/guide/document_help.html の更新だと思ったので、 > ちょっと困惑しています。 > > では。 > > > On Thu, Apr 8, 2021 at 9:00 AM 長南洋一 <cyoic****@maple*****> wrote: > > > > 長南です。 > > > > 反論ではありませんでした。単なるコメントです。反論は「概要案」の方についてです。 > > > > 「全体を俯瞰する資料」をお書きになるとおっしゃっていましたが > > "https://osdn.net/users/ribbon/pf/linuxjm/wiki/概要案" が、 > > それなのですか。それについては別のメールに書きます。 > > > > 私としては、「全体を俯瞰する資料を書く」というのは、git の共有リポジトリの > > クローン方法や、共有リポジトリに書き込むために必要な公開鍵などについて、 > > 一般的な情報をガイド文書の別のセクションとして書くことだと考えていました。 > > それが先にないと、この「ドキュメント編集メモ」の記述が、こことは直接関係の > > ないことまで考えに入れて書くことになるので、どうしてもゴタゴタしてしまうと > > 思います。言いすぎたり、言わなすぎたり。たとえば、「以下の説明ではすべて > > カレントディレクトリが jm であることを仮定しています」と一般的な説明を > > すると、すぐ次の節の > > > > $ pip install -r requirements.txt > > > > と齟齬が生じてしまうわけです。何故なら、requirements.txt は jm/guide に > > あるので、実行の前にカレントディレクトリを guide にしなければならない > > からです。そして、そのへんを詳しく説明していくと、どうしても記述がゴタゴタ > > してしまう。 > > > > カレントディレクトリをはっきりさせる必要がある場合は、元木さん式に > > "cd <JM_GIT_REPO_TOP>/guide" などを使うのもよいと思います。 > > > > なお、リポジトリの clone については、ここよりも LDP man-pages や > > GNU_coreutils の翻訳ガイドで説明する方がふさわしいと思います。 > > リポジトリの clone は、LDP man-pages や GNU_coreutils を > > 翻訳する上でも絶対必要な情報ですし、そうした man ページの翻訳の方が、 > > このドキュメント群の編集よりも、重要なことですから。もちろん、ここに > > 重複して書いてあっても構いません。もっとも、私としては、「管理ガイド」 > > にまで関係があることですから、ここでも、LDP man-pages などの > > 翻訳ガイドでもなく、ガイド文書の最初の方のセクションにまとめて書いて > > おくことをおすすめしますけれど。 > > > > pip のインストールについての説明にも、実は面倒くさい問題がからんでいます。 > > 元木さんが [JM:02115] と [JM:02120]でおっしゃっているのは、 > > 次のようなことでしょう。 > > > > osdn (の shell server) が使っている python は python2 だ。 > > だから、ローカルでドキュメント類の執筆・編集をし、JM のサイトで > > 実際にどんなふうに見えるかを確認したかったら、python3 ではなく、 > > python2 と python2 用の sphinx を使う必要がある。 > > > > なお、現在では sphinx-bootstrap-theme は使っていないので、 > > それは入れる必要がない。 > > > > ディストリビューション所収の sphinx のインストールについて書くのは、 > > 考えるだけで、面倒くさくなります。今さら、python2 用のパッケージを > > 入れることを勧めてよいものかどうか。かと言って、python3 用の sphinx > > では、JM の実際のサイトと表示が同じになることを保証できないし。 > > > > この文書の読者はかなりのベテランユーザーでしょうから、何かをインストール > > しろと言われたときは、当然 apt などのパッケージ管理ツールを考えるでしょうし、 > > また、python3 用の sphinx をインストールして使用したって、実のところ > > python2 版と結果にたいした違いはないだろうと思います。ですから、私なら、 > > ディストリビューション版については、何も書かずにすませてしまいます。 > > 逃げですけれど。 > > > > -- > > 長南洋一 > > > > _______________________________________________ > > linuxjm-discuss mailing list > > linux****@lists***** > > https://lists.osdn.me/mailman/listinfo/linuxjm-discuss
Fork