OSS Gate Workshop: online: 2023-07-29: Alt: pandoc: Work log about workshop

[Alt-NoRock]

https://github.com/jgm/pandoc/blob/main/CONTRIBUTING.md
ガイドラインでコントリビューター向けの作法がありました。

[Alt-NoRock]

pandoc URLは下記にありそう
https://github.com/jgm/pandoc

[Alt-NoRock]

ライセンスは下記. GPLv2 (or later / or greater) のライセンスみたい

© 2006-2023 John MacFarlane ([[email protected]](mailto:[email protected])). Released under the [GPL](https://www.gnu.org/licenses/old-licenses/gpl-2.0.html), version 2 or greater. This software carries no warranty of any kind. (See COPYRIGHT for full copyright and warranty notices.)

https://github.com/jgm/pandoc/blob/main/COPYRIGHT にも関連ソフトウェアの記載がある。
こちらもGPLv2が多そうでした。

[Alt-NoRock]

pandocについて、バグ報告についてのお作法の要諦です。

• Github Issue で報告してほしい
• 最新版(v3.1.6)でインストールして再現可能かを検証してほしい(ソースコードビルドは不要)
• レポートには下記を含めてほしい

the pandoc version (check using pandoc -v)
the exact command line used
the exact input used
the output received
the output you expected instead
A small test case (just a few lines) is ideal. If your input is large, try to whittle it down to a minimum working example.

[Alt-NoRock]

インストール方法 (pandoc)

https://github.com/jgm/pandoc/blob/main/INSTALL.md 参照
debファイルなどは、https://github.com/jgm/pandoc/releases/tag/3.1.6 参照

私の場合、Ubuntu22.04 のため、debファイルをダウンロード後は、下記のようなインストール方法と確認でした。

$ sudo dpkg -i pandoc-3.1.6-1-amd64.deb 
$ pandoc -v

pandoc 3.1.6
Features: +server +lua
Scripting engine: Lua 5.4
User data directory: /home/toru/.local/share/pandoc
Copyright (C) 2006-2023 John MacFarlane. Web: https://pandoc.org
This is free software; see the source for copying conditions. There is no
warranty, not even for merchantability or fitness for a particular purpose.

また、texlive もインストール必要とのことでした（こちらはインストール済みでした）

$ sudo apt-get install texlive
パッケージリストを読み込んでいます... 完了
依存関係ツリーを作成しています... 完了        
状態情報を読み取っています... 完了        
texlive はすでに最新バージョン (2021.20220204-1) です。

(reviewdog) toru@deskmini:~/develop/OSSGate/pandoc/installation$ tex
This is TeX, Version 3.141592653 (TeX Live 2022/dev/Debian) (preloaded format=tex)

[Alt-NoRock]

バグ再現（失敗）

---
header-right: '\confi'
header-includes:
  - '`\newcommand{\confi}{\raisebox{0pt}[0pt]{\includegraphics[width=1.5cm]{/template/ng.png}}}`{=latex}'
---

## bug-report

ok

入力ファイルが上記に対して、 pandoc -i test.md -o test.pdf で出力できるが、ヘッダーはなし
一部オレオレの手順が混ざっているので、公式ドキュメントを参照しながらそもそも手順が合っているかを確認します。

[Alt-NoRock]

確認していたバグは厳密に言えば、 pandoc を直接使っていたわけではなく、pandocを使いやすくした dockerfile を利用したので、そちらにバグ報告すべき？
https://github.com/frozenbonito/docker-pandoc-eisvogel-ja/tree/master

[Alt-NoRock]

午後の方針

https://github.com/frozenbonito/docker-pandoc-eisvogel-ja に対して Issue や PR を出すことを目指す

1. バグ報告 (ヘッダーファイルに「のみ」画像添付している場合、PDF生成がエラーになる)
2. VerUpのPR作成（DockerfileにVersionが固定で入っているが、メンテが遅れている）

1はVersion上げたら治るかもしれないので、２→１の順番で実施
(15:30更新）
version上げるのが思っているより大変そうなので、 １を優先にします。

[Alt-NoRock]

バグの再現手順

環境整理

• OS: Ubuntu 22.04.2 LTS
• Docker: docker version 24.0.2, build cb74dfc
• ディレクトリ構成: 下記のフォルダ構成で動作を実施した

$ ls
ng.md  ng.png  ok-icon.png  ok.md

• ファイルの中身: （添付したいんだけど、、、やり方わからず。PNG画像ファイルは何でも良さそう）

OKの場合

$ docker run --rm -v $(pwd):/data frozenbonito/pandoc-eisvogel-ja -o ok.pdf ok.md

NGの場合

$ docker run --rm -v $(pwd):/data frozenbonito/pandoc-eisvogel-ja -o ng.pdf ng.md
Error producing PDF.
! Undefined control sequence.
<argument> \includegraphics 
                 [width=1.5cm]{./ng.png}
l.279 \end{document}

おそらくですが、画像ファイルが本文で添付されていない状態で、ヘッダーに画像ファイルを付けると失敗するのではないかと思っています

（バグの中身の切り分けが未完了なのが悩みどころ）

file:///home/toru/develop/OSSGate/pandoc_docker_example/ok.md

[Alt-NoRock]

VerUpのPR作成

2つのDockerfile ファイル/ 3箇所にバージョンに関する記載がありました。

Pandoc

ARG pandoc_version="2.10"
FROM pandoc/latex:${pandoc_version}

バイナリ配布している最新Ver: 3.1.6
Dockerhubの最新Ver: 3.1.1

eisvogel (latex のテンプレート)

ARG pandoc_version
(中略)
ARG eisvogel_version="1.5.0"
RUN mkdir -p /root/.pandoc/templates \
    && wget https://raw.githubusercontent.com/Wandmalfarbe/pandoc-latex-template/v${eisvogel_version}/eisvogel.tex \
    -O /root/.pandoc/templates/eisvogel.latex

公式の最新Ver: 2.4.0

plantuml

ARG plantuml_version="1.2020.16"
RUN wget https://sourceforge.net/projects/plantuml/files/plantuml.${plantuml_version}.jar/download -O /root/plantuml.jar

公式の最新Ver: 1.2023.7

すべて古いため、Versionの情報を変更したDockerfile で動作確認してVersion更新版のPRを送ってみる
もしかしたら、Version更新でバグの件も治るかもしれないので、こちらを先にやってみる。

[daipom]

https://hub.docker.com/r/pandoc/latex

FROMで指定しているイメージはここですかね？

3.1.1ならTexLiveは2022が入っていそう

[daipom]

あとは時間に余裕があれば、立てたissueに自分で次の内容のコメントを足すと良さそうとおもいました！

• pandocのアップデートで解決するかもしれないと思った
• pandocのバージョンを3.1.1に上げてビルドを試してみたが、次のエラーで失敗してしまう
  • ...

[Alt-NoRock]

候補を考える(やりたいこと/困っていること）

• 機能改善：reviewdog が bandit に対応していない（頑張らないといけない）
  • reviewdow: PRとかの指摘ツール.
  • bandit : python のSASTツール.
• バグ報告：pandoc で 画像のヘッダーファイル作れなかった

候補を考える（やれること）

• C / python ならなんとか書ける
• markdown も書ける
• 他の言語は使うだけ・読めるくらいでPR飛ばすの怖いなあ・・・・・・

いったん、pandoc の バグ報告をやってみることにする

[blacktoad30]

構文のエラー等は既に確認済みですか?

以下が参考になりそうでした。
https://gist.github.com/lisaross/4b5ac90f3ebc9815f444833e4df816de

[Alt-NoRock]

Docker build の結果

Versionの修正に関係なく、ビルドに失敗する。。。？
texlive が古いことが原因に読めるが、おそらくtexlive をインストールしているのは pandoc/latex のDocker
--> やっぱり pandoc公式直さないとだめ？

$ docker build .
docker-pandoc-eisvogel-ja/docker-pandoc-eisvogel-ja$ docker build .
[+] Building 7.8s (6/9)                                                                                                                                              
 => [internal] load build definition from Dockerfile                                                                                                            0.0s
 => => transferring dockerfile: 910B                                                                                                                            0.0s
 => [internal] load .dockerignore                                                                                                                               0.0s
 => => transferring context: 62B                                                                                                                                0.0s
 => [internal] load metadata for docker.io/pandoc/latex:2.10                                                                                                    3.2s
 => [1/5] FROM docker.io/pandoc/latex:2.10@sha256:b2488dcfd075b63d0c5d6b7f08eed6b00b32d14baff6ad89b3a3298ad8b3bd8e                                              0.1s
 => => resolve docker.io/pandoc/latex:2.10@sha256:b2488dcfd075b63d0c5d6b7f08eed6b00b32d14baff6ad89b3a3298ad8b3bd8e                                              0.0s
 => => sha256:ad40aac39c2f9b9b20455fc02520e077ca7c819f128ec0740e4f88af88fa9256 6.11kB / 6.11kB                                                                  0.0s
 => => sha256:b2488dcfd075b63d0c5d6b7f08eed6b00b32d14baff6ad89b3a3298ad8b3bd8e 3.04kB / 3.04kB                                                                  0.0s
 => [internal] load build context                                                                                                                               0.0s
 => => transferring context: 33B                                                                                                                                0.0s
 => ERROR [2/5] RUN tlmgr option repository http://mirror.ctan.org/systems/texlive/tlnet     && tlmgr install adjustbox     babel-japanese     background       4.5s
------                                                                                                                                                               
 > [2/5] RUN tlmgr option repository http://mirror.ctan.org/systems/texlive/tlnet     && tlmgr install adjustbox     babel-japanese     background     collectbox     everypage     footmisc     footnotebackref     fvextra     luatexja     ly1     mdframed     mweights     needspace     pagecolor     sourcecodepro     sourcesanspro     titling     zref     haranoaji     ipaex:
#0 0.382 tlmgr: setting default package repository to http://mirror.ctan.org/systems/texlive/tlnet
#0 0.382 tlmgr: updating /opt/texlive/texdir/tlpkg/texlive.tlpdb
#0 4.506 
#0 4.506 tlmgr: Local TeX Live (2020) is older than remote repository (2023).
#0 4.506 Cross release updates are only supported with
#0 4.506   update-tlmgr-latest(.sh/.exe) --update
#0 4.506 See https://tug.org/texlive/upgrade.html for details.
------
Dockerfile:6
--------------------
   5 |     
   6 | >>> RUN tlmgr option repository http://mirror.ctan.org/systems/texlive/tlnet \
   7 | >>>     && tlmgr install adjustbox \
   8 | >>>     babel-japanese \
   9 | >>>     background \
  10 | >>>     collectbox \
  11 | >>>     everypage \
  12 | >>>     footmisc \
  13 | >>>     footnotebackref \
  14 | >>>     fvextra \
  15 | >>>     luatexja \
  16 | >>>     ly1 \
  17 | >>>     mdframed \
  18 | >>>     mweights \
  19 | >>>     needspace \
  20 | >>>     pagecolor \
  21 | >>>     sourcecodepro \
  22 | >>>     sourcesanspro \
  23 | >>>     titling \
  24 | >>>     zref \
  25 | >>>     haranoaji \
  26 | >>>     ipaex
  27 |     
--------------------
ERROR: failed to solve: process "/bin/sh -c tlmgr option repository http://mirror.ctan.org/systems/texlive/tlnet     && tlmgr install adjustbox     babel-japanese     background     collectbox     everypage     footmisc     footnotebackref     fvextra     luatexja     ly1     mdframed     mweights     needspace     pagecolor     sourcecodepro     sourcesanspro     titling     zref     haranoaji     ipaex" did not complete successfully: exit code: 1

[daipom]

[Alt-NoRock]

file:///home/toru/develop/OSSGate/pandoc_docker_example/ng.png

[Alt-NoRock]

file:///home/toru/develop/OSSGate/pandoc/ok-icon.png

[daipom]

https://hub.docker.com/r/pandoc/latex

FROMで指定しているイメージはここですかね？

[Alt-NoRock]

3.1.1ならTexLiveは2022が入っていそう
先程のログは移行元(pandoc/latex:2.10) に対してでしたが、 pandoc/latex:3.1.1 も同様に2023が入っていないと怒られますね。。。

------                                                                                                                                                  
 > [2/5] RUN tlmgr option repository http://mirror.ctan.org/systems/texlive/tlnet     && tlmgr install adjustbox     babel-japanese     background     collectbox     everypage     footmisc     footnotebackref     fvextra     luatexja     ly1     mdframed     mweights     needspace     pagecolor     sourcecodepro     sourcesanspro     titling     zref     haranoaji     ipaex:                                                                               
#0 0.388 tlmgr: setting default package repository to http://mirror.ctan.org/systems/texlive/tlnet                                                      
#0 0.388 tlmgr: updating /opt/texlive/texdir/tlpkg/texlive.tlpdb
#0 3.302 
#0 3.302 tlmgr: Local TeX Live (2022) is older than remote repository (2023).
#0 3.302 Cross release updates are only supported with
#0 3.302   update-tlmgr-latest(.sh/.exe) --update
#0 3.302 See https://tug.org/texlive/upgrade.html for details.
------

[Alt-NoRock]

英語版のIssue案

Title: Can't convert markdown file that contains an image file only in the header

A sentence description of the problem

Short DESCRIPTION: I can't conver markdown file to PDF file in particular file

My Environment

• OS: Ubuntu 22.04.2 LTS
• Docker: docker version 24.0.2, build cb74dfc
• Directory: ls result is below

$ ls
ng.md  ng.png  ok-icon.png  ok.md

• Files: attached. I think ANY png file raised this promblem,

ng.md

ok.md

success file pattern

$ docker run --rm -v $(pwd):/data frozenbonito/pandoc-eisvogel-ja -o ok.pdf ok.md

sucessed, and generated ok.pdf.

NG file result

$ docker run --rm -v $(pwd):/data frozenbonito/pandoc-eisvogel-ja -o ng.pdf ng.md
Error producing PDF.
! Undefined control sequence.
<argument> \includegraphics 
                 [width=1.5cm]{./ng.png}
l.279 \end{document}

[daipom]

各セクション必要な情報が簡潔にまとまっていて非常に良いと思います！
タイトルの付け方も素晴らしい。タイトルを英語で上手く作るのは慣れないと難しいと思うのですが、とてもいい感じに必要な情報を短く盛り込んだ形にまとめられていると思います。
手練感をすごい感じますｗ

[github-actions]

おつかれさまでした！

ワークショップの終了にともないissueを閉じますが、このまま作業メモとして使っても構いません 👌

ワークショップの感想を集めています！

ブログなどに書かれた際は、このページへリンクの追加をお願いします 🙏

またの参加をお待ちしています！