Usage

(TODO)

Contributing

For regular development, you need to have Node.js >=0.10 installed on your system, then:

Clone the repository

git clone [email protected]:roperzh/jroff_final.git
cd jroff_final

Install the required dependencies

npm install

Build your local copy and run the tests:

make all

Brief explanation of the code organization

dist: This folder stores the bundled versions of the code.

src/core: As the folder name says, this is the core of the library. There is no HTML-related code here, only code to parse and build the AST.

src/generators: Generators are entities capables of consume the AST generated by the parser and produce an output. For the moment only an HTML generator is implemented.

src/macros: Implementations of macro commands divided in macro packages. For the moment only an and doc packages are supported. Macros supported by groff are stored in default.js.

src/utils: Utility functions and stuff.

Brief explanation of useful make commands

make dist: beautify and build both minified and concatenated versions of the code.

make hint: run js-hint over the test files and the concatenated non-minified version of the code.

make beautify: run js-beautify over all the JavaScript files.

make doc: build a local documentation based on the current version of the code, useful to preview the documentation before pushing. Check the next section for more details.

Documenting new code

This library uses jsdoc3 to generate the documentation, so all the new code must be documented using jsdoc tags. An useful reference can be found here.

Also, due to limitations with jsdoc and UMD it is required to add the @alias tag to all functions, constructors and namespaces.

Generating the documentation

The Makefile includes an useful command to generate and push the documentation to GitHub and GitHub pages, you can simply run:

make doc-build

Note: please make sure to stash or commit all your changes before building the documentation.

If you want to preview the changes before pushing, you can generate the documentation with the doc task and then and open docs/index.html in your browser.

This is an example using OS X:

make doc
open docs/index.html

TODOs

• Performance measures ( https://github.com/bestiejs/benchmark.js )
• Finish the contributing section
• Add instructions to define new macros
• Create a logo (?
• Clean up the code
• Add black box tests
• Finish unit tests
• Fix issues with the parser
• Add missing macros
• Clarify that we do not intend to copy the behavior of groff_html
• Documentation
  • Implement a build system to document pages
  • Add documentation to all the code
  • Add instructions in the readme to build the documentation
• Look for more semantic markup
• Review the README
• Better way to send arguments to macro calls
• Add CI integration
• Automatic detection of macros
• Handle scape characters
• Add support for nested numeric lists
• Add support for -compact and -width arguments in lists

Links

• About macros
• About the an macro
• About the doc macro
• Troff spec

License

All the code contained in this repository, unless explicitly stated, is licensed under MIT license.

A copy of the license can be found inside the LICENSE file.