Обсуждение: Re: Change to documentation headers
Peter, based on feedback we have received, I think our users want our docs header to look the same as our docs footer, i.e. few people see the value of Fast Forward and Fast Backward, and they want "Up" to be in the header. You seem to have done all the substantive changes to stylesheet.dsl --- would you make these changes? Thanks. --------------------------------------------------------------------------- Chris Meller wrote: > I jumped into #postgresql earlier to ask a couple of questions and we > ended up talking about the documentation. agliodbs wanted me to mention > the problems I ran into trying to find what I was looking for on the > mailing list, so here we go. > > I was looking at the documentation (which, btw, has always been of a > very high quality, so props for that!) and trying to find out about > character sets and collations. I didn't have much luck looking at the > main TOC, which isn't a big deal or terribly unexpected, so I did a > search for 'collation'. The second result is the CREATE DATABASE > reference page, which is one of the main pages I was looking for, so > that's great. > > Once I'm there, though, I'm pretty much lost. I've got Prev and Next > links (and Fast Backward and Fast Forward, which didn't seem to do > anything different), but no indication of where I am or how to get > somewhere else. > > For a specific example: After reading the few pieces I needed to know > about for CREATE DATABASE, I wanted to move on to CREATE TABLE. It > looks like I'm in a function reference section, so I assume there must > be a main TOC page listing them all, but I don't see a link to that > anywhere. There's also no indication which chapter and section I'm in, > so I can't go back to the main TOC and navigate down to it to find the > chapter TOC. I ended up hitting 'Next' a dozen times to find CREATE > TABLE in the alphabetical list of functions. > > When I mentioned this out on IRC, peerce did point out that there's an > 'Up' link... at the bottom. I had no idea it was there. I'd found the > parameter I was looking for and had no reason to keep reading the rest > of the lengthy explanation of other parameters and caveats to using > them, so there was no reason for me to keep scrolling and I didn't > expect the navigation link I was looking for to be at the bottom. > > Once I was looking at the navigation at the bottom, it seemed like it > should be the navigation at the top of the page instead. There's an > 'up' link and the Prev and Next links include the title of the pages > you'd be moving to, which is actually nice to know. > > On other pages I saw that the chapter was shown under 'PostgreSQL x.y > Documentation' in the navigation at the top, so I don't know why there > wasn't a similar title on the function page. > > Expanding the breadcrumbs at the top, which only show that you're in > the PostgreSQL x.y documentation, to include the location in the > documentation would pretty much eliminate my problem... So would using > the save left-column navigation bar all the other pages seem to use. > > Anyway, there's my feedback. Great documentation, but confusing > navigation makes it tough to use. Carry on... :) -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. +
On ons, 2011-02-02 at 20:13 -0500, Bruce Momjian wrote: > Peter, based on feedback we have received, I think our users want our > docs header to look the same as our docs footer, i.e. few people see > the value of Fast Forward and Fast Backward, and they want "Up" to be in > the header. You seem to have done all the substantive changes to > stylesheet.dsl --- would you make these changes? Thanks. I'll look into it. Taking the same layout for the header navigation as for the footer navigation is not a problem. But the top also shows the current chapter title. Note sure if we want to lose that or show it somewhere different.
Peter Eisentraut wrote:
> On ons, 2011-02-02 at 20:13 -0500, Bruce Momjian wrote:
> > Peter, based on feedback we have received, I think our users want our
> > docs header to look the same as our docs footer, i.e. few people see
> > the value of Fast Forward and Fast Backward, and they want "Up" to be in
> > the header. You seem to have done all the substantive changes to
> > stylesheet.dsl --- would you make these changes? Thanks.
>
> I'll look into it.
>
> Taking the same layout for the header navigation as for the footer
> navigation is not a problem. But the top also shows the current chapter
> title. Note sure if we want to lose that or show it somewhere
> different.
Thanks. I studied stylesheet.dsl but was unable to understand how to
modify it.
Looking at the 9.0 docs now:
http://www.postgresql.org/docs/9.0/static/tutorial-fk.html
I do like the chapter title there.
Looking at "Home", we actually have two of them. The "Home" at the top
left of the page links to the PG homepage, while the "Home" at the
bottom goes to the top of the 9.0 documentation. That seems odd. Maybe
we need to remove the "Home" at the bottom, or rename it.
You could get away with changing "Fast Backward" to "Up" and removing
"Fast Forward".
--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com
+ It's impossible for everything to be true. +
On Feb 4, 2011, at 4:23 PM, Bruce Momjian wrote: > I do like the chapter title there. > > Looking at "Home", we actually have two of them. The "Home" at the top > left of the page links to the PG homepage, while the "Home" at the > bottom goes to the top of the 9.0 documentation. That seems odd. Maybe > we need to remove the "Home" at the bottom, or rename it. > > You could get away with changing "Fast Backward" to "Up" and removing > "Fast Forward". I like the title and chapter reference at the top. The "PostgreSQL x.y.z Documentation" title serves the same purpose as'Home' at the bottom, so it should be fine as-is. Making the chapter a link to the same destination as 'Up' would makesense to me... You want to go up to the chapter TOC and that's what I would expect to get if I clicked on a chapter link(just as if I clicked on it in the main TOC).
Chris Meller wrote: > > On Feb 4, 2011, at 4:23 PM, Bruce Momjian wrote: > > > I do like the chapter title there. > > > > Looking at "Home", we actually have two of them. The "Home" at the top > > left of the page links to the PG homepage, while the "Home" at the > > bottom goes to the top of the 9.0 documentation. That seems odd. Maybe > > we need to remove the "Home" at the bottom, or rename it. > > > > You could get away with changing "Fast Backward" to "Up" and removing > > "Fast Forward". > > I like the title and chapter reference at the top. The "PostgreSQL > x.y.z Documentation" title serves the same purpose as 'Home' at the > bottom, so it should be fine as-is. Making the chapter a link to the > same destination as 'Up' would make sense to me... You want to go up > to the chapter TOC and that's what I would expect to get if I clicked > on a chapter link (just as if I clicked on it in the main TOC). That is an interesting idea. I thought we had sub-sub-pages, but we don't --- every subpage has a chapter that should be the same as UP. I think making that title a link is a great idea. I think we can still remove fast forward/backward as just being too confusing. -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. +
Bruce Momjian wrote:
> Chris Meller wrote:
> >
> > On Feb 4, 2011, at 4:23 PM, Bruce Momjian wrote:
> >
> > > I do like the chapter title there.
> > >
> > > Looking at "Home", we actually have two of them. The "Home" at the top
> > > left of the page links to the PG homepage, while the "Home" at the
> > > bottom goes to the top of the 9.0 documentation. That seems odd. Maybe
> > > we need to remove the "Home" at the bottom, or rename it.
> > >
> > > You could get away with changing "Fast Backward" to "Up" and removing
> > > "Fast Forward".
> >
> > I like the title and chapter reference at the top. The "PostgreSQL
> > x.y.z Documentation" title serves the same purpose as 'Home' at the
> > bottom, so it should be fine as-is. Making the chapter a link to the
> > same destination as 'Up' would make sense to me... You want to go up
> > to the chapter TOC and that's what I would expect to get if I clicked
> > on a chapter link (just as if I clicked on it in the main TOC).
>
> That is an interesting idea. I thought we had sub-sub-pages, but we
> don't --- every subpage has a chapter that should be the same as UP. I
> think making that title a link is a great idea. I think we can still
> remove fast forward/backward as just being too confusing.
Oops, a problem. On this chapter page:
http://www.postgresql.org/docs/9.0/static/errcodes-appendix.html
there is no chapter name, and hence no "up" link for us, and we need one
there. Perhaps we need a link to "VIII. Appendixes" there. Peter, can
that be done?
--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com
+ It's impossible for everything to be true. +
Bruce Momjian wrote: > Bruce Momjian wrote: > > Chris Meller wrote: > > > > > > On Feb 4, 2011, at 4:23 PM, Bruce Momjian wrote: > > > > > > > I do like the chapter title there. > > > > > > > > Looking at "Home", we actually have two of them. The "Home" at the top > > > > left of the page links to the PG homepage, while the "Home" at the > > > > bottom goes to the top of the 9.0 documentation. That seems odd. Maybe > > > > we need to remove the "Home" at the bottom, or rename it. > > > > > > > > You could get away with changing "Fast Backward" to "Up" and removing > > > > "Fast Forward". > > > > > > I like the title and chapter reference at the top. The "PostgreSQL > > > x.y.z Documentation" title serves the same purpose as 'Home' at the > > > bottom, so it should be fine as-is. Making the chapter a link to the > > > same destination as 'Up' would make sense to me... You want to go up > > > to the chapter TOC and that's what I would expect to get if I clicked > > > on a chapter link (just as if I clicked on it in the main TOC). > > > > That is an interesting idea. I thought we had sub-sub-pages, but we > > don't --- every subpage has a chapter that should be the same as UP. I > > think making that title a link is a great idea. I think we can still > > remove fast forward/backward as just being too confusing. > > Oops, a problem. On this chapter page: > > http://www.postgresql.org/docs/9.0/static/errcodes-appendix.html > > there is no chapter name, and hence no "up" link for us, and we need one > there. Perhaps we need a link to "VIII. Appendixes" there. Peter, can > that be done? More thinking --- "PostgreSQL 9.0.3 Documentation" at the top center is already clickable, so that can act as the home. Let's duplicate that at the bottom too. -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. +
Bruce Momjian wrote: > Bruce Momjian wrote: > > Bruce Momjian wrote: > > > Chris Meller wrote: > > > > > > > > On Feb 4, 2011, at 4:23 PM, Bruce Momjian wrote: > > > > > > > > > I do like the chapter title there. > > > > > > > > > > Looking at "Home", we actually have two of them. The "Home" at the top > > > > > left of the page links to the PG homepage, while the "Home" at the > > > > > bottom goes to the top of the 9.0 documentation. That seems odd. Maybe > > > > > we need to remove the "Home" at the bottom, or rename it. > > > > > > > > > > You could get away with changing "Fast Backward" to "Up" and removing > > > > > "Fast Forward". > > > > > > > > I like the title and chapter reference at the top. The "PostgreSQL > > > > x.y.z Documentation" title serves the same purpose as 'Home' at the > > > > bottom, so it should be fine as-is. Making the chapter a link to the > > > > same destination as 'Up' would make sense to me... You want to go up > > > > to the chapter TOC and that's what I would expect to get if I clicked > > > > on a chapter link (just as if I clicked on it in the main TOC). > > > > > > That is an interesting idea. I thought we had sub-sub-pages, but we > > > don't --- every subpage has a chapter that should be the same as UP. I > > > think making that title a link is a great idea. I think we can still > > > remove fast forward/backward as just being too confusing. > > > > Oops, a problem. On this chapter page: > > > > http://www.postgresql.org/docs/9.0/static/errcodes-appendix.html > > > > there is no chapter name, and hence no "up" link for us, and we need one > > there. Perhaps we need a link to "VIII. Appendixes" there. Peter, can > > that be done? > > More thinking --- "PostgreSQL 9.0.3 Documentation" at the top center is > already clickable, so that can act as the home. Let's duplicate that at > the bottom too. OK, so here is a summary: o remove fast forward/backward links o add book title where there is no heading o make book and chapter titles as links o make the bottom footer match the top header Can we backpatch this to 8.2 so all our online documentation has it? -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. +
Peter, any status on this? --------------------------------------------------------------------------- Bruce Momjian wrote: > Bruce Momjian wrote: > > Bruce Momjian wrote: > > > Bruce Momjian wrote: > > > > Chris Meller wrote: > > > > > > > > > > On Feb 4, 2011, at 4:23 PM, Bruce Momjian wrote: > > > > > > > > > > > I do like the chapter title there. > > > > > > > > > > > > Looking at "Home", we actually have two of them. The "Home" at the top > > > > > > left of the page links to the PG homepage, while the "Home" at the > > > > > > bottom goes to the top of the 9.0 documentation. That seems odd. Maybe > > > > > > we need to remove the "Home" at the bottom, or rename it. > > > > > > > > > > > > You could get away with changing "Fast Backward" to "Up" and removing > > > > > > "Fast Forward". > > > > > > > > > > I like the title and chapter reference at the top. The "PostgreSQL > > > > > x.y.z Documentation" title serves the same purpose as 'Home' at the > > > > > bottom, so it should be fine as-is. Making the chapter a link to the > > > > > same destination as 'Up' would make sense to me... You want to go up > > > > > to the chapter TOC and that's what I would expect to get if I clicked > > > > > on a chapter link (just as if I clicked on it in the main TOC). > > > > > > > > That is an interesting idea. I thought we had sub-sub-pages, but we > > > > don't --- every subpage has a chapter that should be the same as UP. I > > > > think making that title a link is a great idea. I think we can still > > > > remove fast forward/backward as just being too confusing. > > > > > > Oops, a problem. On this chapter page: > > > > > > http://www.postgresql.org/docs/9.0/static/errcodes-appendix.html > > > > > > there is no chapter name, and hence no "up" link for us, and we need one > > > there. Perhaps we need a link to "VIII. Appendixes" there. Peter, can > > > that be done? > > > > More thinking --- "PostgreSQL 9.0.3 Documentation" at the top center is > > already clickable, so that can act as the home. Let's duplicate that at > > the bottom too. > > OK, so here is a summary: > > o remove fast forward/backward links > o add book title where there is no heading > o make book and chapter titles as links > o make the bottom footer match the top header > > Can we backpatch this to 8.2 so all our online documentation has it? > > -- > Bruce Momjian <bruce@momjian.us> http://momjian.us > EnterpriseDB http://enterprisedb.com > > + It's impossible for everything to be true. + -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. +
On fre, 2011-03-11 at 07:07 -0500, Bruce Momjian wrote: > Peter, any status on this? The summary below doesn't make much sense to me. I'll play around with it a little more, but while I understand the goals, the concrete solution isn't yet clear. > > --------------------------------------------------------------------------- > > Bruce Momjian wrote: > > Bruce Momjian wrote: > > > Bruce Momjian wrote: > > > > Bruce Momjian wrote: > > > > > Chris Meller wrote: > > > > > > > > > > > > On Feb 4, 2011, at 4:23 PM, Bruce Momjian wrote: > > > > > > > > > > > > > I do like the chapter title there. > > > > > > > > > > > > > > Looking at "Home", we actually have two of them. The "Home" at the top > > > > > > > left of the page links to the PG homepage, while the "Home" at the > > > > > > > bottom goes to the top of the 9.0 documentation. That seems odd. Maybe > > > > > > > we need to remove the "Home" at the bottom, or rename it. > > > > > > > > > > > > > > You could get away with changing "Fast Backward" to "Up" and removing > > > > > > > "Fast Forward". > > > > > > > > > > > > I like the title and chapter reference at the top. The "PostgreSQL > > > > > > x.y.z Documentation" title serves the same purpose as 'Home' at the > > > > > > bottom, so it should be fine as-is. Making the chapter a link to the > > > > > > same destination as 'Up' would make sense to me... You want to go up > > > > > > to the chapter TOC and that's what I would expect to get if I clicked > > > > > > on a chapter link (just as if I clicked on it in the main TOC). > > > > > > > > > > That is an interesting idea. I thought we had sub-sub-pages, but we > > > > > don't --- every subpage has a chapter that should be the same as UP. I > > > > > think making that title a link is a great idea. I think we can still > > > > > remove fast forward/backward as just being too confusing. > > > > > > > > Oops, a problem. On this chapter page: > > > > > > > > http://www.postgresql.org/docs/9.0/static/errcodes-appendix.html > > > > > > > > there is no chapter name, and hence no "up" link for us, and we need one > > > > there. Perhaps we need a link to "VIII. Appendixes" there. Peter, can > > > > that be done? > > > > > > More thinking --- "PostgreSQL 9.0.3 Documentation" at the top center is > > > already clickable, so that can act as the home. Let's duplicate that at > > > the bottom too. > > > > OK, so here is a summary: > > > > o remove fast forward/backward links > > o add book title where there is no heading > > o make book and chapter titles as links > > o make the bottom footer match the top header > > > > Can we backpatch this to 8.2 so all our online documentation has it? > > > > -- > > Bruce Momjian <bruce@momjian.us> http://momjian.us > > EnterpriseDB http://enterprisedb.com > > > > + It's impossible for everything to be true. + > > -- > Bruce Momjian <bruce@momjian.us> http://momjian.us > EnterpriseDB http://enterprisedb.com > > + It's impossible for everything to be true. + >
Peter Eisentraut wrote: > On fre, 2011-03-11 at 07:07 -0500, Bruce Momjian wrote: > > Peter, any status on this? > > The summary below doesn't make much sense to me. I'll play around with > it a little more, but while I understand the goals, the concrete > solution isn't yet clear. > Peter, where are we on this? We discussed it at PG East. -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. +
Bruce Momjian wrote:
> > More thinking --- "PostgreSQL 9.0.3 Documentation" at the top center is
> > already clickable, so that can act as the home. Let's duplicate that at
> > the bottom too.
>
> OK, so here is a summary:
>
> o remove fast forward/backward links
> o add book title where there is no heading
> o make book and chapter titles as links
> o make the bottom footer match the top header
>
> Can we backpatch this to 8.2 so all our online documentation has it?
I have developed the attached patch which implements an "Up/Home" link
at the top of the page in place of the "Fast Backward" link, and removes
the "Fast Forward" link. It says "Up", unless you are already at the
book title, in which case it says "Home".
While this isn't ideal, it is probably good enough to make things easier
for users. This might be nice to backpatch so all our docs have the
same navigation links.
You can view the built docs here:
http://momjian.us/expire/pgsql/index.html
--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com
+ It's impossible for everything to be true. +
diff --git a/doc/src/sgml/stylesheet.dsl b/doc/src/sgml/stylesheet.dsl
new file mode 100644
index 637758f..2c18dab
*** a/doc/src/sgml/stylesheet.dsl
--- b/doc/src/sgml/stylesheet.dsl
***************
*** 284,290 ****
;; Customization of header, add title attributes (overrides
;; dbcommon.dsl)
! (define (default-header-nav-tbl-ff elemnode prev next prevsib nextsib)
(let* ((r1? (nav-banner? elemnode))
(r1-sosofo (make element gi: "TR"
(make element gi: "TH"
--- 284,290 ----
;; Customization of header, add title attributes (overrides
;; dbcommon.dsl)
! (define (default-header-nav-tbl-ff elemnode prev next)
(let* ((r1? (nav-banner? elemnode))
(r1-sosofo (make element gi: "TR"
(make element gi: "TH"
***************
*** 298,305 ****
(nav-banner elemnode)))))
(r2? (or (not (node-list-empty? prev))
(not (node-list-empty? next))
- (not (node-list-empty? prevsib))
- (not (node-list-empty? nextsib))
(nav-context? elemnode)))
(r2-sosofo (make element gi: "TR"
(make element gi: "TD"
--- 298,303 ----
***************
*** 323,337 ****
(list "WIDTH" "10%")
(list "ALIGN" "left")
(list "VALIGN" "top"))
! (if (node-list-empty? prevsib)
! (make entity-ref name: "nbsp")
! (make element gi: "A"
! attributes: (list
! (list "TITLE" (element-title-string prevsib))
! (list "HREF"
! (href-to
! prevsib)))
! (gentext-nav-prev-sibling prevsib))))
(make element gi: "TD"
attributes: (list
(list "WIDTH" "60%")
--- 321,329 ----
(list "WIDTH" "10%")
(list "ALIGN" "left")
(list "VALIGN" "top"))
! (if (nav-up? elemnode)
! (nav-up elemnode)
! (nav-home-link elemnode)))
(make element gi: "TD"
attributes: (list
(list "WIDTH" "60%")
***************
*** 340,360 ****
(nav-context elemnode))
(make element gi: "TD"
attributes: (list
! (list "WIDTH" "10%")
! (list "ALIGN" "right")
! (list "VALIGN" "top"))
! (if (node-list-empty? nextsib)
! (make entity-ref name: "nbsp")
! (make element gi: "A"
! attributes: (list
! (list "TITLE" (element-title-string nextsib))
! (list "HREF"
! (href-to
! nextsib)))
! (gentext-nav-next-sibling nextsib))))
! (make element gi: "TD"
! attributes: (list
! (list "WIDTH" "10%")
(list "ALIGN" "right")
(list "VALIGN" "top"))
(if (node-list-empty? next)
--- 332,338 ----
(nav-context elemnode))
(make element gi: "TD"
attributes: (list
! (list "WIDTH" "20%")
(list "ALIGN" "right")
(list "VALIGN" "top"))
(if (node-list-empty? next)
Bruce Momjian wrote: > Bruce Momjian wrote: > > > More thinking --- "PostgreSQL 9.0.3 Documentation" at the top center is > > > already clickable, so that can act as the home. Let's duplicate that at > > > the bottom too. > > > > OK, so here is a summary: > > > > o remove fast forward/backward links > > o add book title where there is no heading > > o make book and chapter titles as links > > o make the bottom footer match the top header > > > > Can we backpatch this to 8.2 so all our online documentation has it? > > I have developed the attached patch which implements an "Up/Home" link > at the top of the page in place of the "Fast Backward" link, and removes > the "Fast Forward" link. It says "Up", unless you are already at the > book title, in which case it says "Home". > > While this isn't ideal, it is probably good enough to make things easier > for users. This might be nice to backpatch so all our docs have the > same navigation links. > > You can view the built docs here: > > http://momjian.us/expire/pgsql/index.html Applied to head, 9.0.X, and 9.1.X. -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. +