Thread: pgAgent manpage
Hi Dave, friends,
santa claus just passed through my house and left this manpage near my
shoes... So, merry christmas!
pgagent.xml is the docbook-xml source for this manpage and pgagent.1 was
compiled with the following command under Debian/Sarge:
docbook2x-man pgagent.xml
I can convert the old pgadmin3.1 that I ship with Debian packages to
docbook-xml if needed. I'd prefer that we all ship these manpages for
next releases instead of releasing them specifically for Debian, what do
you think of adding them to the main install process?
Regards,
Raph
.TH pgagent 1 "December 26, 2005"
.SH NAME
pgAgent \- a job scheduler for PostgreSQL.
.SH SYNOPSIS
\fBpgagent\fR [\-f | \-t \fBseconds\fR | \-r \fBseconds\fR | \-l \fBnumber\fR] {<connect string>}
.SH DESCRIPTION
Introduced in pgAdmin III v1.4, pgAgent is a job scheduling agent
for PostgreSQL, capable of running multi\-step batch/shell and SQL tasks on
complex schedules.
.PP
A full documentation of pgAgent is available in pgadmin3's online
help. Launch pgAdmin III (simply type pgadmin3 at command prompt) and
select "Help..." from the "Help" menu. Browse through the pgAdmin III
documentation until you find "pgAgent". Both database setup and system
part of the installation are detailed. You will also find instructions
to create jobs and schedules.
.SH OPTIONS
.TP
\fB\-f\fR
run in the foreground (do not detach from the
terminal)
.TP
\fB\-t\fR \fIseconds\fR
poll time interval in seconds (default 10)
.TP
\fB\-r\fR \fIseconds\fR
retry period after connection abort in seconds (>=10,
default 30)
.TP
\fB\-l\fR \fIverbosity\fR
logging verbosity (ERROR=0, WARNING=1, DEBUG=2, default
0)
.TP
\fI<connect string>\fR
The connect string required is a standard PostgreSQL libpq
connection string (see the PostgreSQL documentation for further
details). For example, the following command line will run pgAgent
against a server listening on the localhost, using a database called
\&'pgadmin', connecting as the user 'postgres': /usr/bin/pgagent
hostaddr=127.0.0.1 dbname=pgadmin user=postgres
.SH "SEE ALSO"
\fBpgadmin3\fR(1)
.SH AUTHORS
The content of this maniual page was mostly ripped from documentation
written by the pgAdmin development team. It was built by Rapha\(:el Enrici
<blacknoz@club\-internet.fr>, for the Debian project (but may be used
by others).
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<refentry id="pgagent">
<refmeta>
<refentrytitle>pgagent</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class='source'>December 26, 2005</refmiscinfo>
</refmeta>
<refnamediv>
<refname>pgAgent</refname>
<refpurpose>a job scheduler for PostgreSQL.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>pgagent</command>
<group>
<arg>-f</arg>
<arg>-t <replaceable>seconds</replaceable></arg>
<arg>-r <replaceable>seconds</replaceable></arg>
<arg>-l <replaceable>number</replaceable></arg>
</group>
<arg choice="req"><connect string></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>DESCRIPTION</title>
<para>Introduced in pgAdmin III v1.4, pgAgent is a job scheduling agent
for PostgreSQL, capable of running multi-step batch/shell and SQL tasks on
complex schedules.</para>
<para>A full documentation of pgAgent is available in pgadmin3's online
help. Launch pgAdmin III (simply type pgadmin3 at command prompt) and
select "Help..." from the "Help" menu. Browse through the pgAdmin III
documentation until you find "pgAgent". Both database setup and system
part of the installation are detailed. You will also find instructions
to create jobs and schedules.</para>
</refsect1>
<refsect1>
<title>OPTIONS</title>
<variablelist>
<varlistentry>
<term><option>-f</option></term>
<listitem>
<para>run in the foreground (do not detach from the
terminal)</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term><option>-t</option> <replaceable>seconds</replaceable></term>
<listitem>
<para>poll time interval in seconds (default 10)</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term><option>-r</option> <replaceable>seconds</replaceable></term>
<listitem>
<para>retry period after connection abort in seconds (>=10,
default 30)</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term><option>-l</option> <replaceable>verbosity</replaceable></term>
<listitem>
<para>logging verbosity (ERROR=0, WARNING=1, DEBUG=2, default
0)</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term><replaceable><connect string></replaceable></term>
<listitem>
<para>The connect string required is a standard PostgreSQL libpq
connection string (see the PostgreSQL documentation for further
details). For example, the following command line will run pgAgent
against a server listening on the localhost, using a database called
'pgadmin', connecting as the user 'postgres': /usr/bin/pgagent
hostaddr=127.0.0.1 dbname=pgadmin user=postgres</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para><emphasis role="bold">pgadmin3</emphasis>(1)</para>
</refsect1>
<refsect1>
<title>AUTHORS</title>
<para>The content of this maniual page was mostly ripped from documentation
written by the pgAdmin development team. It was built by Raphaël Enrici
<blacknoz@club-internet.fr>, for the Debian project (but may be used
by others).</para>
</refsect1>
</refentry>
On 26/12/05 22:36, "Raphaël Enrici" <blacknoz@club-internet.fr> wrote: > Hi Dave, friends, > > santa claus just passed through my house and left this manpage near my > shoes... So, merry christmas! > > pgagent.xml is the docbook-xml source for this manpage and pgagent.1 was > compiled with the following command under Debian/Sarge: > docbook2x-man pgagent.xml > > I can convert the old pgadmin3.1 that I ship with Debian packages to > docbook-xml if needed. I'd prefer that we all ship these manpages for > next releases instead of releasing them specifically for Debian, what do > you think of adding them to the main install process? Hi Raph, I've got no problems with that at all. Can you prepare both XML files and a suitable makefile? I guess we might also need a macro to make sure docbook-xml is actually installed - I can probably help with that if required, though it would probably be guesswork to a certain extent! I've never seen a localised man page, though I guess they probably do exist - so so we use doc/man or doc/en_US/man? Regards, Dave.
Dave Page wrote: > > > On 26/12/05 22:36, "Raphaël Enrici" <blacknoz@club-internet.fr> wrote: > > >>Hi Dave, friends, >> >>santa claus just passed through my house and left this manpage near my >>shoes... So, merry christmas! >> >>pgagent.xml is the docbook-xml source for this manpage and pgagent.1 was >>compiled with the following command under Debian/Sarge: >>docbook2x-man pgagent.xml >> >>I can convert the old pgadmin3.1 that I ship with Debian packages to >>docbook-xml if needed. I'd prefer that we all ship these manpages for >>next releases instead of releasing them specifically for Debian, what do >>you think of adding them to the main install process? > > > Hi Raph, > > I've got no problems with that at all. Can you prepare both XML files and a > suitable makefile? Ok, I'm preparing the files. Until I'm ready can you recheck the pgAgent manpage I sent (in particular the synopsis) please. > I guess we might also need a macro to make sure > docbook-xml is actually installed - I can probably help with that if > required, though it would probably be guesswork to a certain extent! As far as I know a patched version of docbook2x-man is deistributed directly with PostgreSQL, maybe it would be interesting to take a look to how they are organizing the stuff? > I've never seen a localised man page, though I guess they probably do exist > - so so we use doc/man or doc/en_US/man? I confirm they do exist :) On my system all C manpages are installed in /usr/share/man/man[1|2|...] and localised ones are installed in /usr/share/man/(fr_FR|es_ES|...)/man[1|2|...] I would use doc/man and doc/man/fr_FR & so on. It should be investigated though. One more time, let's take a look to how it's done for PostgreSQL. Regards, Raph
On 30/12/05 15:20, "Raphaël Enrici" <blacknoz@club-internet.fr> wrote: >> I've got no problems with that at all. Can you prepare both XML files and a >> suitable makefile? > > Ok, I'm preparing the files. Until I'm ready can you recheck the pgAgent > manpage I sent (in particular the synopsis) please. Sure. The only changes I'd suggest are summed up in the following line: A full documentation of pgAgent is available in pgadmin3's online Which reads better as Full documentation for pgAgent is available in pgAdmin III's online 'A full documentation' doesn't work, as documentation implies plural 'documents', whilst A is singular. The other is simply me with my marketing hat on - please use the full 'pgAdmin III' in text, and pgadmin3 for path/filenames etc. >> I guess we might also need a macro to make sure >> docbook-xml is actually installed - I can probably help with that if >> required, though it would probably be guesswork to a certain extent! > > As far as I know a patched version of docbook2x-man is deistributed > directly with PostgreSQL, maybe it would be interesting to take a look > to how they are organizing the stuff? Not as far as I've ever found (ever tried building the docs on a clean Slackware for example?), but regardless, the PostgreSQL docs are Docbook SGML, not XML. >> I've never seen a localised man page, though I guess they probably do exist >> - so so we use doc/man or doc/en_US/man? > > I confirm they do exist :) On my system all C manpages are installed in > /usr/share/man/man[1|2|...] and localised ones are installed in > /usr/share/man/(fr_FR|es_ES|...)/man[1|2|...] > > I would use doc/man and doc/man/fr_FR & so on. It should be investigated > though. One more time, let's take a look to how it's done for PostgreSQL. There are no localised docs shipped with PostgreSQL. We should not mix conventions in our source tarballs though, even if they do install into different places - let's put them all under doc/xx_XX/man. Regards, Dave.
Dave Page wrote: <snip> > Sure. The only changes I'd suggest are summed up in the following line: > A full documentation of pgAgent is available in pgadmin3's online > Which reads better as > > Full documentation for pgAgent is available in pgAdmin III's online > > 'A full documentation' doesn't work, as documentation implies plural > 'documents', whilst A is singular. > > The other is simply me with my marketing hat on - please use the full > 'pgAdmin III' in text, and pgadmin3 for path/filenames etc. ok, thanks for the corrections, I'll apply them before submitting the stuff back to you. >>>I guess we might also need a macro to make sure >>>docbook-xml is actually installed - I can probably help with that if >>>required, though it would probably be guesswork to a certain extent! >> >>As far as I know a patched version of docbook2x-man is deistributed >>directly with PostgreSQL, maybe it would be interesting to take a look >>to how they are organizing the stuff? > > Not as far as I've ever found (ever tried building the docs on a clean > Slackware for example?), but regardless, the PostgreSQL docs are Docbook > SGML, not XML. Maybe we should not make pgAdmin III's tarball depend on docbook-xml... I mean that the docbook2x package which contains the docbook2x-man depends on many packages. IMHO, making pgAdmin III build depends on the same dependencies just to build manpages would be more confusing than useful... I'd prefer that the machine building the source tarball contains the mandatory software to build the manpage on the fly before building the tarball and/or that we all generate the nroff format when submitting updates to the docbook-xml manpages, just like I did when I've submitted them for review. What do you think about it? FYI, docbook2x Debian packge has the following dependencies: Depends: libc6 (>= 2.3.2.ds1-4), libxml2 (>= 2.6.11), libxslt1.1 (>= 1.1.7), zlib1g (>= 1:1.2.1), perl (>= 5.6.0-16), libxml-sax-expat-perl, libtext-wrapi18n-perl Recommends: docbook-xml, docbook-xsl > There are no localised docs shipped with PostgreSQL. We should not mix > conventions in our source tarballs though, even if they do install into > different places - let's put them all under doc/xx_XX/man. ok, you're right. Regards, Raph
On 30/12/05 20:32, "Raphaël Enrici" <blacknoz@club-internet.fr> wrote: > Maybe we should not make pgAdmin III's tarball depend on docbook-xml... > I mean that the docbook2x package which contains the docbook2x-man > depends on many packages. IMHO, making pgAdmin III build depends on the > same dependencies just to build manpages would be more confusing than > useful... > I'd prefer that the machine building the source tarball contains the > mandatory software to build the manpage on the fly before building the > tarball and/or that we all generate the nroff format when submitting > updates to the docbook-xml manpages, just like I did when I've submitted > them for review. What do you think about it? > Sounds perfectly sensible - perhaps it should be part of the bootstrap script, rather than hacked into 'make dist' (which I have no idea how to do!). > > >> There are no localised docs shipped with PostgreSQL. We should not mix >> conventions in our source tarballs though, even if they do install into >> different places - let's put them all under doc/xx_XX/man. > > ok, you're right. Well, I try :-p /D