{"id":19630995,"url":"https://github.com/reitzig/texlogparser","last_synced_at":"2025-09-18T13:44:40.199Z","repository":{"id":59157711,"uuid":"127746441","full_name":"reitzig/texlogparser","owner":"reitzig","description":"Eases the many pains around digesting logs from (La)TeX engines.","archived":false,"fork":false,"pushed_at":"2018-09-15T22:14:20.000Z","size":110,"stargazers_count":2,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-24T06:52:26.131Z","etag":null,"topics":["latex","log-files","logs","parser","tex"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/reitzig.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-04-02T11:20:00.000Z","updated_at":"2024-12-01T21:47:11.000Z","dependencies_parsed_at":"2022-09-13T18:13:25.611Z","dependency_job_id":null,"html_url":"https://github.com/reitzig/texlogparser","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reitzig%2Ftexlogparser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reitzig%2Ftexlogparser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reitzig%2Ftexlogparser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reitzig%2Ftexlogparser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/reitzig","download_url":"https://codeload.github.com/reitzig/texlogparser/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250580713,"owners_count":21453531,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["latex","log-files","logs","parser","tex"],"created_at":"2024-11-11T12:07:22.751Z","updated_at":"2025-09-18T13:44:35.158Z","avatar_url":"https://github.com/reitzig.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TeXLogParser\n\n[![Gem Version](https://badge.fury.io/rb/tex_log_parser.svg)](https://badge.fury.io/rb/tex_log_parser)\n[![Yard docs](http://img.shields.io/badge/yard-docs-green.svg)](http://www.rubydoc.info/gems/tex_log_parser/) **˙**\n[![Maintainability](https://api.codeclimate.com/v1/badges/748992a2c5f6570797d4/maintainability)](https://codeclimate.com/github/reitzig/texlogparser/maintainability) \n[![Test Coverage](https://api.codeclimate.com/v1/badges/748992a2c5f6570797d4/test_coverage)](https://codeclimate.com/github/reitzig/texlogparser/test_coverage) **˙**\n[![Circle CI](https://circleci.com/gh/reitzig/texlogparser.svg?style=svg)](https://circleci.com/gh/reitzig/workflows/texlogparser/tree/master)\n[![Inline docs](http://inch-ci.org/github/reitzig/texlogparser.svg?branch=master)](http://inch-ci.org/github/reitzig/texlogparser)\n\nThis small Ruby gem eases many pains around digesting logs from (La)TeX engines.\nUsed as a command-line program or library, it converts (La)TeX logs into human-\nor machine-readable forms.\n\n_Disclaimer:_ Due to the nature of (La)TeX logs, parsing is inherently heuristic.\n\n## Installation\n\nOn any system with working Ruby (≥ 2.3), installation is as simple as this:\n\n```bash\n[sudo] gem install tex_log_parser\n```\n\nThe usual options and, later, update mechanisms of Rubygems apply; \nplease refer to their documentation for details.\n\n## Usage\n\nThere are two ways to parse logs: with the command-line program and via the underlying Ruby API.\n\n### Command-line Interface\n\nBy default, `texlogparser` reads from stdin and writes to stdout. That is, you can use it like so:\n\n```bash\npdflatex -interaction=nonstopmode example.tex | texlogparser\n```\n    \nThis adds so little runtime overhead that there are few reasons _not_ to use it. \nNote that the original log file will still be written to `example.log`, \nso no information is lost.\n\n**Important:** Without `nonstopmode`, `pdflatex` et al. stop on errors to interact\nwith the user; `texlogparser` is not prepared to play the middle man for that and\nwill block.\n\nYou can also read from and/or write to files:\n\n```bash\ntexlogparser -i example.log                          # From file, to stdout\ntexlogparser -i example.log -o example.simple.log    # From and to file\ncat example.log | texlogparser -o example.simple.log # From stdin, to file\n```\n\nIf you want to use the output programmatically, you may want to add option `-f json`.\nIt does just what it sounds like.\n\n### Ruby API\n\nThe interface is rather narrow; your main entry point is class \n    [TexLogParser](http://www.rubydoc.info/gems/tex_log_parser/TexLogParser).\nCalling `parse` on it will yield a list of \n    [Message](http://www.rubydoc.info/gems/tex_log_parser/LogParser/Message) \nobjects.\n\nHere is a minimal yet complete example:\n\n```ruby\nrequire 'tex_log_parser'\n\nlog = File.readlines('example.log')\nparser = TexLogParser.new(log)\nputs parser.parse[0]\n```\n\n### Recommendations\n\nHere are some tips on how to generate logs that do not trip up parsing unnecessarily:\n\n * Use `_latex` option `-file-line-error` to get higher accuracy regarding source files and lines.\n * [Increase the maximum line length](https://tex.stackexchange.com/a/52994/3213) as much as possible\n    to improve overall efficacy. Bad linebreaks are \n        [bad](https://github.com/reitzig/texlogparser/search?utf8=%E2%9C%93\u0026q=BROKEN_BY_LINEBREAKS\u0026type=).\n * Avoid parentheses and whitespace in file paths.\n * The shell output of the initial run of `pdflatex` et al. on a new file can \n    contain output of subprograms, and be complicated in other ways as well. \n    It is therefore more robust to use the log file as written to disk, and/or \n    the output resp. log file produced by a subsequent run. \n    (Don't worry, real errors will stick around!) \n\n## Contributing\n\nFor bug reports and feature requests, the usual rules apply: search for \n    [existing issues](https://github.com/reitzig/texlogparser/issues);\njoin the discussion or\n    [create a new one](https://github.com/reitzig/texlogparser/issues/new);\nbe specific and nice; expect nothing.\n    \nThat aside, there are two groups of experts whose help would be much appreciated:\n(La)TeX gourmets and Ruby developers. \n\n### TeXians\n\nPlease report any logs that get parsed wrong, be it because whole messages are not found,\nor because not all details are correctly extracted.\n\nReports that provide the following information will be the most useful:\n\n 1. Full failing log of a minimal example (ideally with source document).\n 2. The engine(s) you use, e.g. `pdflatex`, `xelatex`, or `lualatex`.\n 3. Expected number of error, warning, and info messages (the latter optional).\n 4. Expected message with\n    * log line numbers (where the message starts and ends),\n    * level of the message (error, warning, or info), and\n    * which source file (and lines) it references.\n 5. _Advanced_: In case of wrong source files, run `texlogparser -d` on the log\n    and note on which lines it changes file scopes in wrong ways.   \n\nIf you _also_ know a little Ruby, please consider translating those data into \n    [a (failing) test](https://github.com/reitzig/texlogparser/blob/master/test/test_texlogparser.rb)\nand open a pull request.\n\nSome preemptive notes:\n * Issues around messages below warning level have low priority.\n * Problems caused by inopportune linebreaks are _probably_ out of scope.\n \n**Bonus:** Convince as many package maintainers to use the same standardized, robust way of writing to the log.\n \n### Rubyists\n\nAny feedback about the code quality and usefulness of the documentation would be \nvery appreciated. Particular areas of interest include:\n\n * Is the API designed in useful ways?\n * Does the documentation cover all your questions?\n * Is the Gem structured properly?\n * What can be improved to encourage code contributions?\n * Does the CLI script have problems on any platform?\n \n### Contributors\n\n * [egreg](https://tex.stackexchange.com/users/4427/egreg) and\n   [David Carlisle](https://tex.stackexchange.com/users/1090/david-carlisle)\n   provided helpful test cases and insight in LaTeX Stack Exchange chat. ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freitzig%2Ftexlogparser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Freitzig%2Ftexlogparser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freitzig%2Ftexlogparser/lists"}