# Tools for documenting a ruby project **URL:** \ **Category:** Ruby\ **Created:** [April 22, 2007, 2:55pm UTC](https://www.ruby-forum.com/t/tools-for-documenting-a-ruby-project/92647 "2007-04-22T14:55:57Z")\ **Posts on this page:** 2\ **Page:** 1
**Author:** ![Siemen\_B](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/s/7bcc69/32.png) [@Siemen\_B](https://www.ruby-forum.com/u/Siemen_B)\ **Post date:** [April 22, 2007, 2:55pm UTC](https://www.ruby-forum.com/t/tools-for-documenting-a-ruby-project/92647/1 "2007-04-22T14:55:57Z")
Hi list, I am about to hand in a report for an educational programming project and am looking for a smart and easy way to typeset it and the ruby code for the appendix. I think others must have done similar things and would be grateful to hear about you personal experiences and opinions. The report is ~10 pages with the usual elements of academic writing - abstract, sections, headings, literature references, footnotes and a reference list. In the appendices I have ~2000 lines of ruby code which I would like to typeset with typographic syntax highlighting, line numbers and file names. I also want to show the applications directory structure which I could grab with `tree`. Finally there are some tables and images. I do not have to document the entire application at code/API level. I’d prefer to be able to autogenerate the report entirely so I can make last-minute changes to the code without having to cope with redundancy in the report. I want to stay DRY… At the end, I want it all to be in a single pdf file ready for handing in as a printout. I have been looking at different markup languages and the most relevant for writing the report seem to be textile and markdown, maybe with markdown as the most human-readable. I could also go with a more low-level xml format, I would then use HAML to generate it, but the easier the better. I have no experience with typesetting xml files with CSS for print, but am used to typeset xhtml for on-screen presentation in web browsers. If this is the way to go, then which tools can turn my markdown/xml & css into a nice pdf file? Any suggestions are most welcome! thanks, Siemen ---
**Author:** ![Siemen\_B](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/s/7bcc69/32.png) [@Siemen\_B](https://www.ruby-forum.com/u/Siemen_B)\ **Post date:** [April 22, 2007, 5:57pm UTC](https://www.ruby-forum.com/t/tools-for-documenting-a-ruby-project/92647/2 "2007-04-22T17:57:21Z")
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Siemen B. wrote: > reference list. In the appendices I have ~2000 lines of ruby code > At the end, I want it all to be in a single pdf file ready for handing > but am used to typeset xhtml for on-screen presentation in web > browsers. If this is the way to go, then which tools can turn my > markdown/xml & css into a nice pdf file? > > Any suggestions are most welcome! > > thanks, > Siemen It all depends on how much time you have available before the deadline to learn to operate new tools. My experience has been that unless you use the tools from the _very beginning_ of the project, you’ll inevitably need to fall back on stuff that you know how to operate in order to meet your deadline. So, that said, here are some tools I know about. 1. [OpenOffice.org](http://OpenOffice.org) has some pretty good ways of dealing with HTML, XML and is capable of making a PDF. 2. LyX has some hooks for literate programming. It is TeX based rather than XML/HTML based, although it can import files in text, HTML and XML formats. Try [www.lyx.org](http://www.lyx.org). Their demos of literate programming are in C and Python, not Ruby. I’ve done a few LyX literate Ruby programs, but nothing I thought were good enough to show the world. 3. TeXmacs is also TeX based and is similar to LyX. TeXmacs’ native languages are Scheme (Guile) and to a lesser extent Python, but I’m pretty sure there’s documentation enough to enable one to start up a Ruby session like you can with other languages. 4. There are at least two “literate programming” projects in Ruby. I haven’t used them, so I can’t comment on whether they would meet your needs. I actually am working on an integration of Ruby and LyX for literate programming, but I don’t have anything you could use at the moment. Actually, the concept is a little stronger than literate programming – it’s called “reproducible research”. The fundamental deliverable is what is called a “compendium” – a collection of code, data and documentation that’s delivered as a software package. The R community has a lot of tools for this, and I’m in the process of porting them to Ruby. I didn’t think of syntax highlighting until you mentioned it, though, so thanks!! * * * M. Edward (Ed) Borasky, FBG, AB, PTA, PGS, MS, MNLP, NST, ACMC(P) [http://borasky-research.net/](http://borasky-research.net/) If God had meant for carrots to be eaten cooked, He would have given rabbits fire. -----BEGIN PGP SIGNATURE----- Version: GnuPG v2.0.3 (GNU/Linux) Comment: Using GnuPG with Mozilla - [http://enigmail.mozdev.org](http://enigmail.mozdev.org) iD8DBQFGK4VtIqRAswy4LDARAi52AJ4/GzWXBUOd0U8JrojgPaW6dup4CgCeP+bf +HHQPwpwPAPQQV0vll4VUAI= =cZ7F -----END PGP SIGNATURE-----