Re: New member - where to begin

On Fri, 23 Oct 2009, Roderick A. Anderson wrote:

> * What format? DocBook was mentioned.

http://developer.postgresql.org/pgdocs/postgres/docguide.html is the main
intro to this area and the latest docs available. You'll need to check
out the current release from CVS or git to generate patches; see
http://wiki.postgresql.org/wiki/Development_information for guides to both
of those.

> I prefer vim so what are your preferences for plugins-wise?
> * Any Vim+DocBook or DocBook howtos/tutorials that you would recommend?

For the most part simple changes are easy enough to make; just mimic the
style of similar markup and confirm the docs still build after your
change. I'd recommend using a version control system where you can track
your diffs easier and commit in stages, particularly when getting started.
That makes it easier to figure out what broke after a bad change and you
can incrementally save successful changes until you get more comfortable.

If you have the full vim set (vim-enhanced on Fedora/RHEL, vim-full on
Debian/Ubuntu), there is some assistance the editor can provide. There's
a quick intro to helpful features to toggle at
http://docs.fedoraproject.org/documentation-guide/en_US/ch-vim.html and a
much longer discussion of macros at
http://www.linuxjournal.com/article/7737 ; you really don't need anything
beyond simple customizations in most cases though, simple tool assistance
and cut/paste example copying is plenty if you're not authoring a serious
docbook work from scratch.

One helpful thing you might do right off the bat is update section I.4
"Documentation Authoring" with a section covering vim, to match the one
already there for emacs, to include whatever you find works here.
Getting documentation updates from patch authors is always hard to do, and
some better information to help them accomplish that would be valuable.

--
* Greg Smith gsmith(at)gregsmith(dot)com http://www.gregsmith.com Baltimore, MD