Create a Manual

[ged]

Original report by Michael Granger (Bitbucket: ged, GitHub: ged).

---

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.

[ged]

Original comment by Mahlon E. Smith (Bitbucket: mahlon, GitHub: mahlon).

---

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.

[ged]

Original comment by Anonymous.

---

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.

[ged]

Original comment by Michael Granger (Bitbucket: ged, GitHub: ged).

---

@jc00ke: Thanks for the notes. I was unaware of the hoe incompatibility; I guess I'll have to bite the bullet and rebuild all of my 1.9.3 rvm gemsets for the new patchlevel.

[ged]

Original comment by Anonymous.

---

@ged You're welcome!

Re rake/hoe: Are you opposed to using a gemspec and Bundler? I've gotten away from using gemsets and it's simplified my life considerably. ;)

[ged]

Original comment by Michael Granger (Bitbucket: ged, GitHub: ged).

---

@jc00ke: Yes, absolutely. I have had exactly the opposite experience with Bundler that you have, and very few with RVM. Sorry. :/

[ged]

Original comment by Anonymous.

---

@ged no worries, I was just curious. As Bundler's gotten better I've had fewer & fewer issues. I had never seen the gemset import method before though; that's slick.

[ged]

Original comment by Michael Granger (Bitbucket: ged, GitHub: ged).

---

I think the API docs are now pretty good (especially with @larskanis 's excellent work), and the samples directory has a good selection of how to use the more-esoteric features, so I'm going to close this.