enghouse-documentation v0.1.4

title: 'Enghouse Documentation Builder' alter: 'The other thing.'

test: true

enghouse-documentation

Note: This is still very much a work in progress. Full functonality expected during spring 2018.

What It Is

It's a series of NodeJS modules operating in harmony to convert markdown documents into HTML and PDF files for use by people working at Enghouse Networks, allowing us a quick and easy way of managing our release process and not having to reinvent the wheel. It allows us to source-control our documentation, reference files from files and create all documentation in a unified way.

What It Is Not

It is not a tool for wide-market adoption, even though some aspects of it will likely be useful for other people down the line. As much as possible, I have tried to build external modules in situations where a feature or functionality would be useful to people outside of Enghouse Networks, so that these modules can be used independently of this software.

Modules, you say?

Yes. For example, check out remark-import for an improved version of remark-include.

Notes and Future Updates

• Keyword highlighting?
• There might not really be a need to have so many files in /src. Maybe we could throw them together a little bit and just use the promises to chain the processing instead.
• Possible bugs still exist in the way remark-import handles paths. Tests need to be done on paths on separate drives as well as in vastly different places on the disk. This is both for the imported file and for the images being displayed inside of them.
• A few plugins and modules have not been tested properly.
  • remark-plantuml
  • remark-embed-images :smile:
  • remark-slug :fa-circle:
• Some plugins and modules seem to be pulling double (triple?) duty.
  • remark-emoji vs remark-gemoji vs retext-emoji
  • typographic-apostrophes vs retext-quotes
• Is math syntax working? If not, do we care?
• Is subscript and superscript working? If not, do we care?
• Are abbreviations working? If not, do we care?
• Are footnotes working? If not, do we care?
• Lacks configurability, especially from the command line interface.
• Spaghetti code in places needs to be cleaned up. Promice chaining isn't clean, and there is no reason for the file name of the original file or the temp file to be passed around as much as they are.
• The plantuml JAR-file needs replacing, the current one is ancient.
• Templates are in big need of optimization. Blockquotes, headers and footers, cover page for .docx, etc.
• Comments in SQL code in docx are bright blue on a grey background, very difficult to read.

Thank you!

• Big thanks to Titus, AKA wooorm for all of his great work on Remark, Retext, Rehype, Unified and the rest of them. Your work is the foundation that so many of us have built our own castles upon, and that kind of thing deserves only the biggest and best of praise.
• Another big thanks to Sindre Sorhus, for all the wownderful things he's built for Node.js. His awesome-lint served as some inspiration to this tool as well.