Re: Doc fixes and improvements

On 28 August 2010 19:47, Thom Brown <thom@linux.com> wrote:

On 28 August 2010 15:29, Thom Brown <thom@linux.com> wrote:

I attach a patch which fixes a few layout and markup issues, and also
a bit of tidying up.  These include
- removing excessive table cells
- moving function parameters into function tags rather than having
them being considered separate
- adding return type column on XML2 contrib module functions list and
removing return types from function
- adding table header to XML2 contrib parameter table

Another minor fix attached to put text into a containing paragraph.
--

Apologies, ignore that last one.

On 28 August 2010 19:50, Thom Brown <thom@linux.com> wrote:

On 28 August 2010 19:47, Thom Brown <thom@linux.com> wrote:

On 28 August 2010 15:29, Thom Brown <thom@linux.com> wrote:

I attach a patch which fixes a few layout and markup issues, and also
a bit of tidying up.  These include
- removing excessive table cells
- moving function parameters into function tags rather than having
them being considered separate
- adding return type column on XML2 contrib module functions list and
removing return types from function
- adding table header to XML2 contrib parameter table

Another minor fix attached to put text into a containing paragraph.
--

Apologies, ignore that last one.

Okay, reattached and tested this time.

Thom Brown <thom@linux.com> writes:

On 28 August 2010 19:50, Thom Brown <thom@linux.com> wrote:

On 28 August 2010 19:47, Thom Brown <thom@linux.com> wrote:

On 28 August 2010 15:29, Thom Brown <thom@linux.com> wrote:

I attach a patch which fixes a few layout and markup issues, and also
a bit of tidying up.

Okay, reattached and tested this time.

Ummm ... this seems to be almost entirely pointless whitespace changes.
Sure you attached the right diff?

regards, tom lane

On 29 August 2010 21:31, Tom Lane <tgl@sss.pgh.pa.us> wrote:

Thom Brown <thom@linux.com> writes:

On 28 August 2010 19:50, Thom Brown <thom@linux.com> wrote:

On 28 August 2010 19:47, Thom Brown <thom@linux.com> wrote:

On 28 August 2010 15:29, Thom Brown <thom@linux.com> wrote:

I attach a patch which fixes a few layout and markup issues, and also
a bit of tidying up.

Okay, reattached and tested this time.

Ummm ... this seems to be almost entirely pointless whitespace changes.
Sure you attached the right diff?

Yes, the whitespace changes you're seeing are because I closed the
<para> tag early, then re-opened it again for the next paragraph,
which meant I reduced the indent for the content between them. The
paragraph is also closed again after, rather than containing
everything after it, so I removed the excess closing paragraph tag and
reduce the indentation of the affected sections.

This is because of what is rendered on:
http://www.postgresql.org/docs/9.0/static/functions-logical.html

The sentence "SQL uses a three-valued boolean..." isn't contained in a
paragraph at all and should be. Otherwise it's free text in a div.

--
Thom Brown
Twitter: @darkixion
IRC (freenode): dark_ixion
Registered Linux user: #516935

Thom Brown <thom@linux.com> writes:

On 29 August 2010 21:31, Tom Lane <tgl@sss.pgh.pa.us> wrote:

Ummm ... this seems to be almost entirely pointless whitespace changes.
Sure you attached the right diff?

Yes, the whitespace changes you're seeing are because I closed the
<para> tag early, then re-opened it again for the next paragraph,
which meant I reduced the indent for the content between them. The
paragraph is also closed again after, rather than containing
everything after it, so I removed the excess closing paragraph tag and
reduce the indentation of the affected sections.

This is because of what is rendered on:
http://www.postgresql.org/docs/9.0/static/functions-logical.html

The sentence "SQL uses a three-valued boolean..." isn't contained in a
paragraph at all and should be. Otherwise it's free text in a div.

Uh ... it is too enclosed in a <para>. What your changes seem to
accomplish is to take the <simplelist> and <informaltable> constructs
outside any <para>, but what is the point of that? I don't see anything
obviously wrong with the rendering on the page you cite.

regards, tom lane

On 29 August 2010 22:21, Tom Lane <tgl@sss.pgh.pa.us> wrote:

Thom Brown <thom@linux.com> writes:

On 29 August 2010 21:31, Tom Lane <tgl@sss.pgh.pa.us> wrote:

Ummm ... this seems to be almost entirely pointless whitespace changes.
Sure you attached the right diff?

Yes, the whitespace changes you're seeing are because I closed the
<para> tag early, then re-opened it again for the next paragraph,
which meant I reduced the indent for the content between them.  The
paragraph is also closed again after, rather than containing
everything after it, so I removed the excess closing paragraph tag and
reduce the indentation of the affected sections.

This is because of what is rendered on:
http://www.postgresql.org/docs/9.0/static/functions-logical.html

The sentence "SQL uses a three-valued boolean..." isn't contained in a
paragraph at all and should be.  Otherwise it's free text in a div.

Uh ... it is too enclosed in a <para>.

I'm referring to the rendered output. It isn't contained in <p> tags.

What your changes seem to
accomplish is to take the <simplelist> and <informaltable> constructs
outside any <para>, but what is the point of that?

Well, those can be in their own <para> container too, although I don't
think that's an issue.

But I shalln't pursue it further if you think there's really no issue.

--
Thom Brown
Twitter: @darkixion
IRC (freenode): dark_ixion
Registered Linux user: #516935

Thom Brown <thom@linux.com> writes:

On 29 August 2010 22:21, Tom Lane <tgl@sss.pgh.pa.us> wrote:

What your changes seem to
accomplish is to take the <simplelist> and <informaltable> constructs
outside any <para>, but what is the point of that?

Well, those can be in their own <para> container too, although I don't
think that's an issue.

But I shalln't pursue it further if you think there's really no issue.

Well, I don't know --- I'm no SGML expert, and I'm not sure whether
there's a preferred style for that. But I see in a quick grep that
every occurrence of <simplelist> in our docs, and all but a few
occurrences of <informaltable>, are within paras with some surrounding
text, in precisely the same style as here. So if this needs to be
changed then it needs to be changed in a lot of places. I'm disinclined
to mess with it unless there's a pretty concrete reason to do so.

regards, tom lane

On 29 August 2010 22:36, Tom Lane <tgl@sss.pgh.pa.us> wrote:

Thom Brown <thom@linux.com> writes:

On 29 August 2010 22:21, Tom Lane <tgl@sss.pgh.pa.us> wrote:

What your changes seem to
accomplish is to take the <simplelist> and <informaltable> constructs
outside any <para>, but what is the point of that?

Well, those can be in their own <para> container too, although I don't
think that's an issue.

But I shalln't pursue it further if you think there's really no issue.

Well, I don't know --- I'm no SGML expert, and I'm not sure whether
there's a preferred style for that.  But I see in a quick grep that
every occurrence of <simplelist> in our docs, and all but a few
occurrences of <informaltable>, are within paras with some surrounding
text, in precisely the same style as here.  So if this needs to be
changed then it needs to be changed in a lot of places.  I'm disinclined
to mess with it unless there's a pretty concrete reason to do so.

Any opinion on the first patch I provided at the beginning of this thread?

--
Thom Brown
Twitter: @darkixion
IRC (freenode): dark_ixion
Registered Linux user: #516935

On 30 August 2010 14:41, Thom Brown <thom@linux.com> wrote:

Any opinion on the first patch I provided at the beginning of this thread?

It appears that first email never made it through. Since it may be
because of the size of the patch, I reattach it but gzipped. Here's
the original message too:

I attach a patch which fixes a few layout and markup issues, and also
a bit of tidying up. These include
- removing excessive table cells
- moving function parameters into function tags rather than having
them being considered separate
- adding return type column on XML2 contrib module functions list and
removing return types from function
- adding table header to XML2 contrib parameter table

--
Thom Brown
Twitter: @darkixion
IRC (freenode): dark_ixion
Registered Linux user: #516935

Patch applied and backpatched to 9.0.X. Thanks.

---------------------------------------------------------------------------

Thom Brown wrote:

On 30 August 2010 14:41, Thom Brown <thom@linux.com> wrote:

Any opinion on the first patch I provided at the beginning of this thread?

It appears that first email never made it through. Since it may be
because of the size of the patch, I reattach it but gzipped. Here's
the original message too:

I attach a patch which fixes a few layout and markup issues, and also
a bit of tidying up. These include
- removing excessive table cells
- moving function parameters into function tags rather than having
them being considered separate
- adding return type column on XML2 contrib module functions list and
removing return types from function
- adding table header to XML2 contrib parameter table

--
Thom Brown
Twitter: @darkixion
IRC (freenode): dark_ixion
Registered Linux user: #516935

[ Attachment, skipping... ]

--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ It's impossible for everything to be true. +

On 9 September 2010 01:48, Bruce Momjian <bruce@momjian.us> wrote:

Patch applied and backpatched to 9.0.X.  Thanks.

Whoa, no comments or objections then? I'm scared now. :S

Thanks Bruce :)

--
Thom Brown
Twitter: @darkixion
IRC (freenode): dark_ixion
Registered Linux user: #516935

Thom Brown wrote:

On 9 September 2010 01:48, Bruce Momjian <bruce@momjian.us> wrote:

Patch applied and backpatched to 9.0.X. ?Thanks.

Whoa, no comments or objections then? I'm scared now. :S

Well, you are improving an area that is long overdue for improvement, so
we give you a wide berth. ;-)

Also, if you need any javascript stuff done, just let me know.

Also, we are planning to release Postgres 9.0 on September 20, and it
would be great to have something in place by then to showcase our doc
improvements, in both content and appearance. Is there any schedule for
completion?

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ It's impossible for everything to be true. +

On 10 September 2010 14:36, Bruce Momjian <bruce@momjian.us> wrote:

Thom Brown wrote:

On 9 September 2010 01:48, Bruce Momjian <bruce@momjian.us> wrote:

Patch applied and backpatched to 9.0.X. ?Thanks.

Whoa, no comments or objections then?  I'm scared now. :S

Well, you are improving an area that is long overdue for improvement, so
we give you a wide berth.  ;-)

Also, if you need any javascript stuff done, just let me know.

Also, we are planning to release Postgres 9.0 on September 20, and it
would be great to have something in place by then to showcase our doc
improvements, in both content and appearance.  Is there any schedule for
completion?

Well it's mostly done now. I need to do some more testing and
hopefully others can try it out on weird browsers too because I can
only do so much testing myself.

--
Thom Brown
Twitter: @darkixion
IRC (freenode): dark_ixion
Registered Linux user: #516935

On 10 September 2010 14:39, Thom Brown <thom@linux.com> wrote:

On 10 September 2010 14:36, Bruce Momjian <bruce@momjian.us> wrote:

Thom Brown wrote:

On 9 September 2010 01:48, Bruce Momjian <bruce@momjian.us> wrote:

Patch applied and backpatched to 9.0.X. ?Thanks.

Whoa, no comments or objections then?  I'm scared now. :S

Well, you are improving an area that is long overdue for improvement, so
we give you a wide berth.  ;-)

Also, if you need any javascript stuff done, just let me know.

Also, we are planning to release Postgres 9.0 on September 20, and it
would be great to have something in place by then to showcase our doc
improvements, in both content and appearance.  Is there any schedule for
completion?

Well it's mostly done now.  I need to do some more testing and
hopefully others can try it out on weird browsers too because I can
only do so much testing myself.

Actually, that wasn't entirely true. I have to re-adapt it for the
current site as my changes were for the new version of the site which
we're not using yet. I think it's just a case of changing one line
from last I checked. Not sure where to take that though as I don't
have a working copy of the current site.

--
Thom Brown
Twitter: @darkixion
IRC (freenode): dark_ixion
Registered Linux user: #516935

On Fri, Sep 10, 2010 at 15:43, Thom Brown <thom@linux.com> wrote:

On 10 September 2010 14:39, Thom Brown <thom@linux.com> wrote:

On 10 September 2010 14:36, Bruce Momjian <bruce@momjian.us> wrote:

Thom Brown wrote:

On 9 September 2010 01:48, Bruce Momjian <bruce@momjian.us> wrote:

Patch applied and backpatched to 9.0.X. ?Thanks.

Whoa, no comments or objections then?  I'm scared now. :S

Well, you are improving an area that is long overdue for improvement, so
we give you a wide berth.  ;-)

Also, if you need any javascript stuff done, just let me know.

Also, we are planning to release Postgres 9.0 on September 20, and it
would be great to have something in place by then to showcase our doc
improvements, in both content and appearance.  Is there any schedule for
completion?

Well it's mostly done now.  I need to do some more testing and
hopefully others can try it out on weird browsers too because I can
only do so much testing myself.

Actually, that wasn't entirely true.  I have to re-adapt it for the
current site as my changes were for the new version of the site which
we're not using yet.  I think it's just a case of changing one line
from last I checked.  Not sure where to take that though as I don't
have a working copy of the current site.

Find me on IRC sometime and we can work that out - especially if you
can get to the point of having a patch ready to debug :-)

--
 Magnus Hagander
 Me: http://www.hagander.net/
 Work: http://www.redpill-linpro.com/

Excerpts from Thom Brown's message of vie sep 10 09:39:50 -0400 2010:

Well it's mostly done now. I need to do some more testing and
hopefully others can try it out on weird browsers too because I can
only do so much testing myself.

Is this going to be incorporated into the main stylesheet.css that's
used in the tarball docs, or is it only for the website?

--
Álvaro Herrera <alvherre@commandprompt.com>
The PostgreSQL Company - Command Prompt, Inc.
PostgreSQL Replication, Consulting, Custom Development, 24x7 support

On 10 September 2010 16:26, Alvaro Herrera <alvherre@commandprompt.com> wrote:

Excerpts from Thom Brown's message of vie sep 10 09:39:50 -0400 2010:

Well it's mostly done now.  I need to do some more testing and
hopefully others can try it out on weird browsers too because I can
only do so much testing myself.

Is this going to be incorporated into the main stylesheet.css that's
used in the tarball docs, or is it only for the website?

I don't know. I haven't ever looked at the version provided in the
tarball. Does it currently appear like the live site's documentation
when viewing it?

--
Thom Brown
Twitter: @darkixion
IRC (freenode): dark_ixion
Registered Linux user: #516935

On Fri, Sep 10, 2010 at 15:48, Magnus Hagander <magnus@hagander.net> wrote:

On Fri, Sep 10, 2010 at 15:43, Thom Brown <thom@linux.com> wrote:

On 10 September 2010 14:39, Thom Brown <thom@linux.com> wrote:

On 10 September 2010 14:36, Bruce Momjian <bruce@momjian.us> wrote:

Thom Brown wrote:

On 9 September 2010 01:48, Bruce Momjian <bruce@momjian.us> wrote:

Patch applied and backpatched to 9.0.X. ?Thanks.

Whoa, no comments or objections then?  I'm scared now. :S

Well, you are improving an area that is long overdue for improvement, so
we give you a wide berth.  ;-)

Also, if you need any javascript stuff done, just let me know.

Also, we are planning to release Postgres 9.0 on September 20, and it
would be great to have something in place by then to showcase our doc
improvements, in both content and appearance.  Is there any schedule for
completion?

Well it's mostly done now.  I need to do some more testing and
hopefully others can try it out on weird browsers too because I can
only do so much testing myself.

Actually, that wasn't entirely true.  I have to re-adapt it for the
current site as my changes were for the new version of the site which
we're not using yet.  I think it's just a case of changing one line
from last I checked.  Not sure where to take that though as I don't
have a working copy of the current site.

Find me on IRC sometime and we can work that out - especially if you
can get to the point of having a patch ready to debug :-)

Ok, Thom has merged these changes onto the current website code, and
I've put it up on http://magnus.webdev.postgresql.org - note that you
need to go back to 8.3 to actually see anything, because the db
doesn't have the latest docs.

It'd be good to get some more testing on that one to make sure it
doean't break things - in particular, someone to test IE and Safari.
It should work, but better safe than sorry...

--
 Magnus Hagander
 Me: http://www.hagander.net/
 Work: http://www.redpill-linpro.com/

Excerpts from Magnus Hagander's message of vie sep 10 15:20:41 -0400 2010:

Ok, Thom has merged these changes onto the current website code, and
I've put it up on http://magnus.webdev.postgresql.org - note that you
need to go back to 8.3 to actually see anything, because the db
doesn't have the latest docs.

It'd be good to get some more testing on that one to make sure it
doean't break things - in particular, someone to test IE and Safari.
It should work, but better safe than sorry...

Just gave it a try on IE6 on Linux here, and it looks OK. No rounded
corners and no shadows, but nothing's out of place either.

--
Álvaro Herrera <alvherre@commandprompt.com>
The PostgreSQL Company - Command Prompt, Inc.
PostgreSQL Replication, Consulting, Custom Development, 24x7 support