tools for documenting a ruby project

[Siemen Baader]

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

 

[M. Edward (Ed) Borasky]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

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

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 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. 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/

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

iD8DBQFGK4VtIqRAswy4LDARAi52AJ4/GzWXBUOd0U8JrojgPaW6dup4CgCeP+bf
+HHQPwpwPAPQQV0vll4VUAI=
=cZ7F
-----END PGP SIGNATURE-----