Re: Website stylesheet for local docs

I've asked for this a few times before, but it seems others aren't as
keen on it as me :-) Personally, I find the docs easier to read when
formatted with the new website styles that Thom put together, and I
also like to see things the way they're going to look when they go up
there.

Attached patch makes it possible to say "make STYLE=website" for the
docs, which will then simply replace the stylesheet reference with one
that goes to fetch docs.css on the website. I'm not suggesting we
change the default or anything, just making it reasonably easy to get
it done for one-off builds.

I don't really speak the DSSSL naugage, so there might be a better way
of doing it..

Comments?

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

2012/2/25 Magnus Hagander <magnus(at)hagander(dot)net>:
> I've asked for this a few times before, but it seems others aren't as
> keen on it as me :-) Personally, I find the docs easier to read when
> formatted with the new website styles that Thom put together, and I
> also like to see things the way they're going to look when they go up
> there.
>
> Attached patch makes it possible to say "make STYLE=website" for the
> docs, which will then simply replace the stylesheet reference with one
> that goes to fetch docs.css on the website. I'm not suggesting we
> change the default or anything, just making it reasonably easy to get
> it done for one-off builds.
>
> I don't really speak the DSSSL naugage, so there might be a better way
> of doing it..

+1

Pavel

>
> Comments?
>
> --
>  Magnus Hagander
>  Me: http://www.hagander.net/
>  Work: http://www.redpill-linpro.com/
>
>
> --
> Sent via pgsql-hackers mailing list (pgsql-hackers(at)postgresql(dot)org)
> To make changes to your subscription:
> http://www.postgresql.org/mailpref/pgsql-hackers
>

On Sat, Feb 25, 2012 at 7:54 AM, Magnus Hagander <magnus(at)hagander(dot)net> wrote:
> I've asked for this a few times before, but it seems others aren't as
> keen on it as me :-) Personally, I find the docs easier to read when
> formatted with the new website styles that Thom put together, and I
> also like to see things the way they're going to look when they go up
> there.

Agreed.

> Attached patch makes it possible to say "make STYLE=website" for the
> docs, which will then simply replace the stylesheet reference with one
> that goes to fetch docs.css on the website.

Wouldn't it be better to include the stylesheet in our tree, if we're
going to depend on it?

> I'm not suggesting we
> change the default or anything, just making it reasonably easy to get
> it done for one-off builds.

Why not change the default? Does anyone really prefer the bare bones
doc output?

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

On Mon, Feb 27, 2012 at 04:37, Robert Haas <robertmhaas(at)gmail(dot)com> wrote:
> On Sat, Feb 25, 2012 at 7:54 AM, Magnus Hagander <magnus(at)hagander(dot)net> wrote:
>> I've asked for this a few times before, but it seems others aren't as
>> keen on it as me :-) Personally, I find the docs easier to read when
>> formatted with the new website styles that Thom put together, and I
>> also like to see things the way they're going to look when they go up
>> there.
>
> Agreed.
>
>> Attached patch makes it possible to say "make STYLE=website" for the
>> docs, which will then simply replace the stylesheet reference with one
>> that goes to fetch docs.css on the website.
>
> Wouldn't it be better to include the stylesheet in our tree, if we're
> going to depend on it?

Probably, I just took the easiest route. That way it gets updated as
well. And since it was an optional feature. And since that stylesheet
depends on other stylesheets which depend on images etc, with some
fairly fixed paths in them...

>> I'm not suggesting we
>> change the default or anything, just making it reasonably easy to get
>> it done for one-off builds.
>
> Why not change the default?  Does anyone really prefer the bare bones
> doc output?

Yes, Peter made a point about preferring that back when we changed the
developer docs to be on the main website (how it got worse but at
least he could work on his local build).

But it would be easy enough to flip the switch and instead have a make
STYLE=light or something like that...

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

Magnus Hagander <magnus(at)hagander(dot)net> writes:
> On Mon, Feb 27, 2012 at 04:37, Robert Haas <robertmhaas(at)gmail(dot)com> wrote:
>> Why not change the default? Does anyone really prefer the bare bones
>> doc output?

> Yes, Peter made a point about preferring that back when we changed the
> developer docs to be on the main website (how it got worse but at
> least he could work on his local build).

FWIW, I don't especially like the website style either --- it's too busy
calling attention to itself with colored backgrounds etc.

regards, tom lane

On Mon, Feb 27, 2012 at 16:20, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
> Magnus Hagander <magnus(at)hagander(dot)net> writes:
>> On Mon, Feb 27, 2012 at 04:37, Robert Haas <robertmhaas(at)gmail(dot)com> wrote:
>>> Why not change the default?  Does anyone really prefer the bare bones
>>> doc output?
>
>> Yes, Peter made a point about preferring that back when we changed the
>> developer docs to be on the main website (how it got worse but at
>> least he could work on his local build).
>
> FWIW, I don't especially like the website style either --- it's too busy
> calling attention to itself with colored backgrounds etc.

There we go, at least two people, and people who do a lot of builds
and checks of the docs, like the current format. So I think that's a
good argument to keep the current format the default, and just add a
target like my suggestion as an *option* :-)

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

On Mon, Feb 27, 2012 at 17:26, Magnus Hagander <magnus(at)hagander(dot)net> wrote:
> On Mon, Feb 27, 2012 at 16:20, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
>> Magnus Hagander <magnus(at)hagander(dot)net> writes:
>>> On Mon, Feb 27, 2012 at 04:37, Robert Haas <robertmhaas(at)gmail(dot)com> wrote:
>>>> Why not change the default?  Does anyone really prefer the bare bones
>>>> doc output?
>>
>>> Yes, Peter made a point about preferring that back when we changed the
>>> developer docs to be on the main website (how it got worse but at
>>> least he could work on his local build).
>>
>> FWIW, I don't especially like the website style either --- it's too busy
>> calling attention to itself with colored backgrounds etc.
>
> There we go, at least two people, and people who do a lot of builds
> and checks of the docs, like the current format. So I think that's a
> good argument to keep the current format the default, and just add a
> target like my suggestion as an *option* :-)

Ok, I've applied the current version of this patch based on that it's
useful for many, but kept the default value. I've also went with not
putting the css into the tree at this point, since it's multiple files
and lots of interactions. We can enhance it with that later..

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

On Mon, Feb 27, 2012 at 05:26:04PM +0100, Magnus Hagander wrote:
> On Mon, Feb 27, 2012 at 16:20, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
> > Magnus Hagander <magnus(at)hagander(dot)net> writes:
> >> On Mon, Feb 27, 2012 at 04:37, Robert Haas <robertmhaas(at)gmail(dot)com> wrote:
> >>> Why not change the default?  Does anyone really prefer the bare bones
> >>> doc output?
> >
> >> Yes, Peter made a point about preferring that back when we changed the
> >> developer docs to be on the main website (how it got worse but at
> >> least he could work on his local build).
> >
> > FWIW, I don't especially like the website style either --- it's too busy
> > calling attention to itself with colored backgrounds etc.
>
> There we go, at least two people, and people who do a lot of builds
> and checks of the docs, like the current format. So I think that's a
> good argument to keep the current format the default, and just add a
> target like my suggestion as an *option* :-)

One other problem with the website style is that there is a zero left
margin, making it harder to read. That might work fine when displayed
inside our existing website div blocks, but not stand-alone.

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

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