Issue #79 new

Create a Manual

Michael Granger
repo owner created an issue

I've been considering starting a manual for the 'pg' library, but haven't had the time or motivation to do so up to now.

Ticket <<issue 78>>, while a poor example of issue-reporting, had a kernel of truth within the rude hyperbole: there really isn't any good resource (that I know of) on how to start using the 'pg' library, especially the more-advanced features. I usually just refer to the C API docs, which are excellent, because 'pg' maps to the libpq API pretty much one-to-one. But that's not intuitive, and translating the C into idiomatic Ruby isn't really straighforward.

After converting the build system to use Hoe, I'm going to add the 'hoe-manualgen' plugin, and start working on a cookbook-style manual like [[http://deveiate.org/code/Treequel/|the one I did for Treequel]].

I'll start with an outline, split it into pages, and once I have the initial section done, perhaps solicit people's help in finishing up the rest.

Comments (7)

  1. Mahlon Smith

    While it certinaly doesn't take the place of a gentle manual, to anyone stumbling onto this ticket looking for a "Getting Started" -- check the distribution's samples directory for a pile of working examples.

  2. Jesse Cooke

    Some documentation on how to set up the development environment would be appreciated too. Just getting the tests to run on Ubuntu 12.04 with postgres installed via aptitude & the latest 1.9.3 (p327) was tricky. I'll add the notes here in case they can be helpful in creating a manual later.

    The .rvmrc file activates ruby-1.9.3, and at the time of this comment that's patch level 327. The rake that is installed is version 10, which is incompatible with hoe 3.2.0. So, in order to avoid the LoadError "This Rakefile requires hoe (gem install hoe)" you must run rake using an older version. I did this by using rake _0.9.3_.

    The second issue I ran in to was that the initdb command was not found. I have pg 9.2 installed via aptitude, and I had to change my $PATH as follows:

    export PATH=/usr/lib/postgresql/9.2/bin:$PATH

    Once I updated my $PATH I was able to rake _0.9.3_ newb and see the tests mostly pass (only 1 failure)

    I hope this helps with the manual or anyone else that is wanting to contribute.

  3. Log in to comment