lbt 0.5.1 → 0.5.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 673d0151fc1150a586a1fa60bc61ffc6a18365e53853c7bfb4b5ec3d31a25a0a
-  data.tar.gz: '03562857ac14de1f32f0d6ece4a20299f1c44fab8be9f1a1417abf1858335c7b'
+  metadata.gz: a9cf39baff107d837fdd02c88764d3b161b9569cc3298b479917d44b371a3e63
+  data.tar.gz: 754274ca6ee26d3bccfe6b3f1c87621c73ef52bbf37190fc67b9d1cda430b931
 SHA512:
-  metadata.gz: 52603a2abf95b41404fc41c62e8046884b1504d26994c77ef13feeb34435038e3fc1c5a6c3a948acb60a5201320ab1282fab2295f68e689fe19595ca8738d7b7
-  data.tar.gz: bfd3fbd7bdb487acf68dff294e59271fdbe4672936b54b181e26a7523619b01476130c642633ea6448c7d4d6cdf9d1f21022a2f7a86e621501e5cef71e69bef0
+  metadata.gz: 34a14917dc084b5185f7b688d089aed5dd3ac9e28b8805d132ebc61884e7c6739448f49ea482c77eb144502b9bc5f6cb7e0d3b2116939e667afca9dc9d8ca924
+  data.tar.gz: 7afad25c64d3bdd470c61015b090db21aebb527c1b1ffd3fb827a29f1b2642dea937ccf935b66c78de1101dd137af03f284f93f41e366beb613156e989f2a884

data/README.md

@@ -0,0 +1,97 @@
+日本語の説明はこのファイルの後半にあります。
+
+# LaTeX Build Tools
+
+LaTeX Build Tools is a tool to manage big LaTeX source files.
+This version is different from the old versions.
+
+- Use `lbt` command to run every sub commands.
+- It is provided as a gem, which is a Ruby library program.
+
+The old versions, the one with rake and the other of bash scripts, are moved to the other branches, `rake_version` and `bash` respectively.
+
+LaTeX Build Tools supports LuaLaTeX engine only.
+If you want to use another engine, you need to modify `lib/lbt/build.rb` and `lib/lbt/part_typeset.rb`.
+
+## Prerequisite
+
+- Linux operating system
+- Ruby. You can install it by one of the followings.
+  - Install the distribution package
+  - Install it with rbenv. Refer to [Rbenv's GitHub repository](https://github.com/rbenv/rbenv)
+- LuaLaTeX. You can install it by one of the followings.
+  - Install the distribution package
+  - Install TexLive. Refer to [TexLive website](https://tug.org/texlive/)
+
+## Installation
+
+You can install `lbt` from RubyGems.org with gem command.
+
+```
+$ gem install lbt
+```
+
+If you want to install it from the source code, do the following.
+
+1. Click the `Code` button, then click `Download ZIP` in the small dialog.
+2. Unzip the downloaded Zip file, then a new directory `LaTeX-BuildTools-master` will be created.
+3. Type `gem build lbt` under the directory, then the gem file `lbt-X.X.X.gem` is created.
+The number `X.X.X` is the version number like `0.5.2`.
+1. Type `gem install lbt-X.X.X.gem`, where `X.X.X` is the version number.
+
+## Document
+
+See [Tutorial.en](https://toshiocp.github.io/LaTeX-BuildTools/Tutorial_en_md.html).
+
+## License
+
+GPL. See [License.md](License.md).
+
+----------
+
+# LaTeX Build Tools
+
+LaTeX Build Toolsは大きなLaTeXソースファイルを管理するためのツールです。
+現在の版は次の2点が旧版と異なっています。
+
+- lbtというコマンドからすべてを起動
+- gem（Rubyのライブラリ・プログラム）として提供される
+
+旧版の、rakeを用いる版とbashスクリプト版は、それぞれ`rake_version`ブランチと`bash`ブランチに移動しました。
+
+LaTeX Build ToolsがサポートするLaTeXエンジンはLuaLaTeXです。
+その他のエンジンを使いたい場合は`lib/lbt/build.rb`と`lib/lbt/part_typeset.rb`の修正が必要です。
+
+## 動作条件
+
+- Linux オペレーティング・システム
+- Ruby。Rubyのインストール方法は次の2通りがある
+  - ディストリビューションのパッケージをインストール
+  - Rbenvを用いてインストール。詳しくは[RbenvのGitHubレポジトリ](https://github.com/rbenv/rbenv)を参照してほしい
+- LuaLaTeX。LuaLaTeXのインストール方法は次の2通りがある
+  - ディストリビューションのパッケージをインストール
+  - TexLiveをインストール。詳しくは[TexLiveのウェブサイト](https://tug.org/texlive/)を参照してほしい
+
+## インストール
+
+gemコマンドでRubyGems.orgから`lbt`をインストールする。
+
+```
+$ gem install lbt
+```
+
+以上が最も簡単なインストール方法だが、ソースコードからインストールしたい場合は次のようにする。
+
+1. GitHubのレポジトリを開き`Code`ボタンをクリック。小さいダイアログが現れるので、`Download ZIP`をクリックする
+2. ZIPファイルを解凍すると`LaTeX-BuildTools-master`というディレクトリが作られる
+3. 端末をそのディレクトリに移動して`gem build lbt`とタイプすると、`lbt-X.X.X.gem`というGemファイルが作られる。
+この中の`X.X.X`はバージョン番号で、例えば`0.5.2`などのようなものである
+4. `gem install lbt-X.X.X.gem`とタイプしてインストールする（`X.X.X`はバージョン番号）
+
+## ドキュメント
+
+使い方の説明は[Tutorial.ja](https://toshiocp.github.io/LaTeX-BuildTools/Tutorial_ja_md.html)を参照してほしい。
+
+## ライセンス
+
+GPL。[License.md](License.md)を参照。

data/Tutorial.en.md

@@ -0,0 +1,160 @@
+# Installation
+
+The followings are required for LaTex-Buildtools.
+
+- Ruby
+- LualaTeX
+- Lbt (lbt is Latex-Buildtools)
+
+The first two items can be installed from the distribution package.
+For example, You can use the `apt` command in Ubuntu.
+
+Lbt is provided as a Ruby Gem.
+It can be installed with the `gem` command from RubyGems.org.
+
+```
+$ gem install lbt
+```
+
+# Creating a directory and templates for source files
+
+The rest of this tutorial shows how to use `lbt` with an example.
+Its source file is this tutorial.
+
+First, use a `new` subcommand to create a directory and templates for source files.
+The `new` subcommand takes the directory name, document class name, and working directory name as arguments.
+The last two arguments can be left out.
+Their default values are `book` and `_build` respectively.
+In this example, we use `article` document class.
+
+```
+$ lbt new Tutorial article
+$ cd Tutorial
+$ ls -a
+. .. .config helper.tex main.tex
+```
+
+The working directory name is written in the `.config` file.
+
+```
+$ cat .config
+build_dir = _build
+```
+
+Since the working directory name was left out, it is `_build` (default value).
+It is used when `build` and `part_typeset` subcommands are executed.
+
+The file `main.tex` is the route file of LaTeX sources.
+
+```
+$ cat main.tex
+\documentclass{article}
+\input{helper.tex}
+\title{Title}
+\author{Author}
+\begin{document}
+\maketitle
+\tableofcontents
+
+\end{document}
+```
+
+The title and the author need to rewrite.
+They are changed to "Tutorial" and "Toshio Sekiya" respectively.
+
+The file `helper.tex` is included into the preamble part of `main.tex`.
+Its contents are mainly package including and command definitions.
+
+```
+$ cat helper.tex
+\usepackage{amsmath,amssymb}
+\usepackage[luatex]{graphicx}
+\usepackage{tikz}
+\usepackage[margin=2.4cm]{geometry}
+\usepackage[colorlinks=true,linkcolor=black]{hyperref}
+% If your source includes Markdown, you may need the following lines.
+% It is because Pandoc generates some undefined commands.
+% The Pandoc template file shows how to define them.
+% You can see it by 'pandoc --print-default-template=latex'.
+\providecommand{\tightlist}{%
+  \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}
+```
+
+Since we don't need `tikz` package in this example, it can be deleted.
+But you can leave it if you want.
+The last two lines are required when converting Markdown files to LaTeX files with Pandoc.
+The source, which is this tutorial, is Markdown, so we will leave them.
+
+# Creating sub files
+
+This tutorial has six sections.
+We divide it into six files sec1.md, sec2.md, ... and sec6.md
+They are put under the top directory.
+
+# Typesetting
+
+Converting LaTeX source files into a PDF file is called typesetting.
+You can typeset them with `build` subcommand of Lbt.
+
+```
+$ lbt build
+```
+
+There are many converting processes.
+Finally a PDF file `Tutorial.pdf` is made in the top directory.
+The name of the PDF file is the same as the title in the source file.
+
+# Partial typesetting
+
+The bigger are the LaTeX sources, the longer time the typesetting takes.
+Even if your modification is in only one, `build` subcommand converts all the source files.
+It takes long time.
+The subcommand `part_typeset` provides one file typesetting.
+So it is faster than `build` subcommand.
+
+```
+$ lbt part_typeset 1
+```
+
+The argument `1` means `sec1.md`.
+If you want to type sec5.md, use 5 instead of 1.
+
+For large documents with parts and chapters, for example, specify "1-2-4" for part1/chap2/sec4.tex.
+
+The result is `_build/main.pdf`.
+
+# Renumbering
+
+Sometimes you may want to insert a section between sec1.md and sec2.md.
+At that time, name it sec1.5.md.
+If you want to renamed these (sec1.md, sec1.5.md and sec2.md) into consecutive number filenames (sec1.md, sec2.md, and sec3.md), use `renum` subcommand.
+
+```
+$ lbt renum
+```
+
+# Pandoc and Top-Level-Division option
+
+Lbt uses Pandoc to convert Markdown to LaTeX.
+The default behavior of Pandoc is from the ATX-heading `#` to `\section`.
+See `--top-level-division` option in the Pandoc document.
+
+You can change it by modifying `.config` file in your LaTeX-file directory.
+For example, the following makes the conversion from `#` to `\chapter`.
+
+```
+$ cat .config
+build_dir = _build
+top-level-division = chapter
+```
+
+The format is `top-level-division = (part, chapter or section)`.
+
+The table shows the commonly used top-level-division.
+
+|documentclass|top level division|
+|:-----|:-----|
+|book|chapter or part|
+|report|chapter|
+|article|section|
+|beamer|section|

data/Tutorial.ja.md

@@ -0,0 +1,155 @@
+# インストール
+
+Latex-Buildtoolsを使うには次の3つが必要です。
+
+- Rubyのインストール
+- LuaLaTeXのインストール
+- Lbt（lbtはLatex-Buildtoolsのことです）のインストール
+
+最初の2つはディストリビューションのパッケージをインストールするのが最も簡単です。
+例えばUbuntuであればaptコマンドを使います。
+
+LbtはRubyのgemとして提供されるので、gemコマンドでインストールします。
+
+```
+$ gem install lbt
+```
+
+# ソースファイル用ディレクトリとテンプレートの作成
+
+ここでは、このチュートリアルをPDFファイルに変換することを通してLbtの使い方を示します。
+
+最初にソースファイル用ディレクトリとテンプレートを作成するために、newサブコマンドを使います。
+newサブコマンドには、ディレクトリ名、ドキュメントクラス名、作業ディレクトリ名を引数に与えますが、後ろの2つは省略できます。
+省略した場合のデフォルト値はそれぞれbookと\_buildです。
+ここではltjsarticleドキュメントクラスを使います。
+
+```
+$ lbt new Tutorial ltjsarticle
+$ cd Tutorial
+$ ls -a
+.  ..  .config  helper.tex  main.tex
+```
+
+.configファイルには作業ディレクトリ名の定義が書かれています。
+
+```
+$ cat .config
+build_dir = _build
+```
+
+newサブコマンドで作業ディレクトリ名を省略したので、デフォルト値の\_buildになっています。
+これはbuildとpart\_typesetサブコマンド実行時に参照されます。
+
+main.texはLaTeXソースのルートファイルです。
+
+```
+$ cat main.tex
+\documentclass{ltjsarticle}
+\input{helper.tex}
+\title{Title}
+\author{Author}
+\begin{document}
+\maketitle
+\tableofcontents
+
+\end{document}
+```
+
+タイトルと著者は書き換えが必要です。
+タイトルを「チュートリアル」に、著者を「関谷　敏雄」に変更しておきます。
+
+helper.texはプリアンブル部に取り込まれます。
+主にパッケージの取り込みとコマンドの定義をします。
+
+```
+$ cat helper.tex
+\usepackage{amsmath,amssymb}
+\usepackage[luatex]{graphicx}
+\usepackage{tikz}
+\usepackage[margin=2.4cm]{geometry}
+\usepackage[colorlinks=true,linkcolor=black]{hyperref}
+% If your source includes Markdown, you may need the following lines.
+% It is because Pandoc generates some undefined commands.
+% The Pandoc template file shows how to define them.
+% You can see it by 'pandoc --print-default-template=latex'.
+\providecommand{\tightlist}{%
+  \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}
+```
+
+今回はtikzは必要ないので削除しても構いませんが、ここではそのままにしておきます。
+最後の2行は、PandocでMarkdownファイルをLaTeXファイルに変換するときに必要です。
+今回のソースはMarkdownなので、このまま残しておきます。
+
+# 本文ファイルの作成
+
+今回はこのファイル（Readme.ja.md）をセクションごとに別ファイルにしてトップディレクトリに配置します。
+最初の節（インストール）をsec1.mdとし、以下sec2.md、sec3.md・・・とします。
+このファイルからコピペしてそれぞれのファイルを作ってください。
+
+# タイプセット
+
+LaTeXのソースファイルからPDFファイルを作ることをタイプセットといいます。
+タイプセットはbuildサブコマンドで実行できます。
+
+```
+$ lbt build
+```
+
+この実行によってトップディレクトリにPDFファイルが生成されます。
+ファイル名にはタイトルが使われるので、「チュートリアル.pdf」となります。
+
+# 部分タイプセット
+
+LaTexのソースが大きくなると全体のタイプセットに時間がかかるようになります。
+1つのファイルを書いていて、そのPDFの出来栄えを確かめたいときに全体をタイプセットするのは時間がかかりすぎます。
+そのときは、該当のファイルのみをタイプセットすることができます。
+
+```
+$ lbt part_typeset 1
+```
+
+引数の1はsec1.mdのことです。
+もしsec5.mdをタイプセットしたければ1の代わりに5を使ってください。
+
+PartやChapterのある大きな文書では、例えばpart1/chap2/sec4.texに対して「1-2-4」と引数を指定してください。
+
+コンパイル結果は`_build/main.pdf`に保存されます。
+
+# リナンバー
+
+ときにはsec1.mdとsec2.mdの間にセクションを挿入したいことがあるかもしれません。
+そのときにはsec1.5.mdとしてください。
+これらをsec1.md、sec1.5.md、sec2.mdからsec1.md、sec2.md、sec3.mdのように連続する正整数に直すことをリナンバーと呼ぶことにします。
+renumサブコマンドを実行することでリナンバーできます。
+
+```
+$ lbt renum
+```
+
+# Pandoc と Top-Level-Division オプション
+
+LbtはPandocを用いてMarkdownをLaTeXに変換しています。
+デフォルトでは、PandocはATX見出しの`#`を`\section`に変換します。
+詳しくはPandocのドキュメントの`--top-level-division`を参照してください。
+
+これを、LaTeXファイルのディレクトリにある`.config`ファイルを書き換えることで変更できます。
+例えば、下記のようにすると、`#`が`\chapter`に対応するようになります。
+
+```
+$ cat .config
+build_dir = _build
+top-level-division = chapter
+```
+
+書き方の書式は`top-level-division = (part, chapter or section)`です。
+
+下記の表は一般的に良く用いられるtop-level-divisionです。
+
+|documentclass|top level division|
+|:-----|:-----|
+|book|chapter or part|
+|report|chapter|
+|article|section|
+|beamer|section|
+

data/lib/lbt/build.rb

@@ -3,8 +3,8 @@ require_relative 'utils.rb'
 module Lbt
   # Typeset LaTeX source files into a PDF file.
   def build
-    m = File.read(".config").match(/^build_dir = (.*)$/)
-    build_dir = m[1] ? m[1] : "_build"
+    m = get_config[:'build_dir']
+    build_dir = m ? m : "_build"
     raise "main.tex not exist." unless File.exist?('main.tex')
     mkdir build_dir unless Dir.exist?(build_dir)
 

data/lib/lbt/part_typeset.rb

@@ -16,8 +16,8 @@ module Lbt
       return unless File.file? file
     end
 
-    m = File.read(".config").match(/^build_dir = (.*)$/)
-    build_dir = m[1] ? m[1] : "_build"
+    m = get_config[:'build_dir']
+    build_dir = m ? m : "_build"
     raise "main.tex not exist." unless File.exist?('main.tex')
     mkdir build_dir unless Dir.exist?(build_dir)
 

data/lib/lbt/utils.rb

@@ -105,9 +105,17 @@ If the files are as above, the PCS instance keeps the six filenames whch are sor
     end
   end
 
+  # Convert '.config' file into a Hash
+  def get_config
+    return {} unless File.exist?(".config")
+    File.read(".config").split(/\n/).map{|s| s.split('=')}.map{|key, val| [key.strip.to_sym, val.strip]}.to_h
+  end
+
   # Return a hash (key: extension, value: Proc object) of converters.
   def get_converters
-    converters = {'.md':  lambda {|src, dst| system("pandoc -o #{dst} #{src}")} }
+    tld = get_config[:'top-level-division']
+    tld = tld ? tld : "default"
+    converters = {'.md':  lambda {|src, dst| system("pandoc --top-level-division=#{tld} -o #{dst} #{src}")} }
     if File.file?("converters.rb")
       c = eval(File.read("converters.rb"))
       c.each {|key, val| converters[key] = val} if c.is_a?(Hash)

metadata

@@ -1,22 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: lbt
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.5.3
 platform: ruby
 authors:
 - Toshio Sekiya
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-10-18 00:00:00.000000000 Z
+date: 2023-10-24 00:00:00.000000000 Z
 dependencies: []
 description: Lbt is a build tool for LaTeX. It is useful for big documents.
 email: lxboyjp@gmail.com
 executables:
 - lbt
 extensions: []
-extra_rdoc_files: []
+extra_rdoc_files:
+- README.md
+- Tutorial.en.md
+- Tutorial.ja.md
 files:
+- README.md
+- Tutorial.en.md
+- Tutorial.ja.md
 - bin/lbt
 - images/gecko.png
 - images/lagoon.jpg
@@ -29,7 +35,8 @@ files:
 homepage: https://github.com/ToshioCP/LaTeX-BuildTools
 licenses:
 - GPL-3.0
-metadata: {}
+metadata:
+  documentation_uri: https://toshiocp.github.io/LaTeX-BuildTools/
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -45,7 +52,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
+rubygems_version: 3.4.21
 signing_key:
 specification_version: 4
 summary: LaTeX Build Tools