pg.ddx.io pgsql-docs@postgresql.org mailing list archivehelp / color / mirror / Atom feed
Documentation organization 3+ messages / 2 participants [nested] [flat]
* Documentation organization @ 2000-06-29 17:28 Peter Eisentraut <peter_e@gmx.net> 0 siblings, 1 reply; 3+ messages in thread From: Peter Eisentraut @ 2000-06-29 17:28 UTC (permalink / raw) To: pgsql-docs I've been looking into ways to handle the User/Admin/Programmer vs Integrated dichotomy a little better. I think the intergrated document as we know it needs to go. There's too much weirdness in the order (e.g., the tutorial coming after the FE/BE protocol, release notes somewhere in the middle, etc.) that is created by just pasting together the "guides". Also, the chapters are numbered differently, which makes referring to them by number impossible. But, it's not like I don't have a better idea. :-) DocBook has a <Set> as a parent element of <Book>. This would look something like this: <set> <title>PostgreSQL Documentation</> &user; &admin; ... </set> where &user and &admin would be the usual entities that contain <book>'s. When you process this you get admin.html, user.html, etc. as usual, but you also get a title page that contains links to all the "books". So this would in essence be the integrated document, just another level added to the click-hierarchy. (The ToC for the integrated document is way too long anyway.) This setup also allows us to make links across books in a transparent fashion. For example, if I write `See also <XRef id="mvcc">' in the administrator's guide it comes out as "See also Chapter 13 in the PostgreSQL User's Guide", with hyperlink. The question is how to make print documents from this. I haven't found a way for Jade's RTF backend to split its output into several files. But it should be possible to take this RTF document and just "save pages x-y" to get the user's guide, "save pages y-z" to get the admin guide, etc. and all the page numbers etc. should be in order. At the same time I've also been pondering what kinds of books/guides we need. The division that the integrated document already follows with its "parts" seems like a good idea to me: * User's guide (everything about query language) * Administator's guide * Interfaces guide (everything in src/interfaces, plus pgaccess, psql, etc.) * Programmer's guide (server-side programming, SPI, custom types, functions, procedural languages) * Developer's guide (to contribute to PostgreSQL) * Tutorial I also think we need to seperate out the * Installation instructions * Release notes (You really need these before installation or even download, not after administration.) Reference pages should be placed at the end of each document that they fit into. E.g., postmaster in Administorator's guide, psql in Interfaces, etc. Comments? Suggestions? Better ideas? -- Peter Eisentraut Sernanders väg 10:115 peter_e@gmx.net 75262 Uppsala http://yi.org/peter-e/ Sweden ^ permalink raw reply [nested|flat] 3+ messages in thread
* Re: Documentation organization @ 2000-06-29 17:56 Thomas Lockhart <lockhart@alumni.caltech.edu> parent: Peter Eisentraut <peter_e@gmx.net> 0 siblings, 1 reply; 3+ messages in thread From: Thomas Lockhart @ 2000-06-29 17:56 UTC (permalink / raw) To: Peter Eisentraut <peter_e@gmx.net>; +Cc: pgsql-docs > Comments? Suggestions? Better ideas? I can't argue with the statement that the overall organization is about right. :) I'm not sure how "set" will differ from "part" when it comes time to split up the hardcopy, but it might be pretty easy (it partly depends on how the RTF assigns the styles). Do you want to try to do "postgres.sgml" as a set-based doc and see how it works? Or modify it and commit it as postgres-set.sgml so we can carry along both until the kinks are worked out? > Reference pages should be placed at the end of each document that they > fit into. E.g., postmaster in Administorator's guide, psql in > Interfaces, etc. Hmm. I think that this might be OK, but I'm worried that there will be some "grey area" categories that make it hard to figure out which doc to look in for the reference. psql is a good example: why should it be in "Interfaces" (coding interfaces?) instead of "Applications"? But we can also carry along a separate "references" document which *does* integrate them all, as well as including them at the end of each relevant doc. I'm pretty sure that if I had to choose one or the other I'd choose to put them together. - Thomas ^ permalink raw reply [nested|flat] 3+ messages in thread
* Re: Documentation organization @ 2000-06-30 16:22 Peter Eisentraut <peter_e@gmx.net> parent: Thomas Lockhart <lockhart@alumni.caltech.edu> 0 siblings, 0 replies; 3+ messages in thread From: Peter Eisentraut @ 2000-06-30 16:22 UTC (permalink / raw) To: Thomas Lockhart <lockhart@alumni.caltech.edu>; +Cc: pgsql-docs Thomas Lockhart writes: > I'm not sure how "set" will differ from "part" when it comes time to > split up the hardcopy, but it might be pretty easy (it partly depends > on how the RTF assigns the styles). A "set" will cause the chapter and page numbering to restart in each book, which is what we'd presumably want. I will put something like I imagined together over the weekend and post it on the web so you can take a look. > But we can also carry along a separate "references" document which > *does* integrate them all, as well as including them at the end of > each relevant doc. Good idea. Let's see how it would come out. -- Peter Eisentraut Sernanders väg 10:115 peter_e@gmx.net 75262 Uppsala http://yi.org/peter-e/ Sweden ^ permalink raw reply [nested|flat] 3+ messages in thread
end of thread, other threads:[~2000-06-30 16:22 UTC | newest] Thread overview: 3+ messages (download: mbox mbox.gz follow: Atom feed) -- links below jump to the message on this page -- 2000-06-29 17:28 Documentation organization Peter Eisentraut <peter_e@gmx.net> 2000-06-29 17:56 ` Thomas Lockhart <lockhart@alumni.caltech.edu> 2000-06-30 16:22 ` Peter Eisentraut <peter_e@gmx.net>
This inbox is served by DDX for PostgreSQL; see mirroring instructions for how to clone and mirror all data and code used for this inbox