Thread: Re: [HACKERS] timestamptz alias

Moving to -docs

On Tue, Oct 03, 2006 at 12:13:46PM -0400, Andrew Dunstan wrote:
> Tom Lane wrote:
> >Markus Schaber <schabi@logix-tt.com> writes:
> >
> >>Here's a small patch that adds an appropriate explanation.
> >>
> >
> >If we're going to document these aliases, what of float4, float8, and bool?
> >Also, although the docs mention int2/int4/int8, it's more or less left
> >to the reader's imagination to deduce what they are.
> >
> >Perhaps it'd be better to provide a small table of recognized type
> >aliases, rather than inserting equivalent notes into three or four places.
> >
> >
>
>
> you mean like the table here?
> http://momjian.us/main/writings/pgsql/sgml/datatype.html

An issue I've seen with the docs is that for chapters that have a lot of
sections (such as 8), the section list at the start of each chapter
fills the screen, so it's easy to miss the fact that there's more info
beneath the list (which is wy presumably most folks never knew that
table existed).

I think the ideal way to handle this would be to put the table of
contents in a side-bar and flow the text around it. But that could be a
real bear to do in docbook/sgml, so perhaps it would be better to just
force the TOC for each chapter onto it's own page (and ensure the
overview/introduction text shows up in the TOC).
--
Jim Nasby                                            jim@nasby.net
EnterpriseDB      http://enterprisedb.com      512.569.9461 (cell)

Jim C. Nasby wrote:
> On Tue, Oct 03, 2006 at 12:13:46PM -0400, Andrew Dunstan wrote:
>
>>>
>>> Perhaps it'd be better to provide a small table of recognized type
>>> aliases, rather than inserting equivalent notes into three or four places.
>>>
>>>
>>>
>> you mean like the table here?
>> http://momjian.us/main/writings/pgsql/sgml/datatype.html
>>
>
> An issue I've seen with the docs is that for chapters that have a lot of
> sections (such as 8), the section list at the start of each chapter
> fills the screen, so it's easy to miss the fact that there's more info
> beneath the list (which is wy presumably most folks never knew that
> table existed).
>
> I think the ideal way to handle this would be to put the table of
> contents in a side-bar and flow the text around it. But that could be a
> real bear to do in docbook/sgml, so perhaps it would be better to just
> force the TOC for each chapter onto it's own page (and ensure the
> overview/introduction text shows up in the TOC).
>

I would like a frame driven version of the docs (c.f. doxygen, javadoc,
etc.). The we would not need contents links at the top of each chapter
like this. Navigating the HTML docs is less than pleasant.
Unfortunately, I don't have enough time or docbook-fu to be able to do this.

cheers

andrew

Jim C. Nasby wrote:
> I think the ideal way to handle this would be to put the table of
> contents in a side-bar and flow the text around it.

It's all CSS, so this should be doable.

--
Peter Eisentraut
http://developer.postgresql.org/~petere/

Hi, Jim,

Jim C. Nasby wrote:

> An issue I've seen with the docs is that for chapters that have a lot of
> sections (such as 8), the section list at the start of each chapter
> fills the screen, so it's easy to miss the fact that there's more info
> beneath the list (which is wy presumably most folks never knew that
> table existed).
>
> I think the ideal way to handle this would be to put the table of
> contents in a side-bar and flow the text around it. But that could be a
> real bear to do in docbook/sgml, so perhaps it would be better to just
> force the TOC for each chapter onto it's own page (and ensure the
> overview/introduction text shows up in the TOC).

I agree.

The fact that the TOC and the first part of the Chapter are on the same
page has annoyed me several times now. :-)


Regards,
Markus

--
Markus Schaber | Logical Tracking&Tracing International AG
Dipl. Inf.     | Software Development GIS

Fight against software patents in Europe! www.ffii.org
www.nosoftwarepatents.org

> I would like a frame driven version of the docs (c.f.
> doxygen, javadoc, etc.). The we would not need contents links
> at the top of each chapter like this. Navigating the HTML
> docs is less than pleasant.
> Unfortunately, I don't have enough time or docbook-fu to be
> able to do this.

Yuck. Frames. Ickk. All the issues with bookmarking and searching and
things like that.

Anyway. If done, make sure the current version doesn't go away, but make
the frames version just an option instead.


//Magnus

Magnus Hagander wrote:
>> I would like a frame driven version of the docs (c.f.
>> doxygen, javadoc, etc.). The we would not need contents links
>> at the top of each chapter like this. Navigating the HTML
>> docs is less than pleasant.
>> Unfortunately, I don't have enough time or docbook-fu to be
>> able to do this.
>>
>
> Yuck. Frames. Ickk. All the issues with bookmarking and searching and
> things like that.
>
> Anyway. If done, make sure the current version doesn't go away, but make
> the frames version just an option instead.
>
>
>

Then use a tiled mechanism instead if you want to avoid frames. Or if
you want to be get more advanced some sort of Ajax solution. But we need
some sort of nav bar that you can drill down on. Navigation now is just
horrible, IMNSHO.

cheers

andrew