Final format output for download

[JohnRDOrazio]

Seeing @mkasberg raised the question on the Slack channel, we can discuss here how to go about producing the final format that the end user can download / print / have printed.

My vision is to be as flexible as possible, and offer as many options as possible. A first choice would be PDF, but I would leave the option (if technically feasible) for DOCX, or even InDesign / Latex.

Useful GEMS to go about doing this:

• For InDesign and LaTeX: https://www.ruby-toolbox.com/projects/review - Re:VIEW is a digital publishing system for books and ebooks. It supports InDesign, EPUB and LaTeX
• For PDF: Prawn and CombinePDF
  • https://www.ruby-toolbox.com/projects/prawn - Prawn is a fast, tiny, and nimble PDF generator for Ruby
  • https://www.ruby-toolbox.com/projects/combine_pdf - parse PDF files and combine (merge) them with other PDF files, number the pages, watermark them or stamp them, create tables, add basic text objects etc` (all using the PDF file format)
  • https://www.ruby-toolbox.com/projects/prawn-svg - render SVG directly into a PDF using the 'prawn' gem. Since PDF is vector-based, you'll get nice scaled graphics if you use SVG instead of an image
• For DOCX: looks like it's not very well supported in Ruby, best I could find is https://www.ruby-toolbox.com/projects/docxgen which simply works on DOCX templates by replacing variables. That would be fine if we only had to replace the names of the spouses and stuff like that, but we're wanting to generate a DOCX from scratch basically. Looks like this is better supported in PHP, perhaps for anyone wanted to download a DOCX we could have a PHP script to help with this:
  • https://github.com/PHPOffice/PHPWord - provides a set of classes to write to and read from different document file formats. The current version of PHPWord supports Microsoft Office Open XML (OOXML or OpenXML), OASIS Open Document Format for Office Applications (OpenDocument or ODF), Rich Text Format (RTF), HTML, and PDF

[JohnRDOrazio]

DOCX can also be achieved with NodeJS: https://www.npmjs.com/package/docx .
So I suppose we could choose between PHP or NodeJS as a helper for DOCX generation. My preference is PHP because seems to me to be a little more stable and easier to maintain...

[kas-catholic]

I think the two most appealing formats to me are .docx (Word) and LaTeX. Docx is appealing because users can edit the file when they're done, and LaTeX is appealing because it's good at generating nicely formatted PDFs that would be ready to print.

Although .docx doesn't have a ton of Ruby support, my understanding of the format is that it is zipped XML. We could create the documents in Word once, save the .docx file as we want it to look, and use string replacement on the XML files from Ruby. This is probably the best approach for formatted output anyway -- I think it would be incredibly hard to get a good-looking document with lots of formatting using only something like PHPWord. Although it might still be nice to interact with the document through an interface like that... calling a PHP script isn't a bad idea to consider.

I think the approach with LaTeX would actually be quite similar. We'd probably want to write the LaTeX source file manually, and then do some kind of string replacement before rendering to PDF.

There are a lot of ways to do the string replacement... Interacting with the XML using an XML library might be an option for the Word doc. An alternative that we might consider is using erb with a template like .tex.erb. We might even be able to use erbs on the internal docx xml files if we wanted to.