search

next-l / enju_leaf

Next-L Enju Leaf 統合図書館管理システム / integrated library system https://enju.next-l.jp/
https://www.next-l.jp
MIT License
117 stars 25 forks source link

1.4以降のマニュアルの再構成を行う #1787

Open nabeta opened 1 year ago

nabeta commented 1 year ago

現在のマニュアルは、章番号を手動で振らなければならず、メンテナンスに手間がかかる。Sphinxは章番号を自動で振ってくれるため、こちらに置き換える。以下を行った上でコンテンツの移行を行う。

参考：なぜやろうと思ったかの主旨

(#975)

nabeta commented 1 year ago

documentationリポジトリを作った。 https://github.com/next-l/documentation

yegusa commented 1 year ago

注意事項：

nabeta commented 1 year ago

変換作業でやること:

nabeta commented 1 year ago

画像リンクの書式の変換

マニュアルの手順をリストで書き直すのは編集がたいへんなため、本来のマークアップの意味とは異なるが、見出し====で代用する。

yegusa commented 1 year ago

進行状況は以下に記録します。

https://docs.google.com/spreadsheets/d/1QCCYkfdKknp3PbaXkZBj9bgF5Wso2t4MOC3xEQVqqCo/edit?usp=sharing

nabeta commented 1 year ago

テーマは現在のものにこだわらず、AsciiDocで利用できるものを別途使用する。

yegusa commented 1 year ago

Enju WS(2023-07-09) で決めた：

複数ファイルで入力して、セクションナンバーの自動割り付けはできなそうなのと、 AsciiDocではセクションナンバーをつけないのが主流っぽいので、 そもそもセクションナンバーはつけないことにする

masao commented 1 year ago

画像の自動変換：

$ for f in 1.4/enju_user*.adoc; do
    ruby -pe 'gsub(/^\!\[(.+?)\]\((.+)\)\s*$/){ "image::#$2[#$1]" }' $f > z
    mv -f z $f
done
masao commented 1 year ago

メモは NOTE 構文に置き換える：

変換元：

<div class="alert alert-info memo" markdown="1">

【Memo】

* ユーザ名、利用者番号、貸出履歴が表示されます。
</div>

変換先：

[NOTE]
====
* ユーザ名、利用者番号、貸出履歴が表示されます。
====
masao commented 1 year ago

XMLコード記述：

[source,xml]
----
<note>
<from>masao</from>
<to>nabeta</to>
<body>test test</body>
</note>
----
masao commented 1 year ago

ファイルをまたいだ節番号リンクは以下のように書く：

書式： xref:filename.adoc#節タイトル[リンクテキスト]

例:

また、貸出の履歴を保存する（xref:enju_user_3.adoc#メールアドレスや名前などを変更する[3-2節参照]）にチェックを入れておくと、返却した本も記録され、閲覧できるようになります。

注：節タイトルのアルファベットの大文字がある場合は小文字にすること。 例：節タイトルが「Enjuのインストール」であれば、「enjuのインストール」とする。

masao commented 1 year ago

ローカルでの実行

$ asciidoctor 1.4/enju_user_5.adoc
nabeta commented 1 year ago

PDFの作成時には、-a pdf-theme=default-with-fallback-fontオプションを指定しないと、日本語フォントが読み込まれない。

asciidoctor-pdf -a pdf-theme=default-with-fallback-font enju_install_vm_9.adoc
masao commented 1 year ago

マニュアルそれぞれをまとめたPDFファイルを自動生成するスクリプトを _pdf/convert-adoc2pdf.rb として追加しました。

スクリプトを実行すると、以下のファイルが生成されます:

yegusa commented 1 year ago

メモ： @masao によると、htmlもpdfも節番号が付けられる方法がわかったらしい。