Skip site navigation (1) Skip section navigation (2)

Re: [DOCS] Example indenting

From: Thom Brown <thom(at)linux(dot)com>
To: Magnus Hagander <magnus(at)hagander(dot)net>
Cc: Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us>, pgsql-docs <pgsql-docs(at)postgresql(dot)org>, pgsql-www <pgsql-www(at)postgresql(dot)org>
Subject: Re: [DOCS] Example indenting
Date: 2010-08-25 21:54:01
Message-ID: AANLkTi=Xc8v+b00BcUSk_-bnQt8nULYz0Jjcg6TwO-Ct@mail.gmail.com (view raw or flat)
Thread:
Lists: pgsql-docspgsql-www
On 24 August 2010 15:44, Thom Brown <thom(at)linux(dot)com> wrote:
> On 24 August 2010 09:35, Thom Brown <thom(at)linux(dot)com> wrote:
>> On 23 August 2010 16:09, Thom Brown <thom(at)linux(dot)com> wrote:
>>> On 23 August 2010 15:37, Magnus Hagander <magnus(at)hagander(dot)net> wrote:
>>>> On Mon, Aug 23, 2010 at 16:33, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
>>>>> Thom Brown <thom(at)linux(dot)com> writes:
>>>>>> On 23 August 2010 14:43, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)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

In response to

Responses

pgsql-docs by date

Next:From: Kevin GrittnerDate: 2010-08-25 22:51:16
Subject: Re: [DOCS] Example indenting
Previous:From: Mariano ReingartDate: 2010-08-25 20:04:09
Subject: Compiling and Linking Dynamically-Loaded Functions on Windows

pgsql-www by date

Next:From: Kevin GrittnerDate: 2010-08-25 22:51:16
Subject: Re: [DOCS] Example indenting
Previous:From: Greg Sabino MullaneDate: 2010-08-24 19:39:40
Subject: Re: "Subscribe" mails leaking through?

Privacy Policy | About PostgreSQL
Copyright © 1996-2014 The PostgreSQL Global Development Group