pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedJava class documentation
7+ messages / 3 participants
[nested] [flat]
* Java class documentation
@ 2001-02-22 21:07 Peter Eisentraut <peter_e@gmx.net>
0 siblings, 3 replies; 7+ messages in thread
From: Peter Eisentraut @ 2001-02-22 21:07 UTC (permalink / raw)
To: pgsql-docs; +Cc: pgsql-jdbc@postgresql.org
I've started to finish up the not-marked-up-yet parts of the JDBC
documentation, but most of this seems to have once been generated by
javadoc, and I feel like it is probably a wasted effort to try to manually
convert this to DocBook.
AFAIK, there is currently no Javadoc to DocBook converter available. This
might be a worthwhile project, though.
Could we for now remove the formal class documentation from the DocBook
source, while keeping the narrative parts, and instead point people to the
JavaDoc? Could we make prebuild class documentation in HTML available to
users, maybe where the jars are downloaded?
--
Peter Eisentraut peter_e@gmx.net http://yi.org/peter-e/
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: Java class documentation
@ 2001-02-23 16:00 Thomas Lockhart <lockhart@alumni.caltech.edu>
parent: Peter Eisentraut <peter_e@gmx.net>
2 siblings, 1 reply; 7+ messages in thread
From: Thomas Lockhart @ 2001-02-23 16:00 UTC (permalink / raw)
To: Peter Eisentraut <peter_e@gmx.net>; +Cc: pgsql-docs; pgsql-jdbc@postgresql.org
> Could we for now remove the formal class documentation from the DocBook
> source, while keeping the narrative parts, and instead point people to the
> JavaDoc? Could we make prebuild class documentation in HTML available to
> users, maybe where the jars are downloaded?
Works for me. Not sure if we have rules for building javadoc in our
makefiles, but I'm sure it would be easy to add if necessary. Peter M,
what do you think?
- Thomas
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: Java class documentation
@ 2001-02-23 19:32 Peter Eisentraut <peter_e@gmx.net>
parent: Thomas Lockhart <lockhart@alumni.caltech.edu>
0 siblings, 0 replies; 7+ messages in thread
From: Peter Eisentraut @ 2001-02-23 19:32 UTC (permalink / raw)
To: lockhart@fourpalms.org; +Cc: pgsql-docs; pgsql-jdbc@postgresql.org
Thomas Lockhart writes:
> > Could we for now remove the formal class documentation from the DocBook
> > source, while keeping the narrative parts, and instead point people to the
> > JavaDoc? Could we make prebuild class documentation in HTML available to
> > users, maybe where the jars are downloaded?
>
> Works for me. Not sure if we have rules for building javadoc in our
> makefiles, but I'm sure it would be easy to add if necessary. Peter M,
> what do you think?
Actually, writing a simplistic javadoc to docbook converter ("doclet")
turned out to be rather easy. I can create <refentry> pages for the
relevant classes and put them where the current text is.
The result is a bit ugly, actually, because javadoc does not have the rich
structure that docbook has, while none of docbook's structure actually
matches the javadoc format, so it would still be of interest to have the
full javadoc/html set available.
--
Peter Eisentraut peter_e@gmx.net http://yi.org/peter-e/
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: Java class documentation
@ 2001-02-24 17:47 Peter Mount <peter@retep.org.uk>
parent: Peter Eisentraut <peter_e@gmx.net>
2 siblings, 2 replies; 7+ messages in thread
From: Peter Mount @ 2001-02-24 17:47 UTC (permalink / raw)
To: Peter Eisentraut <peter_e@gmx.net>; pgsql-docs; +Cc: pgsql-jdbc@postgresql.org
At 22:07 22/02/01 +0100, Peter Eisentraut wrote:
>I've started to finish up the not-marked-up-yet parts of the JDBC
>documentation, but most of this seems to have once been generated by
>javadoc, and I feel like it is probably a wasted effort to try to manually
>convert this to DocBook.
Actually I was waiting until 7.1 was out before rewriting the jdbc docs
from scratch (so much has changed since those were written).
>AFAIK, there is currently no Javadoc to DocBook converter available. This
>might be a worthwhile project, though.
>
>Could we for now remove the formal class documentation from the DocBook
>source, while keeping the narrative parts, and instead point people to the
>JavaDoc? Could we make prebuild class documentation in HTML available to
>users, maybe where the jars are downloaded?
Already a work in progress. You might be duplicating work already being
done for the jdbc site.
Peter
>--
>Peter Eisentraut peter_e@gmx.net http://yi.org/peter-e/
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: Java class documentation
@ 2001-02-24 18:03 Peter Mount <peter@retep.org.uk>
parent: Peter Eisentraut <peter_e@gmx.net>
2 siblings, 0 replies; 7+ messages in thread
From: Peter Mount @ 2001-02-24 18:03 UTC (permalink / raw)
To: lockhart@fourpalms.org, Peter Eisentraut <peter_e@gmx.net>; +Cc: pgsql-docs; pgsql-jdbc@postgresql.org
At 16:00 23/02/01 +0000, Thomas Lockhart wrote:
> > Could we for now remove the formal class documentation from the DocBook
> > source, while keeping the narrative parts, and instead point people to the
> > JavaDoc? Could we make prebuild class documentation in HTML available to
> > users, maybe where the jars are downloaded?
>
>Works for me. Not sure if we have rules for building javadoc in our
>makefiles, but I'm sure it would be easy to add if necessary. Peter M,
>what do you think?
As I just replied to PeterE, I was waiting for 7.1 to be out before
rewriting the docs from scratch. I was waiting because of time restraints
and I didn't want to mess up the exiting docs, especially as I knew you
needed time before release with the docs static.
What I'm working on for the jdbc site is a set of API docs explaining the
PostgreSQL specific extensions, and a set of tutorials. The tutorials range
from the basic stuff (replacing the examples in the source), to writing
Servlets with PostgreSQL, EJB's, Corba etc.
Now a Javadoc->DocBook converter should be easy. In fact you can get
javadoc to do it for you using the Doclet API. Should be real easy to do.
Peter
> - Thomas
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: Java class documentation
@ 2001-02-24 23:28 Peter Eisentraut <peter_e@gmx.net>
parent: Peter Mount <peter@retep.org.uk>
1 sibling, 0 replies; 7+ messages in thread
From: Peter Eisentraut @ 2001-02-24 23:28 UTC (permalink / raw)
To: Peter Mount <peter@retep.org.uk>; +Cc: pgsql-docs; pgsql-jdbc@postgresql.org
Peter Mount writes:
> Actually I was waiting until 7.1 was out before rewriting the jdbc docs
> >from scratch (so much has changed since those were written).
I can see that. However, 7.1 users should still get the benefit of
reasonably up to date documentation. I've at least changed all package
references to 'org.postgresql' and said something about ant, plus some
spell checking and polishing. Perhaps you can scan it to make sure it's
not complete garbage.
http://www.postgresql.org/devel-corner/docs/postgres/jdbc.html
--
Peter Eisentraut peter_e@gmx.net http://yi.org/peter-e/
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: Java class documentation
@ 2001-03-01 20:01 Peter Mount <peter@retep.org.uk>
parent: Peter Mount <peter@retep.org.uk>
1 sibling, 0 replies; 7+ messages in thread
From: Peter Mount @ 2001-03-01 20:01 UTC (permalink / raw)
To: Peter Eisentraut <peter_e@gmx.net>; +Cc: pgsql-docs; pgsql-jdbc@postgresql.org
At 00:28 25/02/01 +0100, Peter Eisentraut wrote:
>Peter Mount writes:
>
> > Actually I was waiting until 7.1 was out before rewriting the jdbc docs
> > >from scratch (so much has changed since those were written).
>
>I can see that. However, 7.1 users should still get the benefit of
>reasonably up to date documentation. I've at least changed all package
>references to 'org.postgresql' and said something about ant, plus some
>spell checking and polishing. Perhaps you can scan it to make sure it's
>not complete garbage.
>
>http://www.postgresql.org/devel-corner/docs/postgres/jdbc.html
Ok, I will do.
Sorry for the late reply, it's been a hectic week and its the first time
I've had to even use my home machine since Sunday :-(
Peter
>--
>Peter Eisentraut peter_e@gmx.net http://yi.org/peter-e/
^ permalink raw reply [nested|flat] 7+ messages in thread
end of thread, other threads:[~2001-03-01 20:01 UTC | newest]
Thread overview: 7+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2001-02-22 21:07 Java class documentation Peter Eisentraut <peter_e@gmx.net>
2001-02-23 16:00 ` Thomas Lockhart <lockhart@alumni.caltech.edu>
2001-02-23 19:32 ` Peter Eisentraut <peter_e@gmx.net>
2001-02-24 17:47 ` Peter Mount <peter@retep.org.uk>
2001-02-24 23:28 ` Peter Eisentraut <peter_e@gmx.net>
2001-03-01 20:01 ` Peter Mount <peter@retep.org.uk>
2001-02-24 18:03 ` Peter Mount <peter@retep.org.uk>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox