tex_log_parser 1.0.0.pre.15 → 1.0.0.pre.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 04cec17bca7fe8b297a5b35114d1334e3d5f530fba5f1e952672035c55d6627c
-  data.tar.gz: ec8e3cd45e18157f2fddb43b4c610f590792c0784bf857abd6d69b2d811e53f7
+  metadata.gz: a250fc41646ce2605eac36e8ce5ad22a1767c5de0dc824683a2a8a497d2b173c
+  data.tar.gz: d3df0c06d2280d808a9f9cb3db1eb73d673a8183bb826abe0ef1ad8df4ae0fd6
 SHA512:
-  metadata.gz: 3ce2d48f6d26848b14efecef85d48878cf93e9d5d638a77cf2c8a61af429b0a61364013dace4e5bbf532452dd9290d7dc3359d35b7c322f9bef69491bc893377
-  data.tar.gz: 9a062a9b01e3c467a64ac0166fe054f5e73174745c859d88767abd9faecaabdc8915e3ee879e72ddedf1435991992331a674b6d9392afc01150809ffdf351718
+  metadata.gz: c9b0f10261169bea1cdd0e0ada59cfb92dec26227fd1dca371d7e530f4078b9a700c3781cd038fd47f2a71a7d80c605b7ee64ba2c8cdfd12746a52f2230e5341
+  data.tar.gz: 627ea1f3f32ba584e9c314d198a73ff71c5d2575e799056e88b815e29698a1d459428f3bfd5a91635639592281227b210d934ee12a68aced29247ba1690d828d

data/README.md

@@ -4,17 +4,109 @@
 [![Yard docs](http://img.shields.io/badge/yard-docs-green.svg)](http://www.rubydoc.info/gems/tex_log_parser/1.0.0) **˙**
 [![Maintainability](https://api.codeclimate.com/v1/badges/748992a2c5f6570797d4/maintainability)](https://codeclimate.com/github/reitzig/texlogparser/maintainability) 
 [![Test Coverage](https://api.codeclimate.com/v1/badges/748992a2c5f6570797d4/test_coverage)](https://codeclimate.com/github/reitzig/texlogparser/test_coverage) **˙**
-[![Circle CI](https://circleci.com/gh/reitzig/texlogparser.svg?style=svg)](https://circleci.com/gh/reitzig/texlogparser)
+[![Circle CI](https://circleci.com/gh/reitzig/texlogparser.svg?style=svg)](https://circleci.com/gh/reitzig/workflows/texlogparser/tree/master)
 [![Inline docs](http://inch-ci.org/github/reitzig/texlogparser.svg?branch=master)](http://inch-ci.org/github/reitzig/texlogparser)
 
-Eases the many pains around logs from (La)TeX engines. 
+This small Ruby gem eases many pains around digesting logs from (La)TeX engines.
+Used as a command-line program or library, it converts (La)TeX logs into human-
+or machine-readable forms.
+
+_Disclaimer:_ Due to the nature of (La)TeX logs, parsing is inherently heuristic.
+
+## Installation
+
+On any system with working Ruby (≥ 2.3), installation is as simple as this:
+
+```bash
+[sudo] gem install tex_log_parser
+```
+
+The usual options and, later, update mechanisms of Rubygems apply; 
+please refer to their documentation for details.
 
 ## Usage
 
- * Use `texlogparser` on the CLI.
- * Use `TexLogParser` from Ruby scripts.
+There are two ways to parse logs: with the command-line program and via the underlying Ruby API.
+
+### Command-line Interface
+
+By default, `texlogparser` reads from stdin and writes to stdout. That is, you can use it like so:
+
+```bash
+pdflatex -interaction=nonstopmode example.tex | texlogparser
+```
+    
+This adds so little runtime overhead that there are few reasons _not_ to use it. 
+Note that the original log file will still be written to `example.log`, 
+so no information is lost.
+
+You can also read from and/or write to files:
+
+```bash
+texlogparser -i example.log                          # From file, to stdout
+texlogparser -i example.log -o example.simple.log    # From and to file
+cat example.log | texlogparser -o example.simple.log # From stdin, to file
+```
+
+If you want to use the output programmatically, you may want to add option `-f json`.
+It does just what it sounds like.
+
+ 
+### Ruby API
+
+### Recommendations
+
+ * Use `_latex` option `-file-line-error` to get higher accuracy regarding source files and lines.
+ * [Increase the maximum line length](https://tex.stackexchange.com/a/52994/3213) as much as possible
+    to improve overall efficacy. Bad linebreaks are 
+        [bad](https://github.com/reitzig/texlogparser/search?utf8=%E2%9C%93&q=BROKEN_BY_LINEBREAKS&type=).
+ * Avoid parentheses and whitespace in file paths.
 
 ## Contributing
 
- 1. TeXians: Report wrong parsing (w/ excerpt and full log incl expectations).
- 2. Rubyists: Review API, documentation, gem setup, etc.
+For bug reports and feature requests, the usual rules apply: search for 
+    [existing issues](https://github.com/reitzig/texlogparser/issues);
+join the discussion or
+    [create a new one](https://github.com/reitzig/texlogparser/issues/new);
+be specific and nice; expect nothing.
+    
+That aside, there are two groups of experts whose help would be much appreciated:
+(La)TeX gourmets and Ruby developers. 
+
+### TeXians
+
+Please report any logs that get parsed wrong, be it because whole messages are not found,
+or because not all details are correctly extracted.
+
+Reports that provide the following information will be the most useful:
+
+ 1. Full failing log of a minimal example (ideally with source document).
+ 2. The engine(s) you use, e.g. `pdflatex`, `xelatex`, or `lualatex`.
+ 3. Expected number of error, warning, and info messages (the latter optional).
+ 4. Expected message with
+    * log line numbers (where the message starts and ends),
+    * level of the message (error, warning, or info), and
+    * which source file (and lines) it references.
+ 5. _Advanced_: In case of wrong source files, run `texlogparser -d` on the log
+    and note on which lines it changes file scopes in wrong ways.   
+
+If you _also_ know a little Ruby, please consider translating those data into 
+    [a (failing) test](https://github.com/reitzig/texlogparser/blob/master/test/test_texlogparser.rb)
+and open a pull request.
+
+Some preemptive notes:
+ * Issues around messages below warning level have low priority.
+ * Problems caused by inopportune linebreaks are _probably_ out of scope.
+ 
+**Bonus:** Convince as many package maintainers to use the same standardized, robust way of writing to the log.
+ 
+### Rubyists
+
+Any feedback about the code quality and usefulness of the documentation would be 
+very appreciated. Particular areas of interest include:
+
+ * Is the API designed in useful ways?
+ * Does the documentation cover all your questions?
+ * Is the Gem structured properly?
+ * What can be improved to encourage code contributions?
+ * Does the CLI script have problems on any platform?

data/lib/log_parser/log_parser.rb

@@ -66,7 +66,7 @@ module LogParser
     @log_line_number = 1
     @lines = LogParser::Buffer.new(log)
 
-    Logger.debug "Parsing from '#{log}'"
+    #Logger.debug "Parsing from '#{log}'"
     @scope_changes_by_line = {} if Logger.debug?
   end
 

data/lib/log_parser/logger.rb

@@ -10,7 +10,7 @@ module LogParser
       # @param [true,false] flag
       # @return [void]
       def debug=(flag)
-        @debugging = flag
+        self.debugging = flag
       end
 
       # Indicates whether we are debugging.
@@ -18,7 +18,7 @@ module LogParser
       # @return [true,false]
       #   `true` if we are in debugging mode, `false` otherwise.
       def debug?
-        @debugging || !ENV['DEBUG'].nil?
+        debugging || !ENV['DEBUG'].nil?
       end
 
       # Logs the given message to STDOUT if `debug?` is true.
@@ -28,6 +28,10 @@ module LogParser
       def debug(message)
         puts message if debug?
       end
+
+      private
+
+      attr_accessor :debugging
     end
   end
 end

data/lib/tex_log_parser/patterns/highlighted_messages.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-  class TexLogParser
+class TexLogParser
   # Matches messages of these forms:
   #
   #     !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

data/lib/version.rb

@@ -3,5 +3,5 @@
 # @attr [String] VERSION
 #   The version of TexLogParser.
 class TexLogParser
-  VERSION = '1.0.0.pre.15'
+  VERSION = '1.0.0.pre.16'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tex_log_parser
 version: !ruby/object:Gem::Version
-  version: 1.0.0.pre.15
+  version: 1.0.0.pre.16
 platform: ruby
 authors:
 - Raphael Reitzig
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-04-08 00:00:00.000000000 Z
+date: 2018-04-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: github-markup