mnogootex 0.2.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: aa5c4c34f4297f240efb250291489dc7e475809c
-  data.tar.gz: 192650acf878934caea98fa0377043e34956936e
+SHA256:
+  metadata.gz: edf454b8fab7fe98488bade01dd2c59b3419d5afb9bc4a6c7cadca1cd36bf296
+  data.tar.gz: 1036a5f4e565b1deef11daa6c5418eeb4f357e942fc55009d92f7fc6cfd9dcbe
 SHA512:
-  metadata.gz: 383f762f56a031ca71c41a821dbe877c0028b2c5e53c806694283237967aec7e1b6b1744a453aed2fa5e76781cba7ec12f9db3f0433c7fc30cd5784bac73bc18
-  data.tar.gz: 4dc7c17a9af98cd3a1681b14966364284a627fed718b8f23bc4948ac80e6dc73b9c3ebe46fc9cb92c71307c755c5e92ff77eefcf453aec0619a72b525afb831e
+  metadata.gz: 0c47604bd0302b39ab98ac7417fd0b1b720360c6e54650cc99383237ef2c42cbc65b2edebad71b44d7a662a21aa3740b6f71a66712b87af09d253d86de142989
+  data.tar.gz: 7e00d8a660f75ac7e04e0ba8befea9553f33d8f94b692f31bd634f333043a29abf0eb6eef619389dbf1cc31496ea299ed101b0f4311080ce0e47904983aa939a

data/.github/actions/setup-ruby/action.yml

@@ -0,0 +1,34 @@
+name: Setup Ruby
+description: Setup Ruby
+inputs:
+  ruby-version:
+    required: false
+    default: '2.7'
+  cache-path:
+    required: false
+    default: vendor/bundle
+  cache-key:
+    required: false
+    default: gems-
+  cache-restore-keys:
+    required: false
+    default: gems-
+outputs: {}
+runs:
+    using: "composite"
+    steps:
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ inputs.ruby-version }}
+      - name: Cache Ruby gems
+        uses: actions/cache@v2
+        with:
+          path: ${{ inputs.cache-path }}
+          key: ${{ inputs.cache-key }}
+          restore-keys: ${{ inputs.cache-restore-keys }}
+      - name: Install Ruby gems
+        shell: bash
+        run: |
+          bundle config path ${{ inputs.cache-path }}
+          bundle install --jobs 4 --retry 3

data/.github/workflows/main.yml

@@ -0,0 +1,44 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ 'ubuntu-latest', 'macos-latest' ]
+        ruby: [ '2.6', '2.7', '3.0' ]
+        include:
+          - os: ubuntu-latest
+            ruby: '2.7'
+            coverage: true
+
+    steps:
+
+      - name: Checkout repo
+        uses: actions/checkout@v2
+
+      - name: Setup Ruby
+        uses: ./.github/actions/setup-ruby
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          cache-key: gems-${{ matrix.os }}-${{ matrix.ruby }}-${{ hashFiles('Gemfile', 'mnogootex.gemspec') }}
+          cache-restore-keys: gems-${{ matrix.os }}-${{ matrix.ruby }}-
+
+      - name: Run tests
+        run: bundle exec rake spec:rspec
+
+      - name: Test and publish coverage to Code Climate
+        uses: paambaati/codeclimate-action@v3.0.0
+        if: ${{ matrix.coverage && github.ref == 'refs/heads/main' }}
+        env:
+          CC_TEST_REPORTER_ID: 890ed5ee01002c7149920883256f8e4790000127faa9ddf14d86dd3ceb3b8179
+          COVERAGE: true
+        with:
+          coverageCommand: bundle exec rspec
+          coverageLocations: ${{ github.workspace }}/coverage/coverage.json:simplecov

data/.gitignore

@@ -51,3 +51,6 @@ Gemfile.lock
 
 # rspec failure tracking
 .rspec_status
+
+# byebug history
+**/.byebug_history

data/.rspec

@@ -1,3 +1 @@
---format documentation
---color
 --require spec_helper

data/.rubocop.yml

@@ -0,0 +1,15 @@
+AllCops:
+  TargetRubyVersion: 2.6
+  NewCops: enable
+Metrics/LineLength:
+  Max: 120
+Layout/DotPosition:
+  EnforcedStyle: trailing
+Style/TrailingCommaInArguments:
+  EnforcedStyleForMultiline: consistent_comma
+Metrics/BlockLength:
+  Exclude:
+    - spec/**/*_spec.rb
+# TODO: re-enable
+Style/Documentation:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [2.0.0] - 2021-11-19
+
+### Added
+
+- `exec` command to run `latexmk` directly.
+- `clobber` command to delete both unessential files and artifacts.
+
+### Changed
+
+- `go` command renamed to `build`.
+- `clean` command simply deletes unessential files (instead of everything).
+- Configuration must be named `.mnogootexrc` (instead of `.mnogootex.yml`).
+
+### Removed
+
+- `mnogoo` shell integration no longer exists.
+- `dir` and `pdf` commands no longer exist.
+
+### Fixed
+
+- Avoid deleting files before buils so viewers can reload.
+- Caught nasty IO timing bug when polling `latexmk -pv` for logs.
+
+## [1.1.0] - 2021-11-06
+
+### Added
+
+- New option `work_path` in configuration file to simplify access to build folders.
+
+## [1.0.1] - 2018-09-03
+
+### Fixed
+
+- `mnogootex mnogoo` now produces correct path.
+
+## [1.0.0] - 2018-04-24
+
+### Added
+
+- First public release.
+
+[unreleased]: https://github.com/paolobrasolin/mnogootex/compare/v2.0.0...HEAD
+[2.0.0]: https://github.com/paolobrasolin/mnogootex/compare/v1.1.0...v2.0.0
+[1.1.0]: https://github.com/paolobrasolin/mnogootex/compare/v1.0.1...v1.1.0
+[1.0.1]: https://github.com/paolobrasolin/mnogootex/compare/v1.0.0...v1.0.1
+[1.0.0]: https://github.com/paolobrasolin/mnogootex/releases/tag/v1.0.0

data/CODE_OF_CONDUCT.md

@@ -55,7 +55,7 @@ further defined and clarified by project maintainers.
 ## Enforcement
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported by contacting the project team at TODO: Write your email address. All
+reported by contacting the project team at <paolo.brasolin@gmail.com>. All
 complaints will be reviewed and investigated and will result in a response that
 is deemed necessary and appropriate to the circumstances. The project team is
 obligated to maintain confidentiality with regard to the reporter of an incident.

data/Gemfile

@@ -1,6 +1,7 @@
-source "https://rubygems.org"
+# frozen_string_literal: true
 
-git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+source 'https://rubygems.org'
+
+git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
 
-# Specify your gem's dependencies in mnogootex.gemspec
 gemspec

data/Guardfile

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+guard :rspec, cmd: 'bundle exec rspec' do
+  require 'guard/rspec/dsl'
+  dsl = Guard::RSpec::Dsl.new(self)
+
+  # RSpec files
+  watch(dsl.rspec.spec_helper) { dsl.rspec.spec_dir }
+  watch(dsl.rspec.spec_files)
+
+  # Ruby files
+  dsl.watch_spec_files_for(dsl.ruby.lib_files)
+end
+
+# # TODO: refactor the following into a new version of guard-mutant
+
+# require 'mutant'
+# require 'dry/inflector'
+# require 'guard/compat/plugin'
+
+# # NOTE: :: is mandatory for inline guards
+# module ::Guard
+#   class Mutant < Plugin
+#     def initialize(options = {})
+#       opts = options.dup
+#       # @my_option = opts.delete(:my_special_option)
+#       super(opts) # important to call + avoid passing options Guard doesn't understand
+#     end
+
+#     # TODO: how would this make sense?
+#     # def run_all; end
+
+#     def run_on_modifications(paths)
+#       inflector = Dry::Inflector.new
+#       subjects = paths.map do |path|
+#         match = path.match(%r{(?:spec|lib)\/(.*?)(?:_spec)?.rb}).captures.first
+#         inflector.camelize match
+#       end
+#       succesful = ::Mutant::CLI.run(%w[--use rspec --fail-fast] + subjects)
+#       throw :task_has_failed unless succesful
+#       self
+#     end
+#   end
+# end
+
+# guard :mutant do
+#   require 'guard/rspec/dsl'
+#   dsl = Guard::RSpec::Dsl.new(self)
+
+#   # RSpec files
+#   # watch(dsl.rspec.spec_helper) { dsl.rspec.spec_dir }
+#   watch(dsl.rspec.spec_files)
+
+#   # Ruby files
+#   dsl.watch_spec_files_for(dsl.ruby.lib_files)
+# end

data/README.md

@@ -1,43 +1,283 @@
 # Многоꙮтех
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/mnogootex`. To experiment with that code, run `bin/console` for an interactive prompt.
+[![CI tests status badge][build-shield]][build-url]
+[![Latest release badge][rubygems-shield]][rubygems-url]
+[![License badge][license-shield]][license-url]
+[![Maintainability badge][cc-maintainability-shield]][cc-maintainability-url]
+[![Test coverage badge][cc-coverage-shield]][cc-coverage-url]
 
-TODO: Delete this and the text above, and describe your gem
+[build-shield]: https://img.shields.io/github/workflow/status/paolobrasolin/mnogootex/CI/main?label=tests&logo=github
+[build-url]: https://github.com/paolobrasolin/mnogootex/actions/workflows/main.yml "CI tests status"
+[rubygems-shield]: https://img.shields.io/gem/v/mnogootex?logo=ruby
+[rubygems-url]: https://rubygems.org/gems/mnogootex "Latest release"
+[license-shield]: https://img.shields.io/github/license/paolobrasolin/mnogootex
+[license-url]: https://github.com/paolobrasolin/mnogootex/blob/main/LICENSE "License"
+[cc-maintainability-shield]: https://img.shields.io/codeclimate/maintainability/paolobrasolin/mnogootex?logo=codeclimate
+[cc-maintainability-url]: https://codeclimate.com/github/paolobrasolin/mnogootex "Maintainability"
+[cc-coverage-shield]: https://img.shields.io/codeclimate/coverage/paolobrasolin/mnogootex?logo=codeclimate&label=test%20coverage
+[cc-coverage-url]: https://codeclimate.com/github/paolobrasolin/mnogootex/coverage "Test coverage"
 
-## Installation
+Многоꙮтех (mnogootex) is a utility that parallelizes compilation
+of a LaTeX document using different classes and offers a
+meaningfully filtered output.
 
-Add this line to your application's Gemfile:
+The motivating use case is maintaining a single preamble while
+submitting a paper to many journals using their outdated or crummy
+document classes.
 
-```ruby
-gem 'mnogootex'
+## Getting started
+
+### Prerequisites
+
+Многоꙮтех is written in [**Ruby**](https://www.ruby-lang.org) and requires version `>=2.5` (earlier ones are untested).
+You can check whether it's installed by running `ruby --version`.
+For installation instructions you can refer to the [official documentation](https://www.ruby-lang.org/en/documentation/installation/).
+
+
+Многоꙮтех heavily relies on [**`latexmk`**](https://ctan.org/pkg/latexmk).
+You can check whether it's installed by running `latexmk --version`.
+If you are missing it, follow the documentation of your specific LaTeX distribution and install the `latexmk` package.
+
+### Installation
+
+To install многоꙮтех execute
+
+```bash
+gem install mnogootex
 ```
 
-And then execute:
+If you're upgrading from a previous version, execute
+
+```bash
+gem update mnogootex
+```
 
-    $ bundle
+and remove any mention of `mnogootex` from your shell profile (it's not needed anymore).
 
-Or install it yourself as:
+### Quick start
 
-    $ gem install mnogootex
+First you write a LaTeX document:
+
+```latex
+% ~/demo/main.tex
+\documentclass{scrarticle}
+\begin{document}
+  \abstract{Simply put, my article is awesome.}
+  Let's port my \KOMAScript\ article to other classes!
+\end{document}
+```
+
+Then you list the desided classes in a Многоꙮтех configuration file:
+
+```yaml
+# ~/demo/.mnogootexrc
+jobs:
+  - scrartcl
+  - article
+  - book
+```
+
+Finally you run `mnogootex build` and enjoy the technicolor:
+
+![A user types `mnogootex build main.tex` in the console. Some spinners indicating progress appear. Then the outcome for each class is presented. Failing ones include abridged and color coded logs, to pinpoint the errors.](demo/demo.gif?raw=true "TTY demo GIF")
 
 ## Usage
 
-TODO: Write usage instructions here
+A Многоꙮтех run does the following:
+1. copy the _source_ folder of a project to many _target_ folders, one for each _job_;
+2. replace the document class in the source of each _target_ folder with the name of the relative _job_;
+3. call `latexmk` in parallel on each _target_ folder to compile the documents (or do other tasks);
+4. wait for the outcomes and print the logs, filtered and colour-coded in a meaningful way.
+
+Its convenience lies in the fact that it
+* automates the setup process,
+* parallelizes compilation,
+* improves the readability of the infamous waterfall logs.
+
+Многоꙮтех can be invoked from CLI using `mnogootex`.
+It accepts various [commands](#mnogootex-commands) detailed below.
+
+To leverage the full power of this tool you will need to learn writing [`mnogootex` configurations](#mnogootex-configuration) and ['latexmk' configurations](#latexmk-configuration).
+It might sound daunting but they're really just a few lines.
+
+### `mnogootex` commands
+
+> **Notation:** `[FOO]` means that _`FOO` is optional_ while `FOO ...` means _one or more `FOO`s_.
+
+All commands except `help` accept the same parameters, so let's examine them in advance to avoid repeating ourselves later.
+Here is their syntax:
+
+```bash
+mnogootex COMMAND [JOB ...] [FLAG ...] ROOT
+```
+
+`JOB`s are the names of the document classes to compile your document with.
+Zero or more can be provided, and when none is given the job list is loaded from the [configuration](#jobs).
+
+`FLAG`s are `latexmk` options.
+Zero or more can be provided to override the behaviour of the `latexmk` call underlying the `mnogootex` command.
+You can obtain a list of available options with the inline help `latexmk --help`, and the full documentation with `man latexmk`.
+Generally speaking, if you find yourself always using a `FLAG` you should properly [configure `latexmk`](#latexmk-configuration) instead.
+
+The last mandatory parameter is the `ROOT` file for compiling of your document.
+
+Let's examine the details of each command now.
+
+#### `help [COMMAND]`
+
+This command prints the help for `COMMAND` (or all commands if none is given).
+
+#### `exec [JOB ...] [FLAG ...] ROOT`
+
+This command simply runs `latexmk` on the `ROOT` document for each of your `JOB`s passing the given `FLAG`s.
+
+All other commands below are specializations of this one.
+However you'll seldom use it unless you're debugging.
+
+#### `build [JOB ...] [FLAG ...] ROOT`
+
+This command builds your document.
+
+It is equivalent to `exec [JOB ...] -interaction=nonstopmode ROOT`.
+
+You will probably need to pass some `FLAG`s (e.g. to use the correct engine) but it is not recommended: [configure `latexmk`](#latexmk-configuration) instead.
+
+#### `open [JOB ...] [FLAG ...] ROOT`
+
+This command opens the final compilation artifact (after running the build if necessary).
+
+It is equivalent to `exec [JOB ...] -pv -interaction=nonstopmode ROOT`.
+
+You might need to pass some `FLAG`s (e.g. to use the correct viewer) but it is not recommended: [configure `latexmk`](#latexmk-configuration) instead.
+
+#### `clean [JOB ...] [FLAG ...] ROOT`
 
-## Development
+This command deletes all nonessential build files while keeping the compiled artifacts.
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+It is equivalent to `exec [JOB ...] -c ROOT`.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+#### `clobber [JOB ...] [FLAG ...] ROOT`
 
-## Contributing
+This command deletes all nonessential build files including the compiled artifacts.
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/mnogootex. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+It is equivalent to `exec [JOB ...] -C ROOT`.
 
-## License
+### `mnogootex` configuration
+
+`mnogootex` is configured through [`YAML`](https://learnxinyminutes.com/docs/yaml/)
+files named `.mnogootexrc` put into your projects' root directory.
+
+When `mnogootex` loads a configuration it also looks up for `.mnogootexrc`
+files in all parent directories to merge then together (from the
+shallowest to the deepest path).  This means that e.g. you can keep
+a configuration file in your home folder and use it as a global
+configuration for all you projects, while overwriting only specific
+options in the configuration files of each one.
+
+`mnogootex` currently accepts three options.
+
+#### `jobs`
+
+This option represents the `JOB`s to build your document (when none are given via CLI).
+
+It must contain valid document class names, given as a list of strings.
+
+By default there are no `JOB`s:
+
+```yaml
+# Default value:
+jobs: []
+```
+
+Here is a slightly more interesting example:
+
+```yaml
+jobs:
+  - scrartcl
+  - article
+  - book
+```
+
+#### `work_path`
+
+This option is the folder where all elaboration happens.
+
+It must be a well formed path, given as a string.
+
+By default none is given, meaning that each run of any given job happens in a dedicated temporary folder:
+
+```yaml
+# Default value:
+work_path: null
+```
+
+Overriding this allows you to have easier access to the compilation artifacts.
+A good choice is setting it to `./build` and keep everything below your source folder:
+
+```yaml
+work_path: ./build
+```
+
+#### `spinner`
+
+This option is the spinner animation shown by the CLI.
+
+It is a series of frames given as characters of a string.
+
+By default it's a hole looping around in a blister:
+
+```yaml
+# Default value:
+spinner: ⣾⣽⣻⢿⡿⣟⣯⣷
+```
+
+Here is a couple more in case your terminal doesn't like Unicode:
+
+```yaml
+# A wriggly ASCII worm:
+spinner: )}]|[{({[|]}
+# An extended ASCII boomerang:
+spinner: ╒┍┌┎╓╖┒┐┑╕╛┙┘┚╜╙┖└┕╘
+```
+
+Feel free to get creative!
+
+### `latexmk` configuration
+
+`latexmk` is configured through [`Perl`](https://www.perl.org/)
+files named `.latexmkrc` put into your projects' root directory.
+
+When `latexmk` loads a configuration it also looks up for `.latexmkrc`
+files in all parent directories to merge then together (from the
+shallowest to the deepest path).  This means that e.g. you can keep
+a configuration file in your home folder and use it as a global
+configuration for all you projects, while overwriting only specific
+options in the configuration files of each one.
+
+`latexmk` has a gazillion of options.
+We'll just skim over the most common ones here.
+
+First of all, one must pick the correct engine.
+Assuming you want to produce a PDF artifact, you have a few choices:
+
+```perl
+$pdf_mode = 1; # create PDF with pdflatex
+# $pdf_mode = 2; # create PDF with ps2pdf (via PS)
+# $pdf_mode = 3; # create PDF with dvipdf (via DVI)
+# $pdf_mode = 4; # create PDF with lualatex
+# $pdf_mode = 5; # create PDF with xelatex
+```
+
+Then, if your PDF previewer is not being detected, you might need to configure it.
+Assuming you want to use evince:
+
+```perl
+$pdf_previewer = 'start evince';
+```
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+Most people won't probably need anything more than that.
+However, for further details read the documentation in the commandline with `man latexmk` or on [CTAN](https://ctan.mirror.garr.it/mirrors/ctan/support/latexmk/latexmk.txt)
 
-## Code of Conduct
+## Acknowledgements
 
-Everyone interacting in the Mnogootex project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/mnogootex/blob/master/CODE_OF_CONDUCT.md).
+* Thanks to [@tetrapharmakon](https://github.com/tetrapharmakon) for being the first tester and user.

data/Rakefile

@@ -1,6 +1,27 @@
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+# frozen_string_literal: true
 
-RSpec::Core::RakeTask.new(:spec)
+# require 'mutant'
+# require 'dry/inflector'
 
-task :default => :spec
+require 'rspec/core/rake_task'
+
+namespace :spec do
+  desc 'run RSpec'
+  RSpec::Core::RakeTask.new(:rspec) do |task|
+    task.rspec_opts = '--format documentation'
+  end
+
+  desc 'run SimpleCov'
+  task :simplecov do
+    ENV['COVERAGE'] = 'true'
+    Rake::Task['spec:rspec'].invoke
+  end
+
+  # desc 'run Mutant'
+  # task :mutant, [:subject] do |_, args|
+  #   subjects = [args[:subject]].compact
+  #   subjects << 'Mnogootex*' if subjects.empty?
+  #   successful = ::Mutant::CLI.run(%w[--use rspec --fail-fast] + subjects)
+  #   raise('Mutant task is not successful') unless successful
+  # end
+end

data/demo/.mnogootexrc

@@ -0,0 +1,4 @@
+jobs:
+  - scrarticle
+  - article
+  - book