public inbox for [email protected]help / color / mirror / Atom feed
Documentation Navigation Feedback 19+ messages / 7 participants [nested] [flat]
* Documentation Navigation Feedback @ 2011-01-14 02:49 Chris Meller <[email protected]> 0 siblings, 1 reply; 19+ messages in thread From: Chris Meller @ 2011-01-14 02:49 UTC (permalink / raw) To: pgsql-docs 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... :) Thanks! Chris ^ permalink raw reply [nested|flat] 19+ messages in thread
* Re: [DOCS] Documentation Navigation Feedback @ 2011-01-14 20:53 Bruce Momjian <[email protected]> parent: Chris Meller <[email protected]> 0 siblings, 3 replies; 19+ messages in thread From: Bruce Momjian @ 2011-01-14 20:53 UTC (permalink / raw) To: Chris Meller <[email protected]>; +Cc: PostgreSQL www <[email protected]> I am forwarding this email to the www team in case there is something that can be done to improve our website's display of documentation: --------------------------------------------------------------------------- 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... :) > > Thanks! > > Chris -- Sent via pgsql-docs mailing list ([email protected]) > To make changes to your subscription: > http://www.postgresql.org/mailpref/pgsql-docs -- Bruce Momjian <[email protected]> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. + ^ permalink raw reply [nested|flat] 19+ messages in thread
* Re: [DOCS] Documentation Navigation Feedback @ 2011-01-14 21:21 Brendan Jurd <[email protected]> parent: Bruce Momjian <[email protected]> 2 siblings, 1 reply; 19+ messages in thread From: Brendan Jurd @ 2011-01-14 21:21 UTC (permalink / raw) To: Bruce Momjian <[email protected]>; +Cc: Chris Meller <[email protected]>; PostgreSQL www <[email protected]> On 15 January 2011 07:53, Bruce Momjian <[email protected]> wrote: > > I am forwarding this email to the www team in case there is something > that can be done to improve our website's display of documentation: > I thoroughly agree with Chris' comments. The docs have excellent content but are somewhat unwieldly. The navigation links at the bottom are much more useful than the ones at the top, we might want to swap these around, or perhaps just duplicate what's currently at the bottom to both locations. I have never used "Fast {Back,For}ward", and after playing around with them a bit, I still don't see the point. Does a feature this obscure really deserve the prime real estate it currently occupies? I think I understand why the breadcrumbs stop at "PostgreSQL 9.0" -- the HTML docs themselves are generated from the doc sources in the core project, but the breadcrumbs are part of the webpage container, so they have no knowledge of the docs' internal structure. Still, if we could find some way to extend the breadcrumbs all the way down to the current page, it would be a big step up in usability. Cheers, BJ ^ permalink raw reply [nested|flat] 19+ messages in thread
* Re: [DOCS] Documentation Navigation Feedback @ 2011-01-15 09:49 Magnus Hagander <[email protected]> parent: Bruce Momjian <[email protected]> 2 siblings, 1 reply; 19+ messages in thread From: Magnus Hagander @ 2011-01-15 09:49 UTC (permalink / raw) To: Bruce Momjian <[email protected]>; +Cc: Chris Meller <[email protected]>; PostgreSQL www <[email protected]> On Fri, Jan 14, 2011 at 21:53, Bruce Momjian <[email protected]> wrote: > > I am forwarding this email to the www team in case there is something > that can be done to improve our website's display of documentation: > No, it properly belongs on the -docs list. The website just uses the HTML output that comes out of the main docs build, so that's where TOCs and links are made. All the website does is extract the <body> part an put it inside the framework that adds the logo and the breadcrumbs - but it doesn't have access to any more metadata than the filename and the title of the page, so it can't do anything more advanced. Any improvements there have to be made in the sgml->html translation step in the main code - or at least that step has to put the required metadata in the output. -- Magnus Hagander Me: http://www.hagander.net/ Work: http://www.redpill-linpro.com/ ^ permalink raw reply [nested|flat] 19+ messages in thread
* Re: [DOCS] Documentation Navigation Feedback @ 2011-01-16 20:14 Josh Berkus <[email protected]> parent: Magnus Hagander <[email protected]> 0 siblings, 0 replies; 19+ messages in thread From: Josh Berkus @ 2011-01-16 20:14 UTC (permalink / raw) To: Magnus Hagander <[email protected]>; +Cc: Bruce Momjian <[email protected]>; Chris Meller <[email protected]>; PostgreSQL www <[email protected]> > No, it properly belongs on the -docs list. The website just uses the > HTML output that comes out of the main docs build, so that's where > TOCs and links are made. All the website does is extract the <body> > part an put it inside the framework that adds the logo and the > breadcrumbs - but it doesn't have access to any more metadata than the > filename and the title of the page, so it can't do anything more > advanced. Any improvements there have to be made in the sgml->html > translation step in the main code - or at least that step has to put > the required metadata in the output. I remember that somebody did create and submit a left-side floating navigation window, though. Andrew as talking about putting it up somewhere public. Time to revisit that mod? -- -- Josh Berkus PostgreSQL Experts Inc. http://www.pgexperts.com ^ permalink raw reply [nested|flat] 19+ messages in thread
* Re: [DOCS] Documentation Navigation Feedback @ 2011-01-17 01:54 Robert Haas <[email protected]> parent: Brendan Jurd <[email protected]> 0 siblings, 0 replies; 19+ messages in thread From: Robert Haas @ 2011-01-17 01:54 UTC (permalink / raw) To: Brendan Jurd <[email protected]>; +Cc: Bruce Momjian <[email protected]>; Chris Meller <[email protected]>; PostgreSQL www <[email protected]> On Fri, Jan 14, 2011 at 4:21 PM, Brendan Jurd <[email protected]> wrote: > The navigation links at the bottom are much more useful than the ones > at the top, we might want to swap these around, or perhaps just > duplicate what's currently at the bottom to both locations. +1 for the latter. > I have never used "Fast {Back,For}ward", and after playing around with > them a bit, I still don't see the point. Does a feature this obscure > really deserve the prime real estate it currently occupies? IMHO, no. -- Robert Haas EnterpriseDB: http://www.enterprisedb.com The Enterprise PostgreSQL Company ^ permalink raw reply [nested|flat] 19+ messages in thread
* Re: Change to documentation headers @ 2011-02-03 01:13 Bruce Momjian <[email protected]> parent: Bruce Momjian <[email protected]> 2 siblings, 1 reply; 19+ messages in thread From: Bruce Momjian @ 2011-02-03 01:13 UTC (permalink / raw) To: Peter Eisentraut <[email protected]>; +Cc: Chris Meller <[email protected]>; pgsql-docs 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 <[email protected]> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. + ^ permalink raw reply [nested|flat] 19+ messages in thread
* Re: Change to documentation headers @ 2011-02-04 16:01 Peter Eisentraut <[email protected]> parent: Bruce Momjian <[email protected]> 0 siblings, 1 reply; 19+ messages in thread From: Peter Eisentraut @ 2011-02-04 16:01 UTC (permalink / raw) To: Bruce Momjian <[email protected]>; +Cc: Chris Meller <[email protected]>; pgsql-docs 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. ^ permalink raw reply [nested|flat] 19+ messages in thread
* Re: Change to documentation headers @ 2011-02-04 21:23 Bruce Momjian <[email protected]> parent: Peter Eisentraut <[email protected]> 0 siblings, 1 reply; 19+ messages in thread From: Bruce Momjian @ 2011-02-04 21:23 UTC (permalink / raw) To: Peter Eisentraut <[email protected]>; +Cc: Chris Meller <[email protected]>; pgsql-docs 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 <[email protected]> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. + ^ permalink raw reply [nested|flat] 19+ messages in thread
* Re: Change to documentation headers @ 2011-02-04 22:48 Chris Meller <[email protected]> parent: Bruce Momjian <[email protected]> 0 siblings, 1 reply; 19+ messages in thread From: Chris Meller @ 2011-02-04 22:48 UTC (permalink / raw) To: pgsql-docs 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). ^ permalink raw reply [nested|flat] 19+ messages in thread
* Re: Change to documentation headers @ 2011-02-05 01:03 Bruce Momjian <[email protected]> parent: Chris Meller <[email protected]> 0 siblings, 1 reply; 19+ messages in thread From: Bruce Momjian @ 2011-02-05 01:03 UTC (permalink / raw) To: Chris Meller <[email protected]>; +Cc: pgsql-docs 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 <[email protected]> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. + ^ permalink raw reply [nested|flat] 19+ messages in thread
* Re: Change to documentation headers @ 2011-02-05 01:07 Bruce Momjian <[email protected]> parent: Bruce Momjian <[email protected]> 0 siblings, 1 reply; 19+ messages in thread From: Bruce Momjian @ 2011-02-05 01:07 UTC (permalink / raw) To: Bruce Momjian <[email protected]>; +Cc: Chris Meller <[email protected]>; pgsql-docs 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 <[email protected]> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. + ^ permalink raw reply [nested|flat] 19+ messages in thread
* Re: Change to documentation headers @ 2011-02-05 15:55 Bruce Momjian <[email protected]> parent: Bruce Momjian <[email protected]> 0 siblings, 1 reply; 19+ messages in thread From: Bruce Momjian @ 2011-02-05 15:55 UTC (permalink / raw) To: Bruce Momjian <[email protected]>; +Cc: Chris Meller <[email protected]>; pgsql-docs 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 <[email protected]> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. + ^ permalink raw reply [nested|flat] 19+ messages in thread
* Re: Change to documentation headers @ 2011-02-08 02:00 Bruce Momjian <[email protected]> parent: Bruce Momjian <[email protected]> 0 siblings, 2 replies; 19+ messages in thread From: Bruce Momjian @ 2011-02-08 02:00 UTC (permalink / raw) To: Bruce Momjian <[email protected]>; +Cc: Chris Meller <[email protected]>; pgsql-docs 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 <[email protected]> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. + ^ permalink raw reply [nested|flat] 19+ messages in thread
* Re: Change to documentation headers @ 2011-03-11 12:07 Bruce Momjian <[email protected]> parent: Bruce Momjian <[email protected]> 1 sibling, 1 reply; 19+ messages in thread From: Bruce Momjian @ 2011-03-11 12:07 UTC (permalink / raw) To: Peter Eisentraut <[email protected]>; +Cc: Chris Meller <[email protected]>; pgsql-docs 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 <[email protected]> http://momjian.us > EnterpriseDB http://enterprisedb.com > > + It's impossible for everything to be true. + -- Bruce Momjian <[email protected]> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. + ^ permalink raw reply [nested|flat] 19+ messages in thread
* Re: Change to documentation headers @ 2011-03-15 20:28 Peter Eisentraut <[email protected]> parent: Bruce Momjian <[email protected]> 0 siblings, 1 reply; 19+ messages in thread From: Peter Eisentraut @ 2011-03-15 20:28 UTC (permalink / raw) To: Bruce Momjian <[email protected]>; +Cc: Chris Meller <[email protected]>; pgsql-docs 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 <[email protected]> http://momjian.us > > EnterpriseDB http://enterprisedb.com > > > > + It's impossible for everything to be true. + > > -- > Bruce Momjian <[email protected]> http://momjian.us > EnterpriseDB http://enterprisedb.com > > + It's impossible for everything to be true. + > ^ permalink raw reply [nested|flat] 19+ messages in thread
* Re: Change to documentation headers @ 2011-05-08 02:33 Bruce Momjian <[email protected]> parent: Peter Eisentraut <[email protected]> 0 siblings, 0 replies; 19+ messages in thread From: Bruce Momjian @ 2011-05-08 02:33 UTC (permalink / raw) To: Peter Eisentraut <[email protected]>; +Cc: Chris Meller <[email protected]>; pgsql-docs 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 <[email protected]> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. + ^ permalink raw reply [nested|flat] 19+ messages in thread
* Re: Change to documentation headers @ 2011-10-11 02:08 Bruce Momjian <[email protected]> parent: Bruce Momjian <[email protected]> 1 sibling, 1 reply; 19+ messages in thread From: Bruce Momjian @ 2011-10-11 02:08 UTC (permalink / raw) To: pgsql-docs; +Cc: Chris Meller <[email protected]> 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 <[email protected]> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. + Attachments: [text/x-diff] /rtmp/sgml (2.8K, 2-%2Frtmp%2Fsgml) download | inline diff: 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) ^ permalink raw reply [nested|flat] 19+ messages in thread
* Re: Change to documentation headers @ 2011-10-12 15:24 Bruce Momjian <[email protected]> parent: Bruce Momjian <[email protected]> 0 siblings, 0 replies; 19+ messages in thread From: Bruce Momjian @ 2011-10-12 15:24 UTC (permalink / raw) To: Bruce Momjian <[email protected]>; +Cc: pgsql-docs; Chris Meller <[email protected]> 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 <[email protected]> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. + ^ permalink raw reply [nested|flat] 19+ messages in thread
end of thread, other threads:[~2011-10-12 15:24 UTC | newest] Thread overview: 19+ messages (download: mbox mbox.gz follow: Atom feed) -- links below jump to the message on this page -- 2011-01-14 02:49 Documentation Navigation Feedback Chris Meller <[email protected]> 2011-01-14 20:53 ` Bruce Momjian <[email protected]> 2011-01-14 21:21 ` Brendan Jurd <[email protected]> 2011-01-17 01:54 ` Robert Haas <[email protected]> 2011-01-15 09:49 ` Magnus Hagander <[email protected]> 2011-01-16 20:14 ` Josh Berkus <[email protected]> 2011-02-03 01:13 ` Re: Change to documentation headers Bruce Momjian <[email protected]> 2011-02-04 16:01 ` Re: Change to documentation headers Peter Eisentraut <[email protected]> 2011-02-04 21:23 ` Re: Change to documentation headers Bruce Momjian <[email protected]> 2011-02-04 22:48 ` Re: Change to documentation headers Chris Meller <[email protected]> 2011-02-05 01:03 ` Re: Change to documentation headers Bruce Momjian <[email protected]> 2011-02-05 01:07 ` Re: Change to documentation headers Bruce Momjian <[email protected]> 2011-02-05 15:55 ` Re: Change to documentation headers Bruce Momjian <[email protected]> 2011-02-08 02:00 ` Re: Change to documentation headers Bruce Momjian <[email protected]> 2011-03-11 12:07 ` Re: Change to documentation headers Bruce Momjian <[email protected]> 2011-03-15 20:28 ` Re: Change to documentation headers Peter Eisentraut <[email protected]> 2011-05-08 02:33 ` Re: Change to documentation headers Bruce Momjian <[email protected]> 2011-10-11 02:08 ` Re: Change to documentation headers Bruce Momjian <[email protected]> 2011-10-12 15:24 ` Re: Change to documentation headers Bruce Momjian <[email protected]>
This inbox is served by agora; see mirroring instructions for how to clone and mirror all data and code used for this inbox