Re: Need help with SGML again
От | Josh Berkus |
---|---|
Тема | Re: Need help with SGML again |
Дата | |
Msg-id | 200310150946.01052.josh@agliodbs.com обсуждение исходный текст |
Ответ на | Re: Need help with SGML again (Peter Eisentraut <peter_e@gmx.net>) |
Ответы |
Re: Need help with SGML again
(Tom Lane <tgl@sss.pgh.pa.us>)
Re: Need help with SGML again (Peter Eisentraut <peter_e@gmx.net>) Re: Need help with SGML again ("Henry B. Hotz" <hotz@jpl.nasa.gov>) |
Список | pgsql-docs |
Peter, > You should consider the documentation like a book. That has two > consequences: > > 1. Linking to anything that is not a formal object (having a title and a > number) does not render well in print. ("for more information, see > paragraph 3 on page 15"?) I see what you mean. Given that I do 95% of my doc browsing in HTML, this seems very redundant to me, though; I think it would be interesting to see how many users refer to a paper version of the docs. We may find it's a tiny minority. I'm also annoyed that I found out that the doc strucutre I wanted to use was not permitted only after I typed & marked it, but that's hardly your fault. The way I see it, lack of linking leaves me with 3 choices: 1) Leave things the way they are, which will force new DBAs to scroll/click through runtime.sgml looking for the terms I've defined. 2) Create a seperate page/section giving just the basic settings and move the tuning information for the 10 settings I've augmennted to that document, making things more convenient for new DBAs but annoying experienced ones who need to swtich between the new page and the main GUC listing. 3) Copy the information to *both* places, adding repeated text to runtime.sgml, and the possibility of the two versions of each text getting out of synch. I'm leaning toward (2). Thoughts? > > Any thoughts on replacing Docbook with something else, someday? > > I don't see anything better arising. Something I could edit WYSWYG comes to mind, or at least standard enough DocBook that I could use OpenOffice.org on it. I'm serious about this. Documentation writing, like advocacy, is a great task for people who want to contribute to the project but don't have the coding skills. Currently, it's very difficult to involve any of those people in adding to the docs becuase they have to learn an arcane markup format first, for which there are no good tools on Windows. If we could move the docs to a format supported by a multi-platform WYSWYG editor, I'd bet you dinner that we could get at least 4 more regular documentation contributors, if not a dozen. -- Josh Berkus Aglio Database Solutions San Francisco
В списке pgsql-docs по дате отправления: