0

Is there a git-friendly documentation solution that supports making tables where fields can contain basic equations to preform calculations based on the value of the other cells in the table?

I'm trying to decide what markup to write my project's documentation in. Our documentation will contain rich text, lots of pictures, videos, figures, mathematical formulas, spreadsheets, and charts/graphs (which could just be images rather than generated by data at compile time).

The documentation will be treated as code on github so that it can have all the usual commits/pull requests/review/continuous integration/deployment/etc. I was considering using LibreOffice fodt/fods files, but those file formats have so many extraneous metadata fields that even a no-op produces a huge amount of changes--making diffs viewed on github not very useful. WYSIWYG markup would be best, but having support for html (like markdown has) would be nice for formatting edge cases. (XML isn't an issue so much as all the cascading metadata changes in odf).

There should be a way to turn the document into html that can be rendered well on small devices like smartphones and also on devices with big screens. I should also be able to turn the document into a PDF that can be printed to common paper sizes like A4.

Ideally, there would be some clever way to convert hyperlinks and videos in the document into 2D barcode when converted to a PDF so that this data is not lost when prepared for printing to physical paper.

Requirements

  1. Diffs play well in VCS like git
  2. Table cells can do simple math based on the contents of other cells, such as calculate a total (sum of the column)
  3. Javascript is not a requirement for the client (the calculations shouldn't be made with client-side javascript)

Is there a good software solution for documentation that plays well with VCS and supports embedding spreadsheets/tables with basic calculations in the document?

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Browse other questions tagged or ask your own question.