{"id":13525134,"url":"https://github.com/roperzh/jroff","last_synced_at":"2025-04-13T02:32:14.585Z","repository":{"id":56013006,"uuid":"47151451","full_name":"roperzh/jroff","owner":"roperzh","description":"Man pages parser written in JavaScript, supports `an` and `doc` macros - WIP","archived":false,"fork":false,"pushed_at":"2019-11-11T06:00:34.000Z","size":795,"stargazers_count":77,"open_issues_count":12,"forks_count":15,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-21T03:35:08.679Z","etag":null,"topics":["ast","groff","javascript","man-page","man-pages-parser"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","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/roperzh.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG","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":"2015-11-30T23:03:17.000Z","updated_at":"2025-01-11T09:29:52.000Z","dependencies_parsed_at":"2022-08-15T11:20:53.081Z","dependency_job_id":null,"html_url":"https://github.com/roperzh/jroff","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roperzh%2Fjroff","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roperzh%2Fjroff/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roperzh%2Fjroff/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roperzh%2Fjroff/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/roperzh","download_url":"https://codeload.github.com/roperzh/jroff/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248657793,"owners_count":21140842,"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":["ast","groff","javascript","man-page","man-pages-parser"],"created_at":"2024-08-01T06:01:16.250Z","updated_at":"2025-04-13T02:32:14.220Z","avatar_url":"https://github.com/roperzh.png","language":"JavaScript","funding_links":[],"categories":["Uncategorized"],"sub_categories":["Uncategorized"],"readme":"![jroff](https://cloud.githubusercontent.com/assets/4419992/11488319/61d7086e-97a4-11e5-9ea7-2276c409c208.png)\n\n![travis](https://travis-ci.org/roperzh/jroff.svg?branch=master)\n[![Code Climate](https://codeclimate.com/github/roperzh/jroff/badges/gpa.svg)](https://codeclimate.com/github/roperzh/jroff)\n[![Test Coverage](https://codeclimate.com/github/roperzh/jroff/badges/coverage.svg)](https://codeclimate.com/github/roperzh/jroff/coverage)\n\n## About\n\n*For a real-life example of Jroff in action, check out [grapse](http://www.roperzh.com/grapse).*\n\nJroff is a man page parser written in JavaScript, featuring:\n\n- Partial support for groff-native commands\n- Full support for `an` macros\n- Full support for `doc` macros\n\nThe main functionality of the library is to produce an [AST](https://en.wikipedia.org/wiki/Abstract_syntax_tree) ready to\nbe consumed by a generator.\n\nAt the moment, only a single HTML generator has been implemented, but the plan is\nto implement several more in the near future.\n\n## Usage\n*An annotated version of the code can be found [here](http://www.roperzh.com/jroff/)*\n\n### HTML Generator\nUsing the generator is fairly simple. You only have to create\na new instance and call the `generate` method every\ntime you want to parse a string containing groff text.\n\nThe `generate` function takes two arguments: the source string and an\noptional name from the macro library that will be used to parse the result:\n\n```javascript\n// Instantiate a new generator\nvar generator = new Jroff.HTMLGenerator();\n// Generate the HTML output\nvar result = generator.generate('.Op Fl 0 Ns Op Ar octal', 'doc');\n```\nThis is what we see when we print the result variable:\n\n```html\n\u003cspan\u003e[\u003cstrong\u003e-0 \u003cspan\u003e[\u003ci\u003eoctal\u003c/i\u003e]\u003c/span\u003e\u003c/strong\u003e]\u003c/span\u003e\n```\n\n### Parser\n\nThe parser takes a string as a source, being capable of building an AST\nfrom it. Using the parser is very straightforward, but it is nearly\nuseless without a generator:\n\n```javascript\n// Instantiate a new parser class\nvar parser = new Jroff.Parser('.Op Fl lorem ipsum');\n// Build the AST\nvar ast = parser.buildAST();\n```\nThis is what we see when we inspect the `ast` variable:\n\n```json\n[{\n  \"value\": \"Op\",\n  \"kind\": 2,\n  \"nodes\": [{\n    \"value\": \" \",\n    \"kind\": 5,\n    \"nodes\": []\n  }, {\n    \"value\": \"Fl\",\n    \"kind\": 3,\n    \"nodes\": [{\n      \"value\": \" lorem ipsum\",\n      \"kind\": 5,\n      \"nodes\": []\n    }]\n  }]\n}]\n```\n\n### Defining New Macros\n\nYou can define a specific macro for your project by\nadding a new item in the `Jroff.macros.defaults` object, using\nthe macro name as a key and the function with a specific macro\nfunctionality as the value:\n\n```javascript\nJroff.macros.defaults.sp = function (spacing) {\n    spacing = spacing || '2';\n    return '\u003chr style=\"margin-top:' + spacing + 'em;visibility:hidden;\"\u003e';\n};\n```\nInternally, all macros are defined like this. You can check out `src/macros/defaults.js` for more examples.\n\n## Contributing\n\nFor regular development, you need to have `Node.js \u003e=0.10` installed in\nyour system. Then,\n\nClone the repository.\n\n```console\ngit clone git@bitbucket.org:roperzh/jroff_final.git\ncd jroff_final\n```\n\nInstall the required dependencies.\n\n```console\nnpm install\n```\n\nFinally, build your local copy and run the tests.\n\n```console\nmake all\n```\n\n### Brief Description of the Organization of the Code\n\n`dist`: This folder stores the bundled versions of the code.\n\n`src/core`: As the name of the folder suggests, this is the core of the library.\nThere is no HTML-related code here, only code to parse and build the AST.\n\n`src/generators`: Generators are entities that can consume the AST\ngenerated by the parser and produce an output. At the moment, only one HTML\ngenerator has been implemented.\n\n`src/macros`: Stores macro commands and macro packages.\nAt the moment, it only supports `an` and `doc` packages.\nMacros supported by groff are stored in `default.js`\n\n`src/utils`: Utility functions and miscellany.\n\n### Brief Description of Make Commands\n\n***make dist:*** beautifies and builds minified and concatenated versions\nof the code.\n\n***make hint:*** runs [eslint](http://eslint.org/) over the test files\nand the concatenated, non-minified version of the code.\n\n***make beautify:*** runs [js-beautify](https://github.com/beautify-web/js-beautify)\nover all JavaScript files.\n\n***make doc:*** generates local documentation based on the current version\nof the code. This is useful for previewing documentation before publishing it.\nSee the next section for more details.\n\n### Documenting New Code\n\nThis library uses [jsdoc3](https://github.com/jsdoc3/jsdoc) to generate documentation, so all new code must be documented using jsdoc\ntags. A useful reference can be found [here](http://usejsdoc.org/index.html).\n\nAlso, due to [some limitations](https://github.com/jsdoc3/jsdoc/issues/930) with\njsdoc and [UMD](https://github.com/umdjs/umd), the `@alias` tag must be added to all functions,\nconstructors, and namespaces manually.\n\n### Generating Documentation\n\nThe Makefile includes a useful command that generates and pushes the\ndocumentation onto GitHub and GitHub pages. You can simply run:\n\n```console\nmake doc-build\n```\n\n**Note:** Please make sure to stash or commit all your changes\nbefore generating the documentation.\n\nIf you want to preview the changes before pushing the documentation, you can generate\nit with the `doc` task and then open `docs/index.html`\non your browser.\n\nAn example of this using OS X:\n\n```console\nmake doc\nopen docs/index.html\n```\n\n### Benchmarks\n\nRunning benchmarks is a complicated task, even more so in this case\nsince there aren't other libraries to use as a reference and compare\nthe results with.\n\nTherefore, what these benchmarks are for is to compare different versions\nof the library with three arbitrary man pages: `Git`, `Node.js`,\nand `Ruby`\n\nThis benchmark should be used only for drawing estimative comparisons between\nversions or complex features.\n\nIf you want to run the benchmarks and compare the new data with the latest stored results:\n\n```console\nmake bench\n```\n\nAlternatively, you can store the results of the benchmark in the\ncache file (`benchmarks/benchmarks.json`) with an `-s` flag:\n\n```console\nmake bench flags='-s'\n```\n### To-Dos\n\n- [ ] Add support for nested numeric lists\n- [ ] Add support for `-width` arguments in lists\n- [ ] Add missing macros\n\n### Links\n\n- [Macros](http://www.schweikhardt.net/man_page_howto.html#q5)\n- [`an` macros](http://linux.die.net/man/7/man)\n- [`doc` macros](https://www.dragonflybsd.org/cgi/web-man?command=mdoc\u0026section=7)\n- [Troff specs](http://cm.bell-labs.com/sys/doc/troff.pdf)\n\n## License\n\nAll the code contained in this repository, unless explicitly stated, is\nlicensed under an MIT license.\n\nA copy of the license can be found in the [LICENSE](LICENSE) file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froperzh%2Fjroff","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Froperzh%2Fjroff","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froperzh%2Fjroff/lists"}