Thread: Re: Doc fixes and improvements
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. -- Thom Brown Twitter: @darkixion IRC (freenode): dark_ixion Registered Linux user: #516935
Attachment
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.
Attachment
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
Attachment
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