Thread: Reference manual
Vince, I don't see the reference manual on the web page 'documentation' page. I do see it in the 'postgres' manual. Can 'reference manual' be added, and 'postgres' indicated that it holds all the docs? -- Bruce Momjian | http://candle.pha.pa.us pgman@candle.pha.pa.us | (610) 853-3000 + If your life is a hard drive, | 830 Blythe Avenue + Christ can be your backup. | Drexel Hill, Pennsylvania 19026
On Fri, 9 Feb 2001, Bruce Momjian wrote: > Vince, I don't see the reference manual on the web page 'documentation' > page. I do see it in the 'postgres' manual. > > Can 'reference manual' be added, and 'postgres' indicated that it holds > all the docs? What reference manual? Is it in the current stuff? Vince. -- ========================================================================== Vince Vielhaber -- KA8CSH email: vev@michvhf.com http://www.pop4.net 128K ISDN from $22.00/mo - 56K Dialup from $16.00/mo at Pop4 Networking Online Campground Directory http://www.camping-usa.com Online Giftshop Superstore http://www.cloudninegifts.com ==========================================================================
> On Fri, 9 Feb 2001, Bruce Momjian wrote:
>
> > Vince, I don't see the reference manual on the web page 'documentation'
> > page. I do see it in the 'postgres' manual.
> >
> > Can 'reference manual' be added, and 'postgres' indicated that it holds
> > all the docs?
>
> What reference manual? Is it in the current stuff?
The manual pages. It appears in the postgres manual:
Table of Contents
PostgreSQL 7.1 Tutorial
PostgreSQL 7.1 User's Guide
PostgreSQL 7.1 Administrator's Guide
PostgreSQL 7.1 Programmer's Guide
PostgreSQL 7.1 Reference Manual
PostgreSQL 7.1 Developer's Guide
http://www.postgresql.org/devel-corner/docs/postgres/
--
Bruce Momjian | http://candle.pha.pa.us
pgman@candle.pha.pa.us | (610) 853-3000
+ If your life is a hard drive, | 830 Blythe Avenue
+ Christ can be your backup. | Drexel Hill, Pennsylvania 19026
On Fri, 9 Feb 2001, Bruce Momjian wrote: > PostgreSQL 7.1 Reference Manual > PostgreSQL 7.1 Developer's Guide Is there any particular reason why these are not also seperated out like the rest of the sections? I'm leary about putting pointers to things inside of a directory that is constantly changing. Both the FAQs and the search engine are already pointing to things that no longer exist and there's never a mention that something has been removed or is about to be removed from the docs. Vince. -- ========================================================================== Vince Vielhaber -- KA8CSH email: vev@michvhf.com http://www.pop4.net 128K ISDN from $22.00/mo - 56K Dialup from $16.00/mo at Pop4 Networking Online Campground Directory http://www.camping-usa.com Online Giftshop Superstore http://www.cloudninegifts.com ==========================================================================
> On Fri, 9 Feb 2001, Bruce Momjian wrote: > > > PostgreSQL 7.1 Reference Manual > > PostgreSQL 7.1 Developer's Guide > > Is there any particular reason why these are not also seperated out like > the rest of the sections? I'm leary about putting pointers to things > inside of a directory that is constantly changing. Both the FAQs and > the search engine are already pointing to things that no longer exist > and there's never a mention that something has been removed or is about > to be removed from the docs. No good reason to fix it. The current docs are OK, so I wouldn't worry about it if it is not easy to do. -- Bruce Momjian | http://candle.pha.pa.us pgman@candle.pha.pa.us | (610) 853-3000 + If your life is a hard drive, | 830 Blythe Avenue + Christ can be your backup. | Drexel Hill, Pennsylvania 19026
On Fri, 9 Feb 2001, Bruce Momjian wrote: > > On Fri, 9 Feb 2001, Bruce Momjian wrote: > > > > > Vince, I don't see the reference manual on the web page 'documentation' > > > page. I do see it in the 'postgres' manual. > > > > > > Can 'reference manual' be added, and 'postgres' indicated that it holds > > > all the docs? > > > > What reference manual? Is it in the current stuff? > > I see it in the current docs, yes. Just not in devel. In fact, I see > the 'postgres' docs listed as 'integrated docs' in 7.0. Just made those changes the other day. Will probably do something similar in the devel stuff in the next few days. Vince. -- ========================================================================== Vince Vielhaber -- KA8CSH email: vev@michvhf.com http://www.pop4.net 128K ISDN from $22.00/mo - 56K Dialup from $16.00/mo at Pop4 Networking Online Campground Directory http://www.camping-usa.com Online Giftshop Superstore http://www.cloudninegifts.com ==========================================================================
> On Fri, 9 Feb 2001, Bruce Momjian wrote: > > > Vince, I don't see the reference manual on the web page 'documentation' > > page. I do see it in the 'postgres' manual. > > > > Can 'reference manual' be added, and 'postgres' indicated that it holds > > all the docs? > > What reference manual? Is it in the current stuff? I see it in the current docs, yes. Just not in devel. In fact, I see the 'postgres' docs listed as 'integrated docs' in 7.0. -- Bruce Momjian | http://candle.pha.pa.us pgman@candle.pha.pa.us | (610) 853-3000 + If your life is a hard drive, | 830 Blythe Avenue + Christ can be your backup. | Drexel Hill, Pennsylvania 19026
On Fri, 9 Feb 2001, Bruce Momjian wrote: > > On Fri, 9 Feb 2001, Bruce Momjian wrote: > > > > > PostgreSQL 7.1 Reference Manual > > > PostgreSQL 7.1 Developer's Guide > > > > Is there any particular reason why these are not also seperated out like > > the rest of the sections? I'm leary about putting pointers to things > > inside of a directory that is constantly changing. Both the FAQs and > > the search engine are already pointing to things that no longer exist > > and there's never a mention that something has been removed or is about > > to be removed from the docs. > > No good reason to fix it. The current docs are OK, so I wouldn't worry > about it if it is not easy to do. Good reason to fix it if it's going to be generated the same way when 7.1 becomes the current release. Vince. -- ========================================================================== Vince Vielhaber -- KA8CSH email: vev@michvhf.com http://www.pop4.net 128K ISDN from $22.00/mo - 56K Dialup from $16.00/mo at Pop4 Networking Online Campground Directory http://www.camping-usa.com Online Giftshop Superstore http://www.cloudninegifts.com ==========================================================================
Bruce Momjian writes: > Vince, I don't see the reference manual on the web page 'documentation' > page. I do see it in the 'postgres' manual. > > Can 'reference manual' be added, and 'postgres' indicated that it holds > all the docs? As far as the HTML-formatted docs go and as far as 7.1 (and future) goes, there should only be exactly one link, which points to the index.html of the intergrated doc. There will no longer be separated docs, because that's why there's an integrated doc with a title page and all the links. -- Peter Eisentraut peter_e@gmx.net http://yi.org/peter-e/
Peter Eisentraut <peter_e@gmx.net> writes: > As far as the HTML-formatted docs go and as far as 7.1 (and future) goes, > there should only be exactly one link, which points to the index.html of > the intergrated doc. There will no longer be separated docs, because > that's why there's an integrated doc with a title page and all the links. A complaint that someone made on the lists last night crystallized something that's been bothering me for awhile now: the front page of the integrated docs (http://www.postgresql.org/devel-corner/docs/postgres/) is too sparse. If you don't already understand the layout of the docs, it's not clear where you want to go from here. I think it would work a lot better if this page showed not just the six top-level document names, but the first sublevel (ie, chapter headings) within each one. That would give people a sense of what is in each document, and it'd also save a level of click-through in many cases, since you could click straight to the chapter you want. It looks like this would expand the page from six lines to about fifty, which doesn't seem unreasonable. I have no idea if this is easy, hard, or impossible to do given our current documentation tools, but if it's possible I think it would be a good improvement. regards, tom lane
On Fri, 9 Feb 2001, Peter Eisentraut wrote: > Bruce Momjian writes: > > > Vince, I don't see the reference manual on the web page 'documentation' > > page. I do see it in the 'postgres' manual. > > > > Can 'reference manual' be added, and 'postgres' indicated that it holds > > all the docs? > > As far as the HTML-formatted docs go and as far as 7.1 (and future) goes, > there should only be exactly one link, which points to the index.html of > the intergrated doc. There will no longer be separated docs, because > that's why there's an integrated doc with a title page and all the links. I don't necessarily think this is a good idea. Vince. -- ========================================================================== Vince Vielhaber -- KA8CSH email: vev@michvhf.com http://www.pop4.net 128K ISDN from $22.00/mo - 56K Dialup from $16.00/mo at Pop4 Networking Online Campground Directory http://www.camping-usa.com Online Giftshop Superstore http://www.cloudninegifts.com ==========================================================================
Vince Vielhaber writes: > > As far as the HTML-formatted docs go and as far as 7.1 (and future) goes, > > there should only be exactly one link, which points to the index.html of > > the intergrated doc. There will no longer be separated docs, because > > that's why there's an integrated doc with a title page and all the links. > > I don't necessarily think this is a good idea. I don't see a difference in content between http://www.postgresql.org/users-lounge/docs/#7.0 and http://www.postgresql.org/devel-corner/docs/postgres/ (apart from the links to other formats, of course). So could you elaborate on your concerns? -- Peter Eisentraut peter_e@gmx.net http://yi.org/peter-e/
On Fri, 9 Feb 2001, Peter Eisentraut wrote: > Vince Vielhaber writes: > > > > As far as the HTML-formatted docs go and as far as 7.1 (and future) goes, > > > there should only be exactly one link, which points to the index.html of > > > the intergrated doc. There will no longer be separated docs, because > > > that's why there's an integrated doc with a title page and all the links. > > > > I don't necessarily think this is a good idea. > > I don't see a difference in content between > > http://www.postgresql.org/users-lounge/docs/#7.0 > > and > > http://www.postgresql.org/devel-corner/docs/postgres/ > > (apart from the links to other formats, of course). So could you > elaborate on your concerns? Tom already did part of it.. it looks like hell (to paraphrase) and is somewhat content free. The previous index in the integrated doc was much more useful than this. Also is the overall size of the integrated version vs the individual parts (for the non-html renditions). This new index also doesn't match the website, it's like you left and went elsewhere - and NO we're NOT putting it in frames. Vince. -- ========================================================================== Vince Vielhaber -- KA8CSH email: vev@michvhf.com http://www.pop4.net 128K ISDN from $22.00/mo - 56K Dialup from $16.00/mo at Pop4 Networking Online Campground Directory http://www.camping-usa.com Online Giftshop Superstore http://www.cloudninegifts.com ==========================================================================
Vince Vielhaber writes: > > I don't see a difference in content between > > > > http://www.postgresql.org/users-lounge/docs/#7.0 > > > > and > > > > http://www.postgresql.org/devel-corner/docs/postgres/ > > > > (apart from the links to other formats, of course). So could you > > elaborate on your concerns? > > Tom already did part of it.. it looks like hell (to paraphrase) and is > somewhat content free. But you don't claim that the listing at http://www.postgresql.org/users-lounge/docs/#7.0 has any additional content whatsoever, do you? > The previous index in the integrated doc was much more useful than > this. Possibly, although I found it way too long. There were other, maintainance related reasons for the change too. But the look can always be changed. > Also is the overall size of the integrated > version vs the individual parts (for the non-html renditions). Nobody was talking about the non-html renditions. > This new index also doesn't match the website, it's like you left and > went elsewhere True, but that is not a fault of the new vs. the old docs. And it can be fixed. If you can give me some sort of include files to stick at the top and bottom of each page, we can have the web site docs have the same side bar and colors and everything. > - and NO we're NOT putting it in frames. We better don't. ;-) -- Peter Eisentraut peter_e@gmx.net http://yi.org/peter-e/
Tom Lane writes: > A complaint that someone made on the lists last night crystallized > something that's been bothering me for awhile now: the front page of the > integrated docs (http://www.postgresql.org/devel-corner/docs/postgres/) > is too sparse. If you don't already understand the layout of the docs, > it's not clear where you want to go from here. > > I think it would work a lot better if this page showed not just the six > top-level document names, but the first sublevel (ie, chapter headings) > within each one. Agreed. > I have no idea if this is easy, hard, or impossible to do given our > current documentation tools, but if it's possible I think it would be > a good improvement. I would have said "medium to hard" (but only given that I've been studying DSSSL this week), but it turns out you just need to change exactly one character. If you have the stylesheets installed, locate the file html/dbautoc.dsl. At the very top you'll find (define (toc-depth nd) (if (string=? (gi nd) (normalize "book")) 3 1)) Change the 1 to 2. The result (just the title page) can be seen at <http://www.postgresql.org/~petere/set-index.html>. Yeah. In order to implement this without patching the stylesheet installation we'd need to write a style sheet customization layer. Not that this is difficult, not that I haven't spent this week writing one, but I wasn't going to use it until 7.2. If we wanted this now we could easily use some of the other customization features that are available, like changing the file name suffix to .html and numbering the sections as well as the chapters. If you want it, you'll have a totally differently looking documentation by Monday. ;-) -- Peter Eisentraut peter_e@gmx.net http://yi.org/peter-e/
On Fri, 9 Feb 2001, Peter Eisentraut wrote: > Vince Vielhaber writes: > > > > I don't see a difference in content between > > > > > > http://www.postgresql.org/users-lounge/docs/#7.0 > > > > > > and > > > > > > http://www.postgresql.org/devel-corner/docs/postgres/ > > > > > > (apart from the links to other formats, of course). So could you > > > elaborate on your concerns? > > > > Tom already did part of it.. it looks like hell (to paraphrase) and is > > somewhat content free. > > But you don't claim that the listing at > > http://www.postgresql.org/users-lounge/docs/#7.0 > > has any additional content whatsoever, do you? Yes, it tells you exactly what you're going to get when you click on it. > > > The previous index in the integrated doc was much more useful than > > this. > > Possibly, although I found it way too long. There were other, > maintainance related reasons for the change too. But the look can always > be changed. > > > Also is the overall size of the integrated > > version vs the individual parts (for the non-html renditions). > > Nobody was talking about the non-html renditions. > > > This new index also doesn't match the website, it's like you left and > > went elsewhere > > True, but that is not a fault of the new vs. the old docs. And it can be > fixed. If you can give me some sort of include files to stick at the top > and bottom of each page, we can have the web site docs have the same side > bar and colors and everything. Can't use includes. Can't use PHP. Can't hard code it into the docs. Can't use a bunch of things. We have mirrors. I'd love to redo it in PHP and serve up the content dynamically but that ain't gonna happen any time soon. Vince. -- ========================================================================== Vince Vielhaber -- KA8CSH email: vev@michvhf.com http://www.pop4.net 128K ISDN from $22.00/mo - 56K Dialup from $16.00/mo at Pop4 Networking Online Campground Directory http://www.camping-usa.com Online Giftshop Superstore http://www.cloudninegifts.com ==========================================================================
On Fri, 9 Feb 2001, Peter Eisentraut wrote: > Change the 1 to 2. The result (just the title page) can be seen at > <http://www.postgresql.org/~petere/set-index.html>. Yeah. Looks much better. Vince. -- ========================================================================== Vince Vielhaber -- KA8CSH email: vev@michvhf.com http://www.pop4.net 128K ISDN from $22.00/mo - 56K Dialup from $16.00/mo at Pop4 Networking Online Campground Directory http://www.camping-usa.com Online Giftshop Superstore http://www.cloudninegifts.com ==========================================================================
Vince Vielhaber writes: > > But you don't claim that the listing at > > > > http://www.postgresql.org/users-lounge/docs/#7.0 > > > > has any additional content whatsoever, do you? > > Yes, it tells you exactly what you're going to get when you click > on it. Maybe we're not talking about the same thing here. The current docs have, for example, a link "PostgreSQL 7.1 User's Guide". To me that says that when I click on it I get to read the User's Guide for PostgreSQL 7.1. In the user's lounge I have links along the lines of "Read the User's Guide online". That tells me the same thing. > Can't use includes. Can't use PHP. Can't hard code it into the docs. > Can't use a bunch of things. We have mirrors. I'd love to redo it in > PHP and serve up the content dynamically but that ain't gonna happen any > time soon. I wasn't talking about server-side includes. Don't you have template file fragments that you use when you create a new file on the web site? These could be inserted into the documentation files automatically when they are *created*. What do you mean with "can't hardcode" if you don't generate things dynamically? -- Peter Eisentraut peter_e@gmx.net http://yi.org/peter-e/
On Fri, 9 Feb 2001, Peter Eisentraut wrote: > Vince Vielhaber writes: > > > > But you don't claim that the listing at > > > > > > http://www.postgresql.org/users-lounge/docs/#7.0 > > > > > > has any additional content whatsoever, do you? > > > > Yes, it tells you exactly what you're going to get when you click > > on it. > > Maybe we're not talking about the same thing here. The current docs have, > for example, a link "PostgreSQL 7.1 User's Guide". To me that says that > when I click on it I get to read the User's Guide for PostgreSQL 7.1. > > In the user's lounge I have links along the lines of "Read the User's > Guide online". That tells me the same thing. It may tell it, but it doesn't say it and you were just commenting about that the other day. However like I said in my last note the format that you had on that page in your directory looks alot better. > > Can't use includes. Can't use PHP. Can't hard code it into the docs. > > Can't use a bunch of things. We have mirrors. I'd love to redo it in > > PHP and serve up the content dynamically but that ain't gonna happen any > > time soon. > > I wasn't talking about server-side includes. Don't you have template file > fragments that you use when you create a new file on the web site? These > could be inserted into the documentation files automatically when they are > *created*. What do you mean with "can't hardcode" if you don't generate > things dynamically? I have no desire or intention to rebuild the docs (past and present) any time a change is made to the website's look and feel. They aren't rebuilt every nite automatically like the devel docs are. So why the sudden desire to change things? Vince. -- ========================================================================== Vince Vielhaber -- KA8CSH email: vev@michvhf.com http://www.pop4.net 128K ISDN from $22.00/mo - 56K Dialup from $16.00/mo at Pop4 Networking Online Campground Directory http://www.camping-usa.com Online Giftshop Superstore http://www.cloudninegifts.com ==========================================================================
Vince Vielhaber <vev@michvhf.com> writes: > On Fri, 9 Feb 2001, Peter Eisentraut wrote: >> Change the 1 to 2. The result (just the title page) can be seen at >> <http://www.postgresql.org/~petere/set-index.html>. Yeah. > Looks much better. <aol>me too</aol> regards, tom lane
Vince Vielhaber writes: > I have no desire or intention to rebuild the docs (past and present) any > time a change is made to the website's look and feel. If you were to change the web site's look and feel you could always revert back to the docs as they are found in the respective distribution tarball. So at worst you're back to what we have now, in all other cases you have an improvement. > So why the sudden desire to change things? You said: "This new index also doesn't match the website, it's like you left and went elsewhere", which I interpreted as that you would like the docs to match the web site's look and feel, to which I agree. -- Peter Eisentraut peter_e@gmx.net http://yi.org/peter-e/
Peter Eisentraut <peter_e@gmx.net> writes:
>> So why the sudden desire to change things?
> You said: "This new index also doesn't match the website, it's like you
> left and went elsewhere", which I interpreted as that you would like the
> docs to match the web site's look and feel, to which I agree.
Here's a vote for leaving the docs the way they are, at least in that
respect. I don't *want* a bunch of sidebar clutter when I'm trying to
read docs; I want all the screen space I can get for the useful text.
regards, tom lane
> If you want it, you'll have a totally differently looking documentation by
> Monday. ;-)
(Haven't looked at the result, but I'm sure it's great)
I've been wanting to have a custom style sheet for a long time. Can we
have a "very thin" custom sheet for 7.1, which pretty much only changes
the index contents (and perhaps a couple of other small things if you
think they are important)?
If so, I'd say let's do it now, since it is a good step forward. And we
can revert and *not* use the style sheet if there are problems; afaik it
is a one-liner in the doc/sgml/src/Makefile.
- Thomas
On Sat, 10 Feb 2001, Peter Eisentraut wrote: > Vince Vielhaber writes: > > > I have no desire or intention to rebuild the docs (past and present) any > > time a change is made to the website's look and feel. > > If you were to change the web site's look and feel you could always revert > back to the docs as they are found in the respective distribution tarball. > So at worst you're back to what we have now, in all other cases you have > an improvement. > > > So why the sudden desire to change things? > > You said: "This new index also doesn't match the website, it's like you > left and went elsewhere", which I interpreted as that you would like the > docs to match the web site's look and feel, to which I agree. Try again. Your sudden desire started before today's conversation. Vince. -- ========================================================================== Vince Vielhaber -- KA8CSH email: vev@michvhf.com http://www.pop4.net 128K ISDN from $22.00/mo - 56K Dialup from $16.00/mo at Pop4 Networking Online Campground Directory http://www.camping-usa.com Online Giftshop Superstore http://www.cloudninegifts.com ==========================================================================