The parallel package

  • Masaki Waga

This is a SATySFi package providing typesetting of two column texts in parallel. This package is inspired by the LaTeX package with the same name. This is the official repository.

Installation

You can install SATySFi parallel with opam and Satyrographos:

opam install satysfi-parallel

You can also tangle parallel.satyh from parallel.org using GNU Emacs by typing C-c C-v t (or equivalently, M-x org-babel-tangle) after opening parallel.org. Otherwise, you can tangle from command line as follows:

emacs --batch --eval "(require 'org)" --eval '(org-babel-tangle-file "$<")'

Command

The parallel package provides four commands: +parallel, +parallel-bottom, +parallel-top-bottom, and +parallel-bottom-top. Their difference is only the choice of the baseline. Their signatures are as follows.

% This uses embed-block-top, i.e., aligns the baseline of the top lines.
direct +parallel : [float?; float?; block-text; block-text] block-cmd
% This uses embed-block-bottom, i.e., aligns the baseline of the bottom lines.
direct +parallel-bottom : [float?; float?; block-text; block-text] block-cmd
% This uses embed-block-top for the left block and embed-block-bottom for the right block.
direct +parallel-top-bottom : [float?; float?; block-text; block-text] block-cmd
% This uses embed-block-bottom for the left block and embed-block-top for the right block.
direct +parallel-bottom-top : [float?; float?; block-text; block-text] block-cmd

The first and the second arguments are the float values representing the ratios of the left and the right columns, respectively. These values are optional. The third and the forth arguments are the contents of the left and the right columns, respectively.

Examples

The following shows a small working example of parallel package.

@require: stdja
@import: ./parallel

StdJa.document (|
  title = {Example usage of parallel};
  author = {Masaki Waga};
  show-title = true;
  show-toc = false;
|) '< 
   +parallel <
     +p {
       Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
       Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
       Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
       Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
     }
  > <
     +p {
       ぞうの卵はおいしいぞう。ぞうの卵はおいしいぞう。ぞうの卵はおいしいぞう。ぞうの卵はおいしいぞう。ぞうの卵はおいしいぞう。ぞうの卵はおいしいぞう。ぞうの卵はおいしいぞう。ぞうの卵はおいしいぞう。ぞうの卵はおいしいぞう。ぞうの卵はおいしいぞう。ぞうの卵はおいしいぞう。ぞうの卵はおいしいぞう。ぞうの卵はおいしいぞう。ぞうの卵はおいしいぞう。ぞうの卵はおいしいぞう。ぞうの卵はおいしいぞう。ぞうの卵はおいしいぞう。ぞうの卵はおいしいぞう。ぞうの卵はおいしいぞう。ぞうの卵はおいしいぞう。ぞうの卵はおいしいぞう。ぞうの卵はおいしいぞう。ぞうの卵はおいしいぞう。ぞうの卵はおいしいぞう。
     }
  >
>

You can also specify the ratios of the columns as follows. We note that their sum should be smaller than 1.

@require: stdja
@import: ./parallel

StdJa.document (|
  title = {Example usage of parallel};
  author = {Masaki Waga};
  show-title = true;
  show-toc = false;
|) '< 
   +parallel ?:(0.7) ?:(0.28) <
     +p {
       Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
       Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
       Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
       Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
     }
  > <
     +p {
       ぞうの卵はおいしいぞう。ぞうの卵はおいしいぞう。ぞうの卵はおいしいぞう。ぞうの卵はおいしいぞう。ぞうの卵はおいしいぞう。ぞうの卵はおいしいぞう。ぞうの卵はおいしいぞう。ぞうの卵はおいしいぞう。ぞうの卵はおいしいぞう。ぞうの卵はおいしいぞう。ぞうの卵はおいしいぞう。ぞうの卵はおいしいぞう。ぞうの卵はおいしいぞう。ぞうの卵はおいしいぞう。ぞうの卵はおいしいぞう。ぞうの卵はおいしいぞう。ぞうの卵はおいしいぞう。ぞうの卵はおいしいぞう。ぞうの卵はおいしいぞう。ぞうの卵はおいしいぞう。ぞうの卵はおいしいぞう。ぞうの卵はおいしいぞう。ぞうの卵はおいしいぞう。ぞうの卵はおいしいぞう。
     }
  >
>

Dependency

parallel is independent of any external packages except for pervasives, which is distributed with SATySFi.

Contributing

The original source code of this package is written in parallel.org and the distribution is generated by tangling it with GNU Emacs. If you want to make a pull request on GitHub, please modify this file.

It is also welcome to make an issue with a suggestion of improvement, bug fix, and so on.

Implementation

The following shows the implementation of the parallel package.

@require: pervasives

module Parallel : sig

  % This uses embed-block-top, i.e., aligns the baseline of the top lines.
  direct +parallel : [float?; float?; block-text; block-text] block-cmd
  % This uses embed-block-bottom, i.e., aligns the baseline of the bottom lines.
  direct +parallel-bottom : [float?; float?; block-text; block-text] block-cmd
  % This uses embed-block-top for the left block and embed-block-bottom for the right block.
  direct +parallel-top-bottom : [float?; float?; block-text; block-text] block-cmd
  % This uses embed-block-bottom for the left block and embed-block-top for the right block.
  direct +parallel-bottom-top : [float?; float?; block-text; block-text] block-cmd

end = struct
    let get-ratio ratio-opt = 
      match ratio-opt with
      | None -> 0.48
      | Some(ratio) -> ratio

    let parallel-scheme embed-left embed-right ctx left-ratio right-ratio left-block right-block =
      let left-ratio = get-ratio left-ratio in
      let right-ratio = get-ratio right-ratio in
      let left-column-width = (get-text-width ctx) *' left-ratio in
      let right-column-width = (get-text-width ctx) *' right-ratio in
      let margin = (get-text-width ctx) -' left-column-width -' right-column-width in
      let br-left-pbox =
  embed-left ctx left-column-width (fun ctx -> read-block ctx left-block) in
      let br-right-pbox =
  embed-right ctx right-column-width (fun ctx -> read-block ctx right-block) in
      form-paragraph ctx (br-left-pbox ++ (inline-skip margin) ++ br-right-pbox)

    let-block ctx +parallel ?:left-ratio ?:right-ratio left-block right-block =
      parallel-scheme embed-block-top embed-block-top ctx left-ratio right-ratio left-block right-block

    let-block ctx +parallel-bottom ?:left-ratio ?:right-ratio left-block right-block =
      parallel-scheme embed-block-bottom embed-block-bottom ctx left-ratio right-ratio left-block right-block

    let-block ctx +parallel-top-bottom ?:left-ratio ?:right-ratio left-block right-block =
      parallel-scheme embed-block-top embed-block-bottom ctx left-ratio right-ratio left-block right-block

    let-block ctx +parallel-bottom-top ?:left-ratio ?:right-ratio left-block right-block =
      parallel-scheme embed-block-bottom embed-block-top ctx left-ratio right-ratio left-block right-block
end

On the release to satyrographos-repo

Since the source files are tangled from parallel.org, we have to upload an artifact as a tar.gz file and publish an opam package with it. The generation of the artifact tar.gz file is automated by GitHub Actions. What we have to do is as follows.

  1. When we want to publish a new version, we create a new tag vX.Y.Z and push to the GitHub repository.
  2. package.tar.gz is automatically generated by GitHub Actions.
  3. We use opam pubilsh to publish the new release. The following shows an example command to use.
opam publish --repo=na4zagin3/satyrographos-repo https://github.com/MasWag/satysfi-parallel/releases/download/vX.Y.Z/package.tar.gz .