pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedTips needed for contrib doc
13+ messages / 4 participants
[nested] [flat]
* Tips needed for contrib doc
@ 2007-10-10 21:15 Albert Cervera i Areny <albert@nan-tic.com>
2007-10-11 07:48 ` Re: Tips needed for contrib doc Guillaume Lelarge <guillaume@lelarge.info>
2007-10-12 17:47 ` Re: Tips needed for contrib doc Peter Eisentraut <peter_e@gmx.net>
2007-10-17 19:35 ` Re: Tips needed for contrib doc Albert Cervera i Areny <albert@nan-tic.com>
0 siblings, 3 replies; 13+ messages in thread
From: Albert Cervera i Areny @ 2007-10-10 21:15 UTC (permalink / raw)
To: pgsql-docs
Hi,
I wanted to spend a week or so putting the contrib doc into shape so I want
to start by moving the contrib part from a new appendix to the Reference
part.
The problems I find are:
- I can't make this "contrib" doc a part because Reference already is a part
and can't be nested.
Structure:
<part id="reference">
<part id="contrib">
- If I make the contrib doc a chapter in the index shows with an arabic
number not as a roman one.
Structure:
<part id="reference">
<chapter id="contrib">
- I can't make the doc a <reference> because first I need to point to the
modules and not all of them are documented like a reference.
Structure:
<part id="reference">
<reference id="contrib">
- If I leave it as it is now [1] the problem is that very small chapters just
don't look right IMHO. Take a look at [2], for example. It should be a module
per page in most cases except very long ones.
Structure:
<part id="contrib">
<chapter id="adminpack">
Does anyone have a solution on this? I'm no docbook expert, so I might be very
wrong.
[1] You can find the current state at
http://www.nan-tic.com/ftp/pgdoc-0.0.2/index.html
[2] http://www.nan-tic.com/ftp/pgdoc-0.0.2/adminpack.html
--
Albert Cervera i Areny
http://www.NaN-tic.com
^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: Tips needed for contrib doc
2007-10-10 21:15 Tips needed for contrib doc Albert Cervera i Areny <albert@nan-tic.com>
@ 2007-10-11 07:48 ` Guillaume Lelarge <guillaume@lelarge.info>
2007-10-11 14:08 ` Re: Tips needed for contrib doc Tom Lane <tgl@sss.pgh.pa.us>
2 siblings, 1 reply; 13+ messages in thread
From: Guillaume Lelarge @ 2007-10-11 07:48 UTC (permalink / raw)
To: Albert Cervera i Areny <albert@nan-tic.com>; +Cc: pgsql-docs
Hi,
Albert Cervera i Areny a écrit :
> I wanted to spend a week or so putting the contrib doc into shape so I want
> to start by moving the contrib part from a new appendix to the Reference
> part.
> The problems I find are:
> - I can't make this "contrib" doc a part because Reference already is a part
> and can't be nested.
> Structure:
> <part id="reference">
> <part id="contrib">
>
> - If I make the contrib doc a chapter in the index shows with an arabic
> number not as a roman one.
> Structure:
> <part id="reference">
> <chapter id="contrib">
>
> - I can't make the doc a <reference> because first I need to point to the
> modules and not all of them are documented like a reference.
> Structure:
> <part id="reference">
> <reference id="contrib">
>
I think this is the better way to do it. Even if it means to rewrite the
README to look like a reference.
> - If I leave it as it is now [1] the problem is that very small chapters just
> don't look right IMHO. Take a look at [2], for example. It should be a module
> per page in most cases except very long ones.
> Structure:
> <part id="contrib">
> <chapter id="adminpack">
>
> Does anyone have a solution on this? I'm no docbook expert, so I might be very
> wrong.
>
The only (or simplest) way to have one page per module is to use the
reference part.
Regards.
--
Guillaume.
http://www.postgresqlfr.org
http://dalibo.com
^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: Tips needed for contrib doc
2007-10-10 21:15 Tips needed for contrib doc Albert Cervera i Areny <albert@nan-tic.com>
2007-10-11 07:48 ` Re: Tips needed for contrib doc Guillaume Lelarge <guillaume@lelarge.info>
@ 2007-10-11 14:08 ` Tom Lane <tgl@sss.pgh.pa.us>
2007-10-12 17:13 ` Re: Tips needed for contrib doc Albert Cervera i Areny <albert@nan-tic.com>
0 siblings, 1 reply; 13+ messages in thread
From: Tom Lane @ 2007-10-11 14:08 UTC (permalink / raw)
To: Guillaume Lelarge <guillaume@lelarge.info>; +Cc: Albert Cervera i Areny <albert@nan-tic.com>; pgsql-docs
Guillaume Lelarge <guillaume@lelarge.info> writes:
> The only (or simplest) way to have one page per module is to use the
> reference part.
If the plan is one module per page, why not handle 'em just like the
current command and client reference pages? Add another list to
reference.sgml, and away you go.
regards, tom lane
^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: Tips needed for contrib doc
2007-10-10 21:15 Tips needed for contrib doc Albert Cervera i Areny <albert@nan-tic.com>
2007-10-11 07:48 ` Re: Tips needed for contrib doc Guillaume Lelarge <guillaume@lelarge.info>
2007-10-11 14:08 ` Re: Tips needed for contrib doc Tom Lane <tgl@sss.pgh.pa.us>
@ 2007-10-12 17:13 ` Albert Cervera i Areny <albert@nan-tic.com>
0 siblings, 0 replies; 13+ messages in thread
From: Albert Cervera i Areny @ 2007-10-12 17:13 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: pgsql-docs
The problem with this approach is dblink[1], for example, in which I can't use
reference (as I've already used for dblink itself). I will probably have to
use <refsect> in theses cases then...
[1] http://www.nan-tic.com/ftp/pgdoc/dblink.html
A Dijous 11 Octubre 2007, Tom Lane va escriure:
> Guillaume Lelarge <guillaume@lelarge.info> writes:
> > The only (or simplest) way to have one page per module is to use the
> > reference part.
>
> If the plan is one module per page, why not handle 'em just like the
> current command and client reference pages? Add another list to
> reference.sgml, and away you go.
>
> regards, tom lane
--
Albert Cervera i Areny
http://www.NaN-tic.com
^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: Tips needed for contrib doc
2007-10-10 21:15 Tips needed for contrib doc Albert Cervera i Areny <albert@nan-tic.com>
@ 2007-10-12 17:47 ` Peter Eisentraut <peter_e@gmx.net>
2007-10-12 18:04 ` Re: Tips needed for contrib doc Albert Cervera i Areny <albert@nan-tic.com>
2 siblings, 1 reply; 13+ messages in thread
From: Peter Eisentraut @ 2007-10-12 17:47 UTC (permalink / raw)
To: pgsql-docs; +Cc: Albert Cervera i Areny <albert@nan-tic.com>
Am Mittwoch, 10. Oktober 2007 schrieb Albert Cervera i Areny:
> - I can't make this "contrib" doc a part because Reference already
> is a part and can't be nested.
The Reference things in DocBook are mostly to support legacy man pages, and
man pages are not necessary the greatest format to document everything. What
is your reason that you want this as a reference rather than a part with
chapters?
--
Peter Eisentraut
http://developer.postgresql.org/~petere/
^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: Tips needed for contrib doc
2007-10-10 21:15 Tips needed for contrib doc Albert Cervera i Areny <albert@nan-tic.com>
2007-10-12 17:47 ` Re: Tips needed for contrib doc Peter Eisentraut <peter_e@gmx.net>
@ 2007-10-12 18:04 ` Albert Cervera i Areny <albert@nan-tic.com>
2007-10-14 13:05 ` Re: Tips needed for contrib doc Peter Eisentraut <peter_e@gmx.net>
0 siblings, 1 reply; 13+ messages in thread
From: Albert Cervera i Areny @ 2007-10-12 18:04 UTC (permalink / raw)
To: Peter Eisentraut <peter_e@gmx.net>; +Cc: pgsql-docs
Not that I want to make each module a reference. With previous discussions we
seemed to agree that:
- It should go into the References part of the documentation (right
after "III. PostgreSQL Server Applications).
- Each module docs should be in a single page, mainly because some contrib
modules have/require very little documentation.
So it seems that the only way of achieving both things is to make each contrib
module a <refentry> inside a new <reference id="contrib">. I don't like this
idea, among other things because dblink won't be abe to be treated as a
<reference> which I think is appropiate in this case.
If you've got another solution for this, it'll be very welcome!
A Divendres 12 Octubre 2007, Peter Eisentraut va escriure:
> Am Mittwoch, 10. Oktober 2007 schrieb Albert Cervera i Areny:
> > - I can't make this "contrib" doc a part because Reference
> > already is a part and can't be nested.
>
> The Reference things in DocBook are mostly to support legacy man pages, and
> man pages are not necessary the greatest format to document everything.
> What is your reason that you want this as a reference rather than a part
> with chapters?
--
Albert Cervera i Areny
http://www.NaN-tic.com
^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: Tips needed for contrib doc
2007-10-10 21:15 Tips needed for contrib doc Albert Cervera i Areny <albert@nan-tic.com>
2007-10-12 17:47 ` Re: Tips needed for contrib doc Peter Eisentraut <peter_e@gmx.net>
2007-10-12 18:04 ` Re: Tips needed for contrib doc Albert Cervera i Areny <albert@nan-tic.com>
@ 2007-10-14 13:05 ` Peter Eisentraut <peter_e@gmx.net>
2007-10-14 18:17 ` Re: Tips needed for contrib doc Albert Cervera i Areny <albert@nan-tic.com>
0 siblings, 1 reply; 13+ messages in thread
From: Peter Eisentraut @ 2007-10-14 13:05 UTC (permalink / raw)
To: Albert Cervera i Areny <albert@nan-tic.com>; +Cc: pgsql-docs
Albert Cervera i Areny wrote:
> Not that I want to make each module a reference. With previous
> discussions we seemed to agree that:
>
> - It should go into the References part of the documentation (right
> after "III. PostgreSQL Server Applications).
> - Each module docs should be in a single page, mainly because some
> contrib modules have/require very little documentation.
It think you should structure the documentation by content, not by
output format. You could make each module a section or a chapter, as
you choose.
--
Peter Eisentraut
http://developer.postgresql.org/~petere/
^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: Tips needed for contrib doc
2007-10-10 21:15 Tips needed for contrib doc Albert Cervera i Areny <albert@nan-tic.com>
2007-10-12 17:47 ` Re: Tips needed for contrib doc Peter Eisentraut <peter_e@gmx.net>
2007-10-12 18:04 ` Re: Tips needed for contrib doc Albert Cervera i Areny <albert@nan-tic.com>
2007-10-14 13:05 ` Re: Tips needed for contrib doc Peter Eisentraut <peter_e@gmx.net>
@ 2007-10-14 18:17 ` Albert Cervera i Areny <albert@nan-tic.com>
2007-10-14 19:05 ` Re: Tips needed for contrib doc Tom Lane <tgl@sss.pgh.pa.us>
2007-10-14 21:33 ` Re: Tips needed for contrib doc Peter Eisentraut <peter_e@gmx.net>
0 siblings, 2 replies; 13+ messages in thread
From: Albert Cervera i Areny @ 2007-10-14 18:17 UTC (permalink / raw)
To: Peter Eisentraut <peter_e@gmx.net>; +Cc: pgsql-docs
The problem is that if we want these docs in the Reference section of the
documentation right after "PostgreSQL Server Applications" they can't be
chapters nor sections, they need to be <refentry>'s. That's the problem...
A Diumenge 14 Octubre 2007, Peter Eisentraut va escriure:
> Albert Cervera i Areny wrote:
> > Not that I want to make each module a reference. With previous
> > discussions we seemed to agree that:
> >
> > - It should go into the References part of the documentation (right
> > after "III. PostgreSQL Server Applications).
> > - Each module docs should be in a single page, mainly because some
> > contrib modules have/require very little documentation.
>
> It think you should structure the documentation by content, not by
> output format. You could make each module a section or a chapter, as
> you choose.
--
Albert Cervera i Areny
http://www.NaN-tic.com
^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: Tips needed for contrib doc
2007-10-10 21:15 Tips needed for contrib doc Albert Cervera i Areny <albert@nan-tic.com>
2007-10-12 17:47 ` Re: Tips needed for contrib doc Peter Eisentraut <peter_e@gmx.net>
2007-10-12 18:04 ` Re: Tips needed for contrib doc Albert Cervera i Areny <albert@nan-tic.com>
2007-10-14 13:05 ` Re: Tips needed for contrib doc Peter Eisentraut <peter_e@gmx.net>
2007-10-14 18:17 ` Re: Tips needed for contrib doc Albert Cervera i Areny <albert@nan-tic.com>
@ 2007-10-14 19:05 ` Tom Lane <tgl@sss.pgh.pa.us>
1 sibling, 0 replies; 13+ messages in thread
From: Tom Lane @ 2007-10-14 19:05 UTC (permalink / raw)
To: Albert Cervera i Areny <albert@nan-tic.com>; +Cc: Peter Eisentraut <peter_e@gmx.net>; pgsql-docs
Albert Cervera i Areny <albert@nan-tic.com> writes:
> The problem is that if we want these docs in the Reference section of the
> documentation right after "PostgreSQL Server Applications" they can't be
> chapters nor sections, they need to be <refentry>'s. That's the problem...
In any case one would think that each contrib module should be at the
same logical level in the docs --- if some of them are only sections,
what chapter are they inside of?
One point here is that a lot of the contrib material is not really
written in reference style anyway. I wonder if the best solution is
to make it a separate <part>, with each contrib module being a
<chapter>, and then sections and subsections if needed.
regards, tom lane
^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: Tips needed for contrib doc
2007-10-10 21:15 Tips needed for contrib doc Albert Cervera i Areny <albert@nan-tic.com>
2007-10-12 17:47 ` Re: Tips needed for contrib doc Peter Eisentraut <peter_e@gmx.net>
2007-10-12 18:04 ` Re: Tips needed for contrib doc Albert Cervera i Areny <albert@nan-tic.com>
2007-10-14 13:05 ` Re: Tips needed for contrib doc Peter Eisentraut <peter_e@gmx.net>
2007-10-14 18:17 ` Re: Tips needed for contrib doc Albert Cervera i Areny <albert@nan-tic.com>
@ 2007-10-14 21:33 ` Peter Eisentraut <peter_e@gmx.net>
2007-10-14 23:48 ` Re: Tips needed for contrib doc Albert Cervera i Areny <albert@nan-tic.com>
1 sibling, 1 reply; 13+ messages in thread
From: Peter Eisentraut @ 2007-10-14 21:33 UTC (permalink / raw)
To: Albert Cervera i Areny <albert@nan-tic.com>; +Cc: pgsql-docs
Albert Cervera i Areny wrote:
> The problem is that if we want these docs in the Reference section of
> the documentation right after "PostgreSQL Server Applications" they
> can't be chapters nor sections, they need to be <refentry>'s.
That is not true, AFAICT. What do you base this assertion on?
--
Peter Eisentraut
http://developer.postgresql.org/~petere/
^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: Tips needed for contrib doc
2007-10-10 21:15 Tips needed for contrib doc Albert Cervera i Areny <albert@nan-tic.com>
2007-10-12 17:47 ` Re: Tips needed for contrib doc Peter Eisentraut <peter_e@gmx.net>
2007-10-12 18:04 ` Re: Tips needed for contrib doc Albert Cervera i Areny <albert@nan-tic.com>
2007-10-14 13:05 ` Re: Tips needed for contrib doc Peter Eisentraut <peter_e@gmx.net>
2007-10-14 18:17 ` Re: Tips needed for contrib doc Albert Cervera i Areny <albert@nan-tic.com>
2007-10-14 21:33 ` Re: Tips needed for contrib doc Peter Eisentraut <peter_e@gmx.net>
@ 2007-10-14 23:48 ` Albert Cervera i Areny <albert@nan-tic.com>
0 siblings, 0 replies; 13+ messages in thread
From: Albert Cervera i Areny @ 2007-10-14 23:48 UTC (permalink / raw)
To: Peter Eisentraut <peter_e@gmx.net>; +Cc: pgsql-docs
A Diumenge 14 Octubre 2007, Peter Eisentraut va escriure:
> Albert Cervera i Areny wrote:
> > The problem is that if we want these docs in the Reference section of
> > the documentation right after "PostgreSQL Server Applications" they
> > can't be chapters nor sections, they need to be <refentry>'s.
>
> That is not true, AFAICT. What do you base this assertion on?
You're right, that's not exactly true:
Reference is a Part. If we still want contrib inside Reference, contrib can be
a <chapter>, <reference> or other elements defined at
http://www.docbook.org/tdg5/en/html/part.html. But I cant' make the contrib
section a <part> inside reference (that means no chapter per module!).
If I make it a chapter the numbering inside Reference becomes:
"I. SQL Commands"
"II. PostgreSQL Client Applications"
"III. PostgreSQL Server Applications"
"43. Standard Modules"
Not sure if that's a problem, but that's why I'm asking. That allows, however,
having each contrib module in a section in this chapter and thus fits in one
page.
Though I agree I should concentrate on content, not style, having lots of very
small pages isn't very nice either. You can see that in the docs I have
online. In that case each module is a chapter as Tom suggests and it's a
completely new Part after "Internals"
IMHO having it in reference would make sense if contrib docs where organized
like, well... references but that's not the case for most of them. After all
you need some introduction to the module, some examples, etc.
--
Albert Cervera i Areny
http://www.NaN-tic.com
^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: Tips needed for contrib doc
2007-10-10 21:15 Tips needed for contrib doc Albert Cervera i Areny <albert@nan-tic.com>
@ 2007-10-17 19:35 ` Albert Cervera i Areny <albert@nan-tic.com>
2007-10-18 00:26 ` Re: Tips needed for contrib doc Tom Lane <tgl@sss.pgh.pa.us>
2 siblings, 1 reply; 13+ messages in thread
From: Albert Cervera i Areny @ 2007-10-17 19:35 UTC (permalink / raw)
To: pgsql-docs
Given some of the problems I exposed earlier and the fact that the
documentation of contrib modules isn't organized as a reference. I will be
adding a new chapter to the "II. The SQL Language" part probably after "Full
Text Search". This will also allow to have each module in one page as
desired.
Objections?
A Dimecres 10 Octubre 2007, Albert Cervera i Areny va escriure:
> Hi,
> I wanted to spend a week or so putting the contrib doc into shape so I
> want to start by moving the contrib part from a new appendix to the
> Reference part.
--
Albert Cervera i Areny
http://www.NaN-tic.com
^ permalink raw reply [nested|flat] 13+ messages in thread
* Re: Tips needed for contrib doc
2007-10-10 21:15 Tips needed for contrib doc Albert Cervera i Areny <albert@nan-tic.com>
2007-10-17 19:35 ` Re: Tips needed for contrib doc Albert Cervera i Areny <albert@nan-tic.com>
@ 2007-10-18 00:26 ` Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 0 replies; 13+ messages in thread
From: Tom Lane @ 2007-10-18 00:26 UTC (permalink / raw)
To: Albert Cervera i Areny <albert@nan-tic.com>; +Cc: pgsql-docs
Albert Cervera i Areny <albert@nan-tic.com> writes:
> Given some of the problems I exposed earlier and the fact that the
> documentation of contrib modules isn't organized as a reference. I will be
> adding a new chapter to the "II. The SQL Language" part probably after "Full
> Text Search". This will also allow to have each module in one page as
> desired.
> Objections?
That seems like an entirely random place for it.
If you don't want to put it under Reference, maybe a new top-level Part
(probably after Reference) would be appropriate?
regards, tom lane
^ permalink raw reply [nested|flat] 13+ messages in thread
end of thread, other threads:[~2007-10-18 00:26 UTC | newest]
Thread overview: 13+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2007-10-10 21:15 Tips needed for contrib doc Albert Cervera i Areny <albert@nan-tic.com>
2007-10-11 07:48 ` Guillaume Lelarge <guillaume@lelarge.info>
2007-10-11 14:08 ` Tom Lane <tgl@sss.pgh.pa.us>
2007-10-12 17:13 ` Albert Cervera i Areny <albert@nan-tic.com>
2007-10-12 17:47 ` Peter Eisentraut <peter_e@gmx.net>
2007-10-12 18:04 ` Albert Cervera i Areny <albert@nan-tic.com>
2007-10-14 13:05 ` Peter Eisentraut <peter_e@gmx.net>
2007-10-14 18:17 ` Albert Cervera i Areny <albert@nan-tic.com>
2007-10-14 19:05 ` Tom Lane <tgl@sss.pgh.pa.us>
2007-10-14 21:33 ` Peter Eisentraut <peter_e@gmx.net>
2007-10-14 23:48 ` Albert Cervera i Areny <albert@nan-tic.com>
2007-10-17 19:35 ` Albert Cervera i Areny <albert@nan-tic.com>
2007-10-18 00:26 ` Tom Lane <tgl@sss.pgh.pa.us>
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