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/
Attachments:
doc_style.patchtext/x-patch; charset=US-ASCII; name=doc_style.patchDownload
diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile
index e6c8a49..19e640b 100644
--- a/doc/src/sgml/Makefile
+++ b/doc/src/sgml/Makefile
@@ -89,6 +89,9 @@ man-stamp: stylesheet-man.xsl postgres.xml
.PHONY: draft
JADE.html.call = $(JADE) $(JADEFLAGS) $(SPFLAGS) $(SGMLINCLUDE) $(CATALOG) -d stylesheet.dsl -t sgml -i output-html
+ifeq ($(STYLE),website)
+JADE.html.call += -V website-stylesheet
+endif
# The draft target creates HTML output in draft mode, without index (for faster build).
draft: postgres.sgml $(ALMOSTALLSGML) stylesheet.dsl
diff --git a/doc/src/sgml/stylesheet.dsl b/doc/src/sgml/stylesheet.dsl
index 232fa58..4179643 100644
--- a/doc/src/sgml/stylesheet.dsl
+++ b/doc/src/sgml/stylesheet.dsl
@@ -29,6 +29,7 @@
<!-- (applicable to all output formats) -->
(define draft-mode #f)
+(define website-stylesheet #f)
(define pgsql-docs-list "pgsql-docs@postgresql.org")
@@ -190,7 +191,7 @@
(define %root-filename% "index")
(define %link-mailto-url% (string-append "mailto:" pgsql-docs-list))
(define %use-id-as-filename% #t)
-(define %stylesheet% "stylesheet.css")
+(define %stylesheet% (if website-stylesheet "http://www.postgresql.org/media/css/docs.css" "stylesheet.css"))
(define %graphic-default-extension% "gif")
(define %gentext-nav-use-ff% #t)
(define %body-attr% '())
2012/2/25 Magnus Hagander <magnus@hagander.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
Show quoted text
Comments?
--
Magnus Hagander
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.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@hagander.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@gmail.com> wrote:
On Sat, Feb 25, 2012 at 7:54 AM, Magnus Hagander <magnus@hagander.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@hagander.net> writes:
On Mon, Feb 27, 2012 at 04:37, Robert Haas <robertmhaas@gmail.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@sss.pgh.pa.us> wrote:
Magnus Hagander <magnus@hagander.net> writes:
On Mon, Feb 27, 2012 at 04:37, Robert Haas <robertmhaas@gmail.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@hagander.net> wrote:
On Mon, Feb 27, 2012 at 16:20, Tom Lane <tgl@sss.pgh.pa.us> wrote:
Magnus Hagander <magnus@hagander.net> writes:
On Mon, Feb 27, 2012 at 04:37, Robert Haas <robertmhaas@gmail.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@sss.pgh.pa.us> wrote:
Magnus Hagander <magnus@hagander.net> writes:
On Mon, Feb 27, 2012 at 04:37, Robert Haas <robertmhaas@gmail.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@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com
+ It's impossible for everything to be true. +