Example indenting
I noticed that while the development docs indent examples (for example
http://developer.postgresql.org/pgdocs/postgres/sql-explain.html), the
main docs don't
(http://www.postgresql.org/docs/9.0/static/sql-explain.html).
As you can see, the same page on the main docs doesn't scan well, and
all the examples and paragraphs merge into a tangled mess.
Could someone update the main docs so it outputs a similar style to
the dev docs? This will probably require changes to the actual docs
to separate examples from other sections which share the same markup.
Thanks
--
Thom Brown
Registered Linux user: #516935
Thom Brown <thom@linux.com> writes:
I noticed that while the development docs indent examples (for example
http://developer.postgresql.org/pgdocs/postgres/sql-explain.html), the
main docs don't
(http://www.postgresql.org/docs/9.0/static/sql-explain.html).
I believe this isn't so much a function of the docs themselves as the
webpage template they're being stuffed into on the latter site.
Probably pgsql-www is the place to complain about it.
As you can see, the same page on the main docs doesn't scan well, and
all the examples and paragraphs merge into a tangled mess.
Hm, both pages render acceptably for me in Safari --- it's true that the
examples aren't inset relative to the text on the main-docs site, but
I don't see anything "messed up" beyond that. What browser are you
using? Could you post a screenshot of what you see?
regards, tom lane
On mån, 2010-08-23 at 13:56 +0100, Thom Brown wrote:
Could someone update the main docs so it outputs a similar style to
the dev docs? This will probably require changes to the actual docs
to separate examples from other sections which share the same markup.
I suspect that the docs on the web site don't use the CSS stylesheet
that comes with the docs.
Thom Brown <thom@linux.com> writes:
On 23 August 2010 14:43, Tom Lane <tgl@sss.pgh.pa.us> wrote:
Hm, both pages render acceptably for me in Safari --- it's true that the
examples aren't inset relative to the text on the main-docs site, but
I don't see anything "messed up" beyond that. �What browser are you
using? �Could you post a screenshot of what you see?
By "mess" I mean examples aren't sufficiently distinct from paragraph
text. There's nothing actually malformed. It's more of a styling
issue from my perspective.
Ah, I see. It looks like you are using a monospaced font that is
visually very similar to your regular text font, and so with neither
a font difference or insetting, there's indeed not a lot to distinguish
example from text. On my display the two fonts are a bit more visually
distinct so it's more readable. (Checks preferences ... I've got Safari
set to Times 16 for "standard font" and Courier 13 for "fixed-width
font", though I'm not sure whether the PG docs pages make use of those
selections.)
Anyway, that was a red herring, and the question remains why the
examples are rendered without insetting on the main docs pages.
Was that intentional? I can see that it might be because the text
is already inset from the window edge more than it is on the devel site,
and so insetting the examples even more might result in page width
problems. Maybe the problem is not so much that we want to indent the
examples more as that the text needs to be indented less.
regards, tom lane
Import Notes
Reply to msg id not found: AANLkTin27ZKYu2tdqn5RZvTaCtuX11=sd_pj7tzoTJiY@mail.gmail.com
On Mon, Aug 23, 2010 at 16:33, Tom Lane <tgl@sss.pgh.pa.us> wrote:
Thom Brown <thom@linux.com> writes:
On 23 August 2010 14:43, Tom Lane <tgl@sss.pgh.pa.us> wrote:
Hm, both pages render acceptably for me in Safari --- it's true that the
examples aren't inset relative to the text on the main-docs site, but
I don't see anything "messed up" beyond that. What browser are you
using? Could you post a screenshot of what you see?By "mess" I mean examples aren't sufficiently distinct from paragraph
text. There's nothing actually malformed. It's more of a styling
issue from my perspective.Ah, I see. It looks like you are using a monospaced font that is
visually very similar to your regular text font, and so with neither
a font difference or insetting, there's indeed not a lot to distinguish
example from text. On my display the two fonts are a bit more visually
distinct so it's more readable. (Checks preferences ... I've got Safari
set to Times 16 for "standard font" and Courier 13 for "fixed-width
font", though I'm not sure whether the PG docs pages make use of those
selections.)Anyway, that was a red herring, and the question remains why the
examples are rendered without insetting on the main docs pages.
Was that intentional? I can see that it might be because the text
is already inset from the window edge more than it is on the devel site,
and so insetting the examples even more might result in page width
problems. Maybe the problem is not so much that we want to indent the
examples more as that the text needs to be indented less.
Not having dug into any details, but it seems that example is tagged
with CSS class PROGRAMLISTING - which isn't included anywhere in the
main site CSS. Whereas on the developer site, tehre is a rule for it
that gives margin-left: 4ex. Probably worth experimenting with that
one.
--
Magnus Hagander
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/
On 23 August 2010 15:37, Magnus Hagander <magnus@hagander.net> wrote:
On Mon, Aug 23, 2010 at 16:33, Tom Lane <tgl@sss.pgh.pa.us> wrote:
Thom Brown <thom@linux.com> writes:
On 23 August 2010 14:43, Tom Lane <tgl@sss.pgh.pa.us> wrote:
Hm, both pages render acceptably for me in Safari --- it's true that the
examples aren't inset relative to the text on the main-docs site, but
I don't see anything "messed up" beyond that. What browser are you
using? Could you post a screenshot of what you see?By "mess" I mean examples aren't sufficiently distinct from paragraph
text. There's nothing actually malformed. It's more of a styling
issue from my perspective.Ah, I see. It looks like you are using a monospaced font that is
visually very similar to your regular text font, and so with neither
a font difference or insetting, there's indeed not a lot to distinguish
example from text. On my display the two fonts are a bit more visually
distinct so it's more readable. (Checks preferences ... I've got Safari
set to Times 16 for "standard font" and Courier 13 for "fixed-width
font", though I'm not sure whether the PG docs pages make use of those
selections.)Anyway, that was a red herring, and the question remains why the
examples are rendered without insetting on the main docs pages.
Was that intentional? I can see that it might be because the text
is already inset from the window edge more than it is on the devel site,
and so insetting the examples even more might result in page width
problems. Maybe the problem is not so much that we want to indent the
examples more as that the text needs to be indented less.Not having dug into any details, but it seems that example is tagged
with CSS class PROGRAMLISTING - which isn't included anywhere in the
main site CSS. Whereas on the developer site, tehre is a rule for it
that gives margin-left: 4ex. Probably worth experimenting with that
one.
Yes the following style is present in the dev docs, but not the www docs:
pre.LITERALLAYOUT,
.SCREEN,
.SYNOPSIS,
.PROGRAMLISTING
{
margin-left:4ex;
}
So as Peter said, the stylesheet in use isn't the same as the dev
version. Importing that one style into the www docs, it looks fine.
--
Thom Brown
Registered Linux user: #516935
On 24 August 2010 15:44, Thom Brown <thom@linux.com> wrote:
On 24 August 2010 09:35, Thom Brown <thom@linux.com> wrote:
On 23 August 2010 16:09, Thom Brown <thom@linux.com> wrote:
On 23 August 2010 15:37, Magnus Hagander <magnus@hagander.net> wrote:
On Mon, Aug 23, 2010 at 16:33, Tom Lane <tgl@sss.pgh.pa.us> wrote:
Thom Brown <thom@linux.com> writes:
On 23 August 2010 14:43, Tom Lane <tgl@sss.pgh.pa.us> wrote:
Hm, both pages render acceptably for me in Safari --- it's true that the
examples aren't inset relative to the text on the main-docs site, but
I don't see anything "messed up" beyond that. What browser are you
using? Could you post a screenshot of what you see?By "mess" I mean examples aren't sufficiently distinct from paragraph
text. There's nothing actually malformed. It's more of a styling
issue from my perspective.Ah, I see. It looks like you are using a monospaced font that is
visually very similar to your regular text font, and so with neither
a font difference or insetting, there's indeed not a lot to distinguish
example from text. On my display the two fonts are a bit more visually
distinct so it's more readable. (Checks preferences ... I've got Safari
set to Times 16 for "standard font" and Courier 13 for "fixed-width
font", though I'm not sure whether the PG docs pages make use of those
selections.)Anyway, that was a red herring, and the question remains why the
examples are rendered without insetting on the main docs pages.
Was that intentional? I can see that it might be because the text
is already inset from the window edge more than it is on the devel site,
and so insetting the examples even more might result in page width
problems. Maybe the problem is not so much that we want to indent the
examples more as that the text needs to be indented less.Not having dug into any details, but it seems that example is tagged
with CSS class PROGRAMLISTING - which isn't included anywhere in the
main site CSS. Whereas on the developer site, tehre is a rule for it
that gives margin-left: 4ex. Probably worth experimenting with that
one.Yes the following style is present in the dev docs, but not the www docs:
pre.LITERALLAYOUT,
.SCREEN,
.SYNOPSIS,
.PROGRAMLISTING
{
margin-left:4ex;
}So as Peter said, the stylesheet in use isn't the same as the dev
version. Importing that one style into the www docs, it looks fine.Just as a quick test, I also tried out applying a style which clearly
defines these sections. I attach an example of how this transforms
the page (and how it looks without any style changes). Just an idea.The style applied here is:
pre.LITERALLAYOUT,
.SCREEN,
.SYNOPSIS,
.PROGRAMLISTING
{
margin: 0 4ex;
padding: 2ex 4ex;
border-left: 4px solid #008EBD;
background-color: #E0ECEF;
}And this is possibly overkill, but the following CSS results in the
attached screenshot:pre.LITERALLAYOUT,
.SCREEN,
.SYNOPSIS,
.PROGRAMLISTING
{
margin: 0 4ex;
padding: 2ex 4ex;
}pre.LITERALLAYOUT,
.SCREEN
{
border-left: 4px solid #DFA60D;
background-color: #FFFCDF;}
pre.SYNOPSIS
{
border-left: 4px solid #AFAFAF;
background-color: #EFEFEF;
}pre.PROGRAMLISTING
{
border-left: 4px solid #008EBD;
background-color: #E0ECEF;
}It makes a visual distinction between examples, definitions and actual
terminal output.
And another prototype:
http://www.flickr.com/photos/dark_ixion/4927669444/sizes/o/
(not attached because the messages don't come through otherwise)
..(and this time really without the attachment)
--
Thom Brown
Registered Linux user: #516935
Import Notes
Reply to msg id not found: AANLkTi=O_JCQitEiv294QJZHPV58L7H57uKZTP5FF2RL@mail.gmail.com
Thom Brown <thom@linux.com> wrote:
And another prototype:
http://www.flickr.com/photos/dark_ixion/4927669444/sizes/o/
Wow! That looks *really* slick!
That is much more readable than what I'm used to seeing!
-Kevin
On Wed, 2010-08-25 at 17:51 -0500, Kevin Grittner wrote:
Thom Brown <thom@linux.com> wrote:
And another prototype:
http://www.flickr.com/photos/dark_ixion/4927669444/sizes/o/Wow! That looks *really* slick!
That is much more readable than what I'm used to seeing!
Wait, what? Were going to have documentation that is representative of
someone who has designed a web page circa 2005? WOOT!
Seriously, +1. Very nice work.
Joshua D. Drake
-Kevin
--
PostgreSQL.org Major Contributor
Command Prompt, Inc: http://www.commandprompt.com/ - 509.416.6579
Consulting, Training, Support, Custom Development, Engineering
http://twitter.com/cmdpromptinc | http://identi.ca/commandprompt
Le 26/08/2010 01:29, Joshua D. Drake a écrit :
On Wed, 2010-08-25 at 17:51 -0500, Kevin Grittner wrote:
Thom Brown <thom@linux.com> wrote:
And another prototype:
http://www.flickr.com/photos/dark_ixion/4927669444/sizes/o/Wow! That looks *really* slick!
That is much more readable than what I'm used to seeing!
Wait, what? Were going to have documentation that is representative of
someone who has designed a web page circa 2005? WOOT!Seriously, +1. Very nice work.
Yeah, quite impressive. Would love to know how Thom did that. And if I
can borrow it for the french translation of the manual :)
--
Guillaume
http://www.postgresql.fr
http://dalibo.com
On 26 August 2010 06:52, Guillaume Lelarge <guillaume@lelarge.info> wrote:
Le 26/08/2010 01:29, Joshua D. Drake a écrit :
On Wed, 2010-08-25 at 17:51 -0500, Kevin Grittner wrote:
Thom Brown <thom@linux.com> wrote:
And another prototype:
http://www.flickr.com/photos/dark_ixion/4927669444/sizes/o/Wow! That looks *really* slick!
That is much more readable than what I'm used to seeing!
Wait, what? Were going to have documentation that is representative of
someone who has designed a web page circa 2005? WOOT!Seriously, +1. Very nice work.
Yeah, quite impressive. Would love to know how Thom did that. And if I
can borrow it for the french translation of the manual :)
Thanks, although I'm worried it's a bit too distracting. I got a bit
carried away as originally it was only to make the documentation more
readable, so if these changes make it less functional, it doesn't
really matter if it looks good or not. It also happens to show up
mistakes in the documentation markup on some pages, so if any similar
sort of cosmetic changes were to take place, they may have to come
after fixes to the SGML.
But I've left the CSS additions in a comment on the Flickr page:
http://www.flickr.com/photos/dark_ixion/4927669444/
Just looked at the French documentation for the first time and it
shocked at how similar my changes are. :O I wasn't aware the French
docs looked any different to the English ones.
--
Thom Brown
Registered Linux user: #516935
On Thu, Aug 26, 2010 at 09:03, Thom Brown <thom@linux.com> wrote:
On 26 August 2010 06:52, Guillaume Lelarge <guillaume@lelarge.info> wrote:
Le 26/08/2010 01:29, Joshua D. Drake a écrit :
On Wed, 2010-08-25 at 17:51 -0500, Kevin Grittner wrote:
Thom Brown <thom@linux.com> wrote:
And another prototype:
http://www.flickr.com/photos/dark_ixion/4927669444/sizes/o/Wow! That looks *really* slick!
That is much more readable than what I'm used to seeing!
Wait, what? Were going to have documentation that is representative of
someone who has designed a web page circa 2005? WOOT!Seriously, +1. Very nice work.
Yeah, quite impressive. Would love to know how Thom did that. And if I
can borrow it for the french translation of the manual :)Thanks, although I'm worried it's a bit too distracting. I got a bit
carried away as originally it was only to make the documentation more
readable, so if these changes make it less functional, it doesn't
really matter if it looks good or not. It also happens to show up
mistakes in the documentation markup on some pages, so if any similar
sort of cosmetic changes were to take place, they may have to come
after fixes to the SGML.But I've left the CSS additions in a comment on the Flickr page:
http://www.flickr.com/photos/dark_ixion/4927669444/Just looked at the French documentation for the first time and it
shocked at how similar my changes are. :O I wasn't aware the French
docs looked any different to the English ones.
Thanks, Thom, this is great work.
And just FYI to everybody else, I've tried Thom into the task of
structuring our CSS a bit more, so that we can apply this without risk
;)
Thom - there you go, now it's public, there's no backing down now :P
--
Magnus Hagander
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/
On 26 August 2010 13:11, Magnus Hagander <magnus@hagander.net> wrote:
On Thu, Aug 26, 2010 at 09:03, Thom Brown <thom@linux.com> wrote:
On 26 August 2010 06:52, Guillaume Lelarge <guillaume@lelarge.info> wrote:
Le 26/08/2010 01:29, Joshua D. Drake a écrit :
On Wed, 2010-08-25 at 17:51 -0500, Kevin Grittner wrote:
Thom Brown <thom@linux.com> wrote:
And another prototype:
http://www.flickr.com/photos/dark_ixion/4927669444/sizes/o/Wow! That looks *really* slick!
That is much more readable than what I'm used to seeing!
Wait, what? Were going to have documentation that is representative of
someone who has designed a web page circa 2005? WOOT!Seriously, +1. Very nice work.
Yeah, quite impressive. Would love to know how Thom did that. And if I
can borrow it for the french translation of the manual :)Thanks, although I'm worried it's a bit too distracting. I got a bit
carried away as originally it was only to make the documentation more
readable, so if these changes make it less functional, it doesn't
really matter if it looks good or not. It also happens to show up
mistakes in the documentation markup on some pages, so if any similar
sort of cosmetic changes were to take place, they may have to come
after fixes to the SGML.But I've left the CSS additions in a comment on the Flickr page:
http://www.flickr.com/photos/dark_ixion/4927669444/Just looked at the French documentation for the first time and it
shocked at how similar my changes are. :O I wasn't aware the French
docs looked any different to the English ones.Thanks, Thom, this is great work.
And just FYI to everybody else, I've tried Thom into the task of
structuring our CSS a bit more, so that we can apply this without risk
;)Thom - there you go, now it's public, there's no backing down now :P
Looks like the webkit rendering engine can't deal with rounded corners
neatly where the borders are different widths so got rid of the
left-hand border-width.
Did a little bit more today:
http://www.flickr.com/photos/dark_ixion/4929208375/sizes/o/
And I get to play with stuff on Github which I'm new to :)
--
Thom Brown
Twitter: @darkixion
IRC (freenode): dark_ixion
Registered Linux user: #516935
On Thu, 2010-08-26 at 17:28 +0100, Thom Brown wrote:
Looks like the webkit rendering engine can't deal with rounded corners
neatly where the borders are different widths so got rid of the
left-hand border-width.
did you use --webkit-border-radius
Did a little bit more today:
http://www.flickr.com/photos/dark_ixion/4929208375/sizes/o/And I get to play with stuff on Github which I'm new to :)
--
PostgreSQL.org Major Contributor
Command Prompt, Inc: http://www.commandprompt.com/ - 509.416.6579
Consulting, Training, Support, Custom Development, Engineering
http://twitter.com/cmdpromptinc | http://identi.ca/commandprompt
On Thu, 2010-08-26 at 08:03 +0100, Thom Brown wrote:
Yeah, quite impressive. Would love to know how Thom did that. And if I
can borrow it for the french translation of the manual :)Thanks, although I'm worried it's a bit too distracting. I got a bit
carried away as originally it was only to make the documentation more
readable, so if these changes make it less functional, it doesn't
really matter if it looks good or not.
I would consider two things since we are talking documentation.
1. Drop the shadow
2. Keep the sizes consistent on the borders (notably the left side)
It is great for it to be aesthetically pleasing but if we have those
minor inconsistencies I think it would be distracting from the
information itself.
Otherwise, I think it is a bang up job.
Sincerely,
Joshua D. Drake
--
PostgreSQL.org Major Contributor
Command Prompt, Inc: http://www.commandprompt.com/ - 509.416.6579
Consulting, Training, Support, Custom Development, Engineering
http://twitter.com/cmdpromptinc | http://identi.ca/commandprompt
On 26 August 2010 18:03, Joshua D. Drake <jd@commandprompt.com> wrote:
On Thu, 2010-08-26 at 08:03 +0100, Thom Brown wrote:
Yeah, quite impressive. Would love to know how Thom did that. And if I
can borrow it for the french translation of the manual :)Thanks, although I'm worried it's a bit too distracting. I got a bit
carried away as originally it was only to make the documentation more
readable, so if these changes make it less functional, it doesn't
really matter if it looks good or not.I would consider two things since we are talking documentation.
1. Drop the shadow
Okay.
2. Keep the sizes consistent on the borders (notably the left side)
All borders in the updated image are identical.
It is great for it to be aesthetically pleasing but if we have those
minor inconsistencies I think it would be distracting from the
information itself.
Agreed, and it's sort of experimental at the moment. If it doesn't
help present information better, it's useless really.
--
Thom Brown
Twitter: @darkixion
IRC (freenode): dark_ixion
Registered Linux user: #516935
On 26 August 2010 18:00, Joshua D. Drake <jd@commandprompt.com> wrote:
On Thu, 2010-08-26 at 17:28 +0100, Thom Brown wrote:
Looks like the webkit rendering engine can't deal with rounded corners
neatly where the borders are different widths so got rid of the
left-hand border-width.did you use --webkit-border-radius
Yes, although that's not the issue. It's where the width of two
perpendicular borders differ, the corner goes a bit weird in webkit
engines, so I just dropped the varying widths.
--
Thom Brown
Twitter: @darkixion
IRC (freenode): dark_ixion
Registered Linux user: #516935
Thom Brown <thom@linux.com> wrote:
Joshua D. Drake <jd@commandprompt.com> wrote:
It is great for it to be aesthetically pleasing but if we have
those minor inconsistencies I think it would be distracting from
the information itself.Agreed, and it's sort of experimental at the moment. If it
doesn't help present information better, it's useless really.
I know this sort of thing gets pretty subjective, but having gone
back and looked at it a couple times...
(1) I don't find the shadows distracting, but I can see where that
could be a factor for some -- if it distracts anybody, I won't miss
them too much.
(2) The one thing I *do* find distracting is the wide separation in
the colors used for the different boxes (grey, yellow, blue, red).
I like the warning to stand out with red, but if the others were
somewhat more subtle differences, I think it would be less jarring
and distracting. You know, enough that you can tell the difference
if you're looking for it, and enough to register subliminally, but
not enough to slap you upside the head.
Hmmm... Does that qualify as bikeshedding?
-Kevin
On 26 August 2010 18:23, Kevin Grittner <Kevin.Grittner@wicourts.gov> wrote:
Thom Brown <thom@linux.com> wrote:
Joshua D. Drake <jd@commandprompt.com> wrote:
It is great for it to be aesthetically pleasing but if we have
those minor inconsistencies I think it would be distracting from
the information itself.Agreed, and it's sort of experimental at the moment. If it
doesn't help present information better, it's useless really.I know this sort of thing gets pretty subjective, but having gone
back and looked at it a couple times...(1) I don't find the shadows distracting, but I can see where that
could be a factor for some -- if it distracts anybody, I won't miss
them too much.(2) The one thing I *do* find distracting is the wide separation in
the colors used for the different boxes (grey, yellow, blue, red).
I like the warning to stand out with red, but if the others were
somewhat more subtle differences, I think it would be less jarring
and distracting. You know, enough that you can tell the difference
if you're looking for it, and enough to register subliminally, but
not enough to slap you upside the head.
I agree with this too and I'll work on making sure things look more
consistent. I'll just have to think about how to make the differences
clear without random splashes of colour on the page.
--
Thom Brown
Twitter: @darkixion
IRC (freenode): dark_ixion
Registered Linux user: #516935
Thom Brown wrote:
Thom - there you go, now it's public, there's no backing down now :P
Looks like the webkit rendering engine can't deal with rounded corners
neatly where the borders are different widths so got rid of the
left-hand border-width.Did a little bit more today:
http://www.flickr.com/photos/dark_ixion/4929208375/sizes/o/And I get to play with stuff on Github which I'm new to :)
That really pumps up the appearance of our docs!
--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com
+ It's impossible for everything to be true. +
