Re: [DOCS] Re: [INTERFACES] libpq & user
От | Thomas G. Lockhart |
---|---|
Тема | Re: [DOCS] Re: [INTERFACES] libpq & user |
Дата | |
Msg-id | 35AED21A.55BE5343@alumni.caltech.edu обсуждение исходный текст |
Ответ на | Re: [DOCS] Re: [INTERFACES] libpq & user (Bruce Momjian <maillist@candle.pha.pa.us>) |
Список | pgsql-interfaces |
> If people took the current man version of a file, converted it into > sgml, and deleted the old man file, that would be even better. No > duplication, but then you have to have a way to generate the man file, > and currently we don't. Well, the man pages as they currently exist aren't what we want anyway. See below. > I just did a context diff of the man directory since 6.3.2, and I have > 5k lines of diffs. Most of them are additions of underscores in man > pages names. This was done so the man->html could create proper links > for man pages. The rest are small wording changes or new libpq > functions. Not much. Great. That is encouraging, and matches my impression of where we are at. As v6.4 gets closer to release, you and others will be wanting to update docs to reflect new features, so this is a good time to get coordinated. > Let me know how we should proceed. Well, I think we are still short of a common view here, but closing in on it :) Remember, the man pages as they exist now will not exist in the future! The information content in a single current man page does not fit with a well structured document of any kind. The man pages in the future will be the same as the sgml reference pages, which summarize syntax and give examples. If you want the "whys and wherefores" then you go to the User's Guide, Administrator's Manual, or Reference Manual. This isn't a bad thing; it is the best way to present information. man pages will provide quick reminders, while the full docs are meant for teaching and informing. The man pages have more now because there was no other place to put new information, so we kept adding more and more to them. I'm just now generating a list of all files in the tree (as of last Friday) which are (or might be) documentation resources. I'll send you the list, and if you would remove any lines which are definitely not documentation and return the result to me then I will generate an sgml document/table from it and put it into a section of the "docguide" appendix, with it marked-up as to what has been converted and what has not. I'll update the web site doc information, and generate a new output version of the html docs for the web site and for our use. I will indicate which man pages have been directly used in the sgml docs (libpq, for example) and the other man pages are fair game for continued maintenance. However, if we already have a place for the same information in the sgml docs, I will call that out and ask that we try to maintain both for a short while. If we get some preliminary work on the man page conversion software done (so we have some pretty good examples which are close to adequate) then we can make the "hard switch" to sgml. OK? Let me know if these suggestions are headed in the right direction, and if so which ones you would like to support. Talk to you soon. - Tom
В списке pgsql-interfaces по дате отправления: