Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Open
2 tasks
nabeta opened this issue Feb 19, 2023 · 15 comments
Open
2 tasks

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

nabeta opened this issue Feb 19, 2023 · 15 comments
Labels
document

Comments

@nabeta
Copy link
Member

nabeta commented Feb 19, 2023 •
edited by yegusa

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

  • GitHubでのビルド環境の整備
  • トップページの作成

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

  • 最重要：相互参照（リンク）をメンテするのが大変だから楽にしたい
  • セクション番号を自動的にしたい　　→　結局　セクション番号を付けるのはツールの事情でつけないことにした
  • PDF版マニュアルを楽に作成できると嬉しい

(#975)
@nabeta
Copy link
Member Author

nabeta commented Feb 19, 2023

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

@yegusa
Copy link

yegusa commented Feb 19, 2023

注意事項：

  • 古いマニュアル 1.1, 1.2, 1.3 はそのままのURLでそのまま残す
  • トップページから↑へのリンクを貼る

@nabeta
Copy link
Member Author

nabeta commented May 14, 2023 •
edited by yegusa

変換作業でやること:

  • 見出しの書式の変換 ・・・　== などとする
  • 手動入力されている節番号とセクションリンクの削除
  • 画像リンクの書式の変換
  • tocの追加
  • コメントの書式の変換 ・・・//// や //　にする
  • HTMLタグのコメント化・・・　スタイル指定のdiv タグを // でコメントアウト

@nabeta
Copy link
Member Author

nabeta commented May 14, 2023

画像リンクの書式の変換

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

@yegusa
Copy link

yegusa commented Jun 11, 2023

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

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

@nabeta
Copy link
Member Author

nabeta commented Jun 11, 2023

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

@yegusa
Copy link

yegusa commented Jul 9, 2023

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

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

@masao
Copy link
Member

masao commented Jul 9, 2023 •
edited

画像の自動変換：

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

@masao
Copy link
Member

masao commented Jul 9, 2023 •
edited

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

変換元：

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

【Memo】

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

変換先：

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

@masao
Copy link
Member

masao commented Jul 9, 2023 •
edited

XMLコード記述：

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

@masao
Copy link
Member

masao commented Aug 20, 2023

ファイルをまたいだ節番号リンクは以下のように書く： ※ xref:filename.adoc#_節タイトル[リンクテキスト]

例:

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

@masao
Copy link
Member

masao commented Aug 20, 2023

ローカルでの実行

$ asciidoctor 1.4/enju_user_5.adoc

@nabeta
Copy link
Member Author

nabeta commented Sep 17, 2023

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

asciidoctor-pdf -a pdf-theme=default-with-fallback-font enju_install_vm_9.adoc

@yegusa yegusa mentioned this issue Sep 17, 2023
Open
5 tasks
@masao
Copy link
Member

masao commented Sep 17, 2023 •
edited

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

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

  • _pdf/enju_install_vm_all.pdf
  • _pdf/enju_operation_all.pdf
  • _pdf/enju_setup_all.pdf
  • _pdf/enju_user_all.pdf
  • _pdf/enju_webapi_all.pdf

@yegusa
Copy link

yegusa commented Sep 17, 2023

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
document
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
3 participants
@nabeta @masao @yegusa