Re: [DOCS] Switching to XML
Am Montag, 11. Dezember 2006 02:18 schrieb David Blewett:
> Sorry to butt in, but I'm still not sure how to do multiple indexes
> in one volume using the DSSSL stylesheets.
I'm not sure either.
> The docs I pointed to were for the XSL stylesheets.
Right. So using the XSL(T) stylesheet instead of the DSSSL stylesheet would
be a step in the right direction. Actually the 8.2 branch currently only has
an XSLT stylesheet for HTML output. In 8.3devel I've added one for XSL-FO
output, which you can invoke by "make postgres-{A4|US}.fo". (You will
probably want yet a different paper format for your book.)
--
Peter Eisentraut
http://developer.postgresql.org/~petere/
---(end of broadcast)---
TIP 9: In versions below 8.0, the planner will ignore your desire to
choose an index scan if your joining column's datatypes do not
match
Re: [DOCS] More missing docs (aggs)
Tom, > Uh, why do you think that's significant? The stype is whatever you > need to use. Right, but do you have two stypes for a multi-col, a single stype, or a composite stype? The docs don't say and it's not obvious. -- Josh Berkus PostgreSQL @ Sun San Francisco ---(end of broadcast)--- TIP 9: In versions below 8.0, the planner will ignore your desire to choose an index scan if your joining column's datatypes do not match
Re: [DOCS] More missing docs (aggs)
Josh Berkus writes: >> Uh, why do you think that's significant? The stype is whatever you >> need to use. > Right, but do you have two stypes for a multi-col, a single stype, or a > composite stype? The docs don't say and it's not obvious. There is only one transition state variable, as I should think would be reasonably obvious from the wording: An aggregate function is made from one or two ordinary functions: a state transition function sfunc, and an optional final calculation function ffunc. These are used as follows: sfunc( internal-state, next-data-values ) ---> next-internal-state ffunc( internal-state ) ---> aggregate-value PostgreSQL creates a temporary variable of data type stype to hold the current internal state of the aggregate. At each input row, the aggregate argument value(s) are calculated and the state transition function is invoked with the current state value and the new argument value(s) to calculate a new internal state value. Whether the state value is a composite type or not is up to the aggregate author. There aren't any examples of using a composite type in the docs, but there are examples of using an array as stype, so I would hope that our users are bright enough to think of composites when they need one. regards, tom lane ---(end of broadcast)--- TIP 7: You can help support the PostgreSQL project by donating at http://www.postgresql.org/about/donate
Re: [DOCS] More missing docs (aggs)
Tom, > Whether the state value is a composite type or not is up to the > aggregate author. There aren't any examples of using a composite type > in the docs, but there are examples of using an array as stype, so > I would hope that our users are bright enough to think of composites > when they need one. Aha, got it. OK, so this just needs a good example ... will try to think of one. -- Josh Berkus PostgreSQL @ Sun San Francisco ---(end of broadcast)--- TIP 6: explain analyze is your friend
Re: [DOCS] Authoring Tools WAS: Switching to XML
Folks, Tom and Peter correctly point out that discussion of production tools and authoring tools are separate, and only come together if there are tools for XML which solve both issues, an assertion which is not yet proven. I am one of the champions of XML simply because I know for a fact that there are no real authoring tools* for SGML. However, I do *not* know that the tools for XML produce acceptable output. So, questions to answer: 1) Are there enhanced tools for Docbook XML, WYSWYG or otherwise, which make doc authoring easier and produce correct output for PostgreSQL Docs? 1) a) is there some way we can try various tools and check output? 2) If (1), would switching to XML make doc writing with Emacs/VIM harder? 3) If (1), will having authoring tools available increase the number of doc contributors? Regarding (3), I believe that having authoring tools would increase our pool based on two things: a) Anectodal evidence, including several people (like me) who were prevented from doing significant doc clean-up by the amount of labor required to restructure large SGML documents. b) That the vast majority of the OSS world is no longer using SGML, meaning that even for hand-editing people who work on other projects will be more familiar with XML and thus better able to edit it. While these two may not be enough to answer "should we migrate", they are enough to make it worth trying to find the answer to (1), since if all of the Docbook XML authoring tools are crappy the whole discussion is moot. So, can someone help me come up with a way to validate a Docbook XML version of the PostgreSQL docs so that I (and others, hopefully) can start testing tools? * = an authoring tool is one which makes generation of the document easier/faster than hand-editing text files. No such tool exists for SGML -- even the Emacs toolkit merely does validation. -- Josh Berkus PostgreSQL @ Sun San Francisco ---(end of broadcast)--- TIP 2: Don't 'kill -9' the postmaster
Re: [DOCS] 8.2.0 pdf
Devrim GUNDUZ escribió: Hi, On Thu, 2006-12-07 at 18:32 +0200, Devrim GUNDUZ wrote: On Thu, 2006-12-07 at 14:39 +0100, Javier Molina wrote: Page numbers do not appear in the table of contents (they show as ??) starting from ALTER TABLESPACE (page xix), they were fine in 8.1. Yes, this was reported this morning -- I started to rebuild the pdf. I committed the new 8.2-A4 pdf to CVS -- it will hit the mirrors soon. Regards, Great, now I will be able to print it. Thanks! ---(end of broadcast)--- TIP 3: Have you checked our extensive FAQ? http://www.postgresql.org/docs/faq
Re: [DOCS] Authoring Tools WAS: Switching to XML
> So, questions to answer: > > 1) Are there enhanced tools for Docbook XML, WYSWYG or otherwise, which make > doc authoring easier and produce correct output for PostgreSQL Docs? Anything that you produce from a WYSWYG editor is going to have to be massaged to work with PostgreSQL.Org docs. > 1) a) is there some way we can try various tools and check output? OpenOffice.Org, WordPerfect, Kword, Abiword. The first two (last I checked) were the only mature software supporting Docbook output. > > 2) If (1), would switching to XML make doc writing with Emacs/VIM harder? Absolutely not. > > 3) If (1), will having authoring tools available increase the number of doc > contributors? It might. However, getting authors will always be difficult. Having clear direction from the website on how to contribute documentation. This should include how to contribute if you don't know Docbook. Right now, you have to dig all the way to Appendix G (who reads apepedixes?). Something like this would also be helpful: http://www.tldp.org/LDP/LDP-Author-Guide/html/index.html > Regarding (3), I believe that having authoring tools would increase our pool > based on two things: > a) Anectodal evidence, including several people (like me) who were prevented > from doing significant doc clean-up by the amount of labor required to > restructure large SGML documents. Well to be honest, there isn't really anyway around that that I know of. OpenOffice.Org will allow you to do what you want, but someone is going to have to clean up after you. Now, that is not neccessarily a road block. It is certainly plausible that someone could write a section (although I think plain text would be better here) or rewrite a section and submit it for factoring. Factoring would involve any Docbook that needed to be done. Usually the Docbook that is required is trivial. > b) That the vast majority of the OSS world is no longer using SGML, meaning > that even for hand-editing people who work on other projects will be more > familiar with XML and thus better able to edit it. Well that is certainly true. > So, can someone help me come up with a way to validate a Docbook XML version > of the PostgreSQL docs so that I (and others, hopefully) can start testing > tools? >From the source tree: make postgres.xml Then validate as you see fit. Just FYI, it does validate. > > > * = an authoring tool is one which makes generation of the document > easier/faster than hand-editing text files. No such tool exists for SGML -- > even the Emacs toolkit merely does validation. > What is it specifically you are looking for then? Because that is what Docbook is, XML (or sgml) the only thing you need to do is validate. http://www.commandprompt.com/community/emacs_sgml/ If you use OpenOffice you will have to set up a style to correct mirror the PostgreSQL Docbook usage. Is that perhaps useful? An OpenOffice style that people could download that is documented and can be used for creating reasonably useful Docbook for the community? Sincerely, Joshua D. Drake -- === The PostgreSQL Company: Command Prompt, Inc. === Sales/Support: +1.503.667.4564 || 24x7/Emergency: +1.800.492.2240 Providing the most comprehensive PostgreSQL solutions since 1997 http://www.commandprompt.com/ Donate to the PostgreSQL Project: http://www.postgresql.org/about/donate ---(end of broadcast)--- TIP 7: You can help support the PostgreSQL project by donating at http://www.postgresql.org/about/donate
Re: [DOCS] Switching to XML
-BEGIN PGP SIGNED MESSAGE-
Hash: SHA256
Peter Eisentraut wrote:
> Right. So using the XSL(T) stylesheet instead of the DSSSL stylesheet would
> be a step in the right direction. Actually the 8.2 branch currently only has
> an XSLT stylesheet for HTML output. In 8.3devel I've added one for XSL-FO
> output, which you can invoke by "make postgres-{A4|US}.fo". (You will
> probably want yet a different paper format for your book.)
Excuse my ignorance, but I thought XSLT stylesheets can only be used
on XML files?
David Blewett
-BEGIN PGP SIGNATURE-
Version: GnuPG v1.4.5 (MingW32)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org
iD8DBQFFfZ8KZmlc6wNjtLYRCEsTAJ0YF/5/enV2w7ibvjSYENTdKjZs3QCgophl
tZVTZsrFceHD3f+KKn6Drqo=
=zhwv
-END PGP SIGNATURE-
---(end of broadcast)---
TIP 4: Have you searched our list archives?
http://archives.postgresql.org
Re: [DOCS] Switching to XML
On Mon, 2006-12-11 at 13:10 -0500, David Blewett wrote:
> -BEGIN PGP SIGNED MESSAGE-
> Hash: SHA256
>
> Peter Eisentraut wrote:
> > Right. So using the XSL(T) stylesheet instead of the DSSSL stylesheet
> > would
> > be a step in the right direction. Actually the 8.2 branch currently only
> > has
> > an XSLT stylesheet for HTML output. In 8.3devel I've added one for XSL-FO
> > output, which you can invoke by "make postgres-{A4|US}.fo". (You will
> > probably want yet a different paper format for your book.)
>
> Excuse my ignorance, but I thought XSLT stylesheets can only be used
> on XML files?
AFAIK they can only be used on XML files, but you can get XML from the
postgresql sgml sources by using make postgres.xml .
Of course your changes that you make from release to release for volumes
won't be permanent and we will continue to waste time because people
have an odd affection for SGML like it was some kind of pet dog.
Joshua D. Drake
>
> David Blewett
>
> -BEGIN PGP SIGNATURE-
> Version: GnuPG v1.4.5 (MingW32)
> Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org
>
> iD8DBQFFfZ8KZmlc6wNjtLYRCEsTAJ0YF/5/enV2w7ibvjSYENTdKjZs3QCgophl
> tZVTZsrFceHD3f+KKn6Drqo=
> =zhwv
> -END PGP SIGNATURE-
>
> ---(end of broadcast)---
> TIP 4: Have you searched our list archives?
>
>http://archives.postgresql.org
>
--
=== The PostgreSQL Company: Command Prompt, Inc. ===
Sales/Support: +1.503.667.4564 || 24x7/Emergency: +1.800.492.2240
Providing the most comprehensive PostgreSQL solutions since 1997
http://www.commandprompt.com/
Donate to the PostgreSQL Project: http://www.postgresql.org/about/donate
---(end of broadcast)---
TIP 5: don't forget to increase your free space map settings
Re: [DOCS] Authoring Tools WAS: Switching to XML
"Joshua D. Drake" <[EMAIL PROTECTED]> writes: >> 1) a) is there some way we can try various tools and check output? > OpenOffice.Org, WordPerfect, Kword, Abiword. The first two (last I > checked) were the only mature software supporting Docbook output. I tried opening postgres.xml in OpenOffice 2.0, and it just showed me the raw text and markup --- no indication that it understood xml at all. Is there some special incantation needed? regards, tom lane ---(end of broadcast)--- TIP 7: You can help support the PostgreSQL project by donating at http://www.postgresql.org/about/donate
Re: [DOCS] Authoring Tools WAS: Switching to XML
On Mon, 2006-12-11 at 13:34 -0500, Tom Lane wrote: > "Joshua D. Drake" <[EMAIL PROTECTED]> writes: > >> 1) a) is there some way we can try various tools and check output? > > > OpenOffice.Org, WordPerfect, Kword, Abiword. The first two (last I > > checked) were the only mature software supporting Docbook output. > > I tried opening postgres.xml in OpenOffice 2.0, and it just showed me > the raw text and markup --- no indication that it understood xml at all. > Is there some special incantation needed? I found that I had to remove the > regards, tom lane > -- === The PostgreSQL Company: Command Prompt, Inc. === Sales/Support: +1.503.667.4564 || 24x7/Emergency: +1.800.492.2240 Providing the most comprehensive PostgreSQL solutions since 1997 http://www.commandprompt.com/ Donate to the PostgreSQL Project: http://www.postgresql.org/about/donate ---(end of broadcast)--- TIP 9: In versions below 8.0, the planner will ignore your desire to choose an index scan if your joining column's datatypes do not match
Re: [DOCS] Switching to XML
On Sun, 2006-12-10 at 19:07 +0100, Peter Eisentraut wrote: > Joshua D. Drake wrote: > > The only thing I see is that you don't want to move because all the > > tools that are available for docbook sgml are also available for > > docbook xml. > > Link posted by David Blewett: > http://groups.google.com/group/pgsql.docs/browse_thread/thread/37ff3a011bb705d7 Per this link Peter you cite: """ - Marked sections don't work anymore; would need to use DocBook-specific profiling mechanism, which isn't all that elegant. - More typing: Things like foo and other abbreviations won't work anymore; all attributes would need to be quoted, etc. - doc/src/sgml/*.sgml will look silly for filenames. - Someone would need to do the conversion. I understand that the French translation team might have patches available. So that is it. In my mind, there is no clear winner, but if someone has a concrete need for XML, I don't see a problem with it. """ Your first disadvantage I can not comment on. Your second disadvantage is fixed with any reasonable editor including emacs. Your third comment is a filename change. Your fourth is resolved, we have the conversion per make postgres.xml. We could even reasonably break it all out again. I would add to advantages that: 1. We wouldn't have to have this discussion every six months :) 2. It will make life easier for regional projects as they are already going through the pain of moving to XML for each release. 3. It would help some sub projects including the printed documentation project that Blewitt and I are working on because we could submit our patches as XML directly back to the community. Lastly: There are several who have mentioned a concrete need. Is the need solved with the existing tools? Yes, but not without extra steps. So I would ask that you either give us further reason why you don't want to move to XML or honor what you say above, in that you don't have a problem with it. Sincerely, Joshua D. Drake -- === The PostgreSQL Company: Command Prompt, Inc. === Sales/Support: +1.503.667.4564 || 24x7/Emergency: +1.800.492.2240 Providing the most comprehensive PostgreSQL solutions since 1997 http://www.commandprompt.com/ Donate to the PostgreSQL Project: http://www.postgresql.org/about/donate ---(end of broadcast)--- TIP 4: Have you searched our list archives? http://archives.postgresql.org
Re: [DOCS] Authoring Tools WAS: Switching to XML
"Joshua D. Drake" <[EMAIL PROTECTED]> writes: > On Mon, 2006-12-11 at 13:34 -0500, Tom Lane wrote: >> I tried opening postgres.xml in OpenOffice 2.0, and it just showed me >> the raw text and markup --- no indication that it understood xml at all. >> Is there some special incantation needed? > I found that I had to remove the docbook dtd declartion. > Warning, it is ugly :) but it does indeed work. Only for exceedingly small values of "work". I tried that, and got a display showing all the text run together in a single paragraph. I changed one word and re-saved, and got a file that had basically nothing to do with the original --- it's been arbitrarily reformatted, and most of the original markup is gone. Perhaps later versions are better, but the OO version currently available in Fedora 5 appears utterly useless for our purposes. Can you show me an authoring tool that does *not* think it's OK to mangle the low-level text in "semantically irrelevant" ways? We might as well forget about the concept of a doc patch if people start using tools like this --- if a one-word change results in diffs across the whole file, the tool is not usable. regards, tom lane ---(end of broadcast)--- TIP 4: Have you searched our list archives? http://archives.postgresql.org
Re: [DOCS] Authoring Tools WAS: Switching to XML
> Can you show me an authoring tool that does *not* think it's OK to > mangle the low-level text in "semantically irrelevant" ways? No. :) I mentioned this previously. Any word processor is going to blow stuff away in an ugly way. The closest we could get is: Create a custom style in OpenOffice that works in a similar fashion to PostgreSQL. Use Tidy and or a custom script to clean after the fact. IMHO the only tools for Docbook that are usable are editors, preferrably validating editors such as Emacs, Bluefish (actually Word Perfect does this too). We are not going to get what we want out of WYSIWYG. > We might > as well forget about the concept of a doc patch if people start using > tools like this --- if a one-word change results in diffs across the > whole file, the tool is not usable. You are correct, we would have to run some kind of clean script and then diff between the two versions. Sincerely, Joshua D. Drake -- === The PostgreSQL Company: Command Prompt, Inc. === Sales/Support: +1.503.667.4564 || 24x7/Emergency: +1.800.492.2240 Providing the most comprehensive PostgreSQL solutions since 1997 http://www.commandprompt.com/ Donate to the PostgreSQL Project: http://www.postgresql.org/about/donate ---(end of broadcast)--- TIP 7: You can help support the PostgreSQL project by donating at http://www.postgresql.org/about/donate
Re: [DOCS] Authoring Tools WAS: Switching to XML
Josh, > Anything that you produce from a WYSWYG editor is going to have to be > massaged to work with PostgreSQL.Org docs. *sigh* too bad Lyx only writes DocBook and doesn't read it. > > * = an authoring tool is one which makes generation of the document > > easier/faster than hand-editing text files. No such tool exists for > > SGML -- even the Emacs toolkit merely does validation. > > What is it specifically you are looking for then? Because that is what > Docbook is, XML (or sgml) the only thing you need to do is validate. "Authoring Tool" means "not always hand-editing tags". Right now, I can't do anything with Emacs SGML that I couldn't do with Wordpad or Pico, except validate. Let me give you an example of a doc change which needing to hand-edit SGML prevented me from making: I wanted to clean up runtime.sgml by adding an alpha index, and clearly breaking out data like defaults, set time, etc. This meant changing 70% of the document, including some significant re-arranging. After 5 hours of editing, I discovered that I was only 1/3 done ... and that there had been incompatible changes in CVS in the meantime. I gave up. If the docs were WYSWYG-editable or if we had any authoring tool which would automatically fix tags, I would have been able to make the changes and submit a patch in < 4 hours, not 15 hours+ it would have taken to complete the project. -- --Josh Josh Berkus PostgreSQL @ Sun San Francisco ---(end of broadcast)--- TIP 4: Have you searched our list archives? http://archives.postgresql.org
Re: [DOCS] Authoring Tools WAS: Switching to XML
> "Authoring Tool" means "not always hand-editing tags". Right now, I can't > do anything with Emacs SGML that I couldn't do with Wordpad or Pico, > except validate. That is certainly not true. Emacs will correctly associate your tags without having to write those tags, if you use Emacs correctly. As will Bluefish. http://www.commandprompt.com/community/emacs_sgml/x108 Bluefish is a little easier with this IMHO but it gives the same capabilities. > > Let me give you an example of a doc change which needing to hand-edit SGML > prevented me from making: I wanted to clean up runtime.sgml by adding an > alpha index, and clearly breaking out data like defaults, set time, etc. > This meant changing 70% of the document, including some significant > re-arranging. > > After 5 hours of editing, I discovered that I was only 1/3 done ... and > that there had been incompatible changes in CVS in the meantime. I gave > up. Well the CVS issue will be one that always exists. > > If the docs were WYSWYG-editable or if we had any authoring tool which > would automatically fix tags, O.k. well you will you lost my support here. I guarantee you I would not submit patches if I had to work with problems associated with doing things in OpenOffice.Org format. I would not have a problem helping get a clean up script together that would work with Docbook output from OpenOffice.org though. Docbook is specifically designed for technical documentation. > I would have been able to make the changes > and submit a patch in < 4 hours, not 15 hours+ it would have taken to > complete the project. Wait... You want a tool to automatically fix tags? You do need to know Docbook to write the docs JoshB. That means you need to know which tags are relevant to what. Something like emacs will make this easier because it will tell you what tags are valid for each section of the document you are in. Sincerely, Joshua D. Drake > -- === The PostgreSQL Company: Command Prompt, Inc. === Sales/Support: +1.503.667.4564 || 24x7/Emergency: +1.800.492.2240 Providing the most comprehensive PostgreSQL solutions since 1997 http://www.commandprompt.com/ Donate to the PostgreSQL Project: http://www.postgresql.org/about/donate ---(end of broadcast)--- TIP 4: Have you searched our list archives? http://archives.postgresql.org
Re: [DOCS] Switching to XML
"Joshua D. Drake" <[EMAIL PROTECTED]> writes: > Your fourth is resolved, we have the conversion per make postgres.xml. We do not have that --- have you looked at the output? It's nigh unreadable. Same problem as with the authoring tools: that software doesn't think that formatting of the XML source text is important. regards, tom lane ---(end of broadcast)--- TIP 7: You can help support the PostgreSQL project by donating at http://www.postgresql.org/about/donate
Re: [DOCS] Switching to XML
On Mon, 2006-12-11 at 14:53 -0500, Tom Lane wrote: > "Joshua D. Drake" <[EMAIL PROTECTED]> writes: > > Your fourth is resolved, we have the conversion per make postgres.xml. > > We do not have that --- have you looked at the output? It's nigh > unreadable. You are correct which is actually the argument that Gleu made to me about moving to XML. I did find however that if you ran postgres.xml through tidy it cleaned things up nicely. Secondly the make postgres.xml would be a one time thing. I would happilly take the time to get postgres.xml into a format that was reasonable and similar to how we currently do the postgres.sgml docs. > Same problem as with the authoring tools: that software > doesn't think that formatting of the XML source text is important. Well not authoring editors though. Emacs or Bluefish won't blow that stuff away (just realized Bluefish doesn't validate :( ). > > regards, tom lane > -- === The PostgreSQL Company: Command Prompt, Inc. === Sales/Support: +1.503.667.4564 || 24x7/Emergency: +1.800.492.2240 Providing the most comprehensive PostgreSQL solutions since 1997 http://www.commandprompt.com/ Donate to the PostgreSQL Project: http://www.postgresql.org/about/donate ---(end of broadcast)--- TIP 7: You can help support the PostgreSQL project by donating at http://www.postgresql.org/about/donate
Re: [DOCS] Authoring Tools WAS: Switching to XML
Josh, > Wait... You want a tool to automatically fix tags? You do need to know > Docbook to write the docs JoshB. That means you need to know which tags > are relevant to what. Something like emacs will make this easier because > it will tell you what tags are valid for each section of the document > you are in. Sure, but that doesn't do any good if you want to cut-and-paste a section and fix the tags. Anyway, from the sound of it whether or not there are better authoring tools for XML than SGML is "undetermined pending further investigation." -- --Josh Josh Berkus PostgreSQL @ Sun San Francisco ---(end of broadcast)--- TIP 5: don't forget to increase your free space map settings
Re: [DOCS] Switching to XML
"Joshua D. Drake" <[EMAIL PROTECTED]> writes: > Secondly the make postgres.xml would be a one time thing. Agreed, the cost of conversion is one-time ... but it's not small. Aside from getting the files themselves converted, there's the effort for people to find, install, and learn suitable tools, not to mention come up to speed on the differences between xml and sgml. (I assume there are some significant ones, else why are we having this discussion?) The real problem here is that you've still failed to establish any sizable benefit from converting. As best I can tell at the moment, the acceptable options for editing XML will be about the same as they are for SGML: emacs, and not a lot else. I don't really see why I should have to start spelling out every closing tag for a no-op like that. regards, tom lane ---(end of broadcast)--- TIP 3: Have you checked our extensive FAQ? http://www.postgresql.org/docs/faq
Re: [DOCS] Switching to XML
On Mon, 2006-12-11 at 15:07 -0500, Tom Lane wrote: > "Joshua D. Drake" <[EMAIL PROTECTED]> writes: > > Secondly the make postgres.xml would be a one time thing. > > Agreed, the cost of conversion is one-time ... but it's not small. > Aside from getting the files themselves converted, there's the effort > for people to find, install, and learn suitable tools, not to mention > come up to speed on the differences between xml and sgml. (I assume > there are some significant ones, else why are we having this discussion?) Well this actually comes back to one of Peter's points :). You shouldn't need to update your tools. If you installed Docbook tools, it is going to come with DSSSL and XSL. OpenJade will process the XML as will any of the current db2, docbook2 etc.. scripts. As far as learning the differences between xml and sgml, they are very subtle because it is still Docbook. http://www.oreilly.com/catalog/docbook/chapter/book/appb.html http://www.docbook.org/tdg/en/html/ch02.html For most things that anyone would be doing, they will see extremely little difference. I didn't even notice the difference because I never used short tags. > The real problem here is that you've still failed to establish any > sizable benefit from converting. As best I can tell at the moment, > the acceptable options for editing XML will be about the same as they > are for SGML: emacs, and not a lot else. Well basically, editing :) any editor although some make it easier as I mentioned Emacs, BlueFish, Kate etc... The benefits are (in my mind): 1. At least some of our regionals are already using XML. Let's make it a little easier for them to do so. 2. It would make the new printed documentation project easier for David Blewitt (the guy that is doing it) 3. DocBook XML is where FOSS documentation is moving or has moved depending on the project. Should any project want to integrate any part of our docs to their docs or vice versa, it will be easier for them if we follow the similar standard of using Docbook XML. 4. Their is active and progressive development with XSL and Docbook. There is not (that I can see) the same level with DSSSL and Docbbok. 5. The format objects development (FOP) seems to be better maintained then the dblatex/db2latex/pdflatex stuff. FOP does not appear to work with SGML. 6. Nobody has really come up with a reason *not* to move to XML that can't easily be addressed. 7. And this may be ethereal but I do believe that if we were following in the footsteps of other FOSS projects we may be able to get writers from those projects. Even only 1 of them. > I don't really see why I > should have to start spelling out every closing tag for a no-op like > that. Fair enough but if you are using a decent editor, it will take care of that for you. To be honest. I do not care. I have zero preference to XML or SGML because I know them both. I do however care, when I have regionals and contributors trying to give to the community that are having difficulty doing so *because* we use SGML versus XML. It is enough for me, that I have PostgreSQLFR, Chile and the printed book project all clammoring for XML support to give more weight to their arguments. Each of the three have presented their specific problems with the SGML. Not to mention people such as Andrew Dunstan and the others. Maybe the people demand isn't the concern. Okay, but switching to XML is not hurting anyone. It's not like we are trying to change languages... only the DTD :) Sincerely, Joshua D. Drake > > regards, tom lane > -- === The PostgreSQL Company: Command Prompt, Inc. === Sales/Support: +1.503.667.4564 || 24x7/Emergency: +1.800.492.2240 Providing the most comprehensive PostgreSQL solutions since 1997 http://www.commandprompt.com/ Donate to the PostgreSQL Project: http://www.postgresql.org/about/donate ---(end of broadcast)--- TIP 6: explain analyze is your friend
Re: [DOCS] Switching to XML
> The real problem here is that you've still failed to > establish any sizable benefit from converting. As best I can > tell at the moment, the acceptable options for editing XML > will be about the same as they are for SGML: emacs, and not a > lot else. I don't really see why I should have to start > spelling out every closing tag for a no-op like that. Visual Studio has a *very* nice XML editor these days, and they don't do SGML... (ok, ok, that's a joke. It's true, sure, but it's not very relevant...) //Magnus ---(end of broadcast)--- TIP 6: explain analyze is your friend
Re: [DOCS] Switching to XML
On Mon, 2006-12-11 at 21:56 +0100, Magnus Hagander wrote: > > The real problem here is that you've still failed to > > establish any sizable benefit from converting. As best I can > > tell at the moment, the acceptable options for editing XML > > will be about the same as they are for SGML: emacs, and not a > > lot else. I don't really see why I should have to start > > spelling out every closing tag for a no-op like that. > > Visual Studio has a *very* nice XML editor these days, and they don't do > SGML... > > (ok, ok, that's a joke. It's true, sure, but it's not very relevant...) Actually it might be for Windows developers wishing to develop Windows specific sections. How does it work with Docbook? Sincerely, Joshua D. Drake > > //Magnus > > ---(end of broadcast)--- > TIP 6: explain analyze is your friend > -- === The PostgreSQL Company: Command Prompt, Inc. === Sales/Support: +1.503.667.4564 || 24x7/Emergency: +1.800.492.2240 Providing the most comprehensive PostgreSQL solutions since 1997 http://www.commandprompt.com/ Donate to the PostgreSQL Project: http://www.postgresql.org/about/donate ---(end of broadcast)--- TIP 4: Have you searched our list archives? http://archives.postgresql.org
Re: [DOCS] Switching to XML
-BEGIN PGP SIGNED MESSAGE- Hash: SHA256 Tom Lane wrote: > "Joshua D. Drake" <[EMAIL PROTECTED]> writes: >> Secondly the make postgres.xml would be a one time thing. > > Agreed, the cost of conversion is one-time ... but it's not small. > Aside from getting the files themselves converted, there's the effort > for people to find, install, and learn suitable tools, not to mention > come up to speed on the differences between xml and sgml. (I assume > there are some significant ones, else why are we having this discussion?) > > The real problem here is that you've still failed to establish any > sizable benefit from converting. As best I can tell at the moment, > the acceptable options for editing XML will be about the same as they > are for SGML: emacs, and not a lot else. I don't really see why I > should have to start spelling out every closing tag for a no-op like > that. > > regards, tom lane In regards to cost of conversion: The osx tool that the makefile uses to generate postgres.xml has more options available to tweak the output (not resolve external files into the main file, no newlines in tags, etc.) After adding a few of those options + htmltidy, the result is pretty close to the original SGML, barring a bare newline between 's for example. The benefit I'm talking about is the ability to do multiple indexes in one document, which is not possible with DSSSL. In order to do this, I would have to run the conversion *every time* I wanted to work on a new release of the manual to bookstores. David Blewett -BEGIN PGP SIGNATURE- Version: GnuPG v1.4.5 (MingW32) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org iD8DBQFFfci5Zmlc6wNjtLYRCFYwAJ45TMs/YY0RoxHi+oMCB7shPGghlQCfa+oA hDRctNczvnrFweSV4yI2lG0= =2NoW -END PGP SIGNATURE- ---(end of broadcast)--- TIP 5: don't forget to increase your free space map settings
Re: [DOCS] Switching to XML
On Mon, 2006-12-11 at 13:53, Tom Lane wrote: > "Joshua D. Drake" <[EMAIL PROTECTED]> writes: > > Your fourth is resolved, we have the conversion per make postgres.xml. > > We do not have that --- have you looked at the output? It's nigh > unreadable. Same problem as with the authoring tools: that software > doesn't think that formatting of the XML source text is important. Would this help: http://xmlindent.sourceforge.net/ I use it all the time at work, where we have LOTS of tools that make big one line xml files for us. ---(end of broadcast)--- TIP 1: if posting/reading through Usenet, please send an appropriate subscribe-nomail command to [EMAIL PROTECTED] so that your message can get through to the mailing list cleanly
Re: [DOCS] Switching to XML
David Blewett <[EMAIL PROTECTED]> writes: > The benefit I'm talking about is the ability to do multiple indexes > in one document, which is not possible with DSSSL. In order to do > this, I would have to run the conversion *every time* I wanted to > work on a new release of the manual to bookstores. Yeah, but for purely downstream work like that, what's the objection to just running the osx conversion? It seems to take just a few seconds. I'm still not seeing where we get return on our investment for converting the master source files from one format to the other. regards, tom lane ---(end of broadcast)--- TIP 1: if posting/reading through Usenet, please send an appropriate subscribe-nomail command to [EMAIL PROTECTED] so that your message can get through to the mailing list cleanly
Re: [DOCS] Switching to XML
> > > The real problem here is that you've still failed to > establish any > > > sizable benefit from converting. As best I can tell at > the moment, > > > the acceptable options for editing XML will be about the same as > > > they are for SGML: emacs, and not a lot else. I don't really see > > > why I should have to start spelling out every closing tag for a > > > no-op like that. > > > > Visual Studio has a *very* nice XML editor these days, and > they don't > > do SGML... > > > > (ok, ok, that's a joke. It's true, sure, but it's not very > > relevant...) > > Actually it might be for Windows developers wishing to > develop Windows specific sections. How does it work with Docbook? It works just fine with any XML inlcluding docbook. It does your basic syntax highlighting, autoindenting and things like that. You can teach it about things like docbook to get autocomplete on tags and attributes, but I don't know if anybody has done that (I certainly haven't). //Magnus ---(end of broadcast)--- TIP 1: if posting/reading through Usenet, please send an appropriate subscribe-nomail command to [EMAIL PROTECTED] so that your message can get through to the mailing list cleanly
Re: [DOCS] Switching to XML
"Magnus Hagander" <[EMAIL PROTECTED]> writes: >>> Visual Studio has a *very* nice XML editor these days, and >>> they don't do SGML... >>> >>> (ok, ok, that's a joke. It's true, sure, but it's not very >>> relevant...) >> >> Actually it might be for Windows developers wishing to >> develop Windows specific sections. How does it work with Docbook? > It works just fine with any XML inlcluding docbook. It does your basic > syntax highlighting, autoindenting and things like that. You can teach > it about things like docbook to get autocomplete on tags and attributes, > but I don't know if anybody has done that (I certainly haven't). How is it on the point of not introducing random reformatting into the XML source text? regards, tom lane ---(end of broadcast)--- TIP 4: Have you searched our list archives? http://archives.postgresql.org
Re: [DOCS] Switching to XML
> >>> Visual Studio has a *very* nice XML editor these days, and they > >>> don't do SGML... > >>> > >>> (ok, ok, that's a joke. It's true, sure, but it's not very > >>> relevant...) > >> > >> Actually it might be for Windows developers wishing to develop > >> Windows specific sections. How does it work with Docbook? > > > It works just fine with any XML inlcluding docbook. It does > your basic > > syntax highlighting, autoindenting and things like that. > You can teach > > it about things like docbook to get autocomplete on tags and > > attributes, but I don't know if anybody has done that (I > certainly haven't). > > How is it on the point of not introducing random reformatting > into the XML source text? it doesn't do it, period. Just to be clear, it's a XML *source* editor. Just like emacs, excpet prettier ;-) (and just for the record, these days even the GUI editors in Visual Studio generally do a very good job of not breaking your manually tuned markup, but there is no GUI editor for docbook) //Magnus ---(end of broadcast)--- TIP 4: Have you searched our list archives? http://archives.postgresql.org
Re: [DOCS] Switching to XML
David Blewett a écrit :
> Peter Eisentraut wrote:
>> Right. So using the XSL(T) stylesheet instead of the DSSSL stylesheet would
>> be a step in the right direction. Actually the 8.2 branch currently only
>> has
>> an XSLT stylesheet for HTML output. In 8.3devel I've added one for XSL-FO
>> output, which you can invoke by "make postgres-{A4|US}.fo". (You will
>> probably want yet a different paper format for your book.)
>
> Excuse my ignorance, but I thought XSLT stylesheets can only be used
> on XML files?
>
That's right. To use Peter's work, you need to checkout CVS HEAD, cd
into doc/src/sgml, "make postgres.xml" which build a valid XML file.
Next step depends on the output format you want to get. To get HTML
output from XSLT file, execute "make xslthtml". This target use
stylesheet.xsl which customizes a bit the XSLT stylesheets for XHTML
available from docbook.sourceforge.net. To get .fo output (required to
build a PDF file), "make postgres-A4.fo". This command will use the
stylesheet-fo.xsl file. This file is just a pointer to XSLT stylesheets
for PDF available from docbook.sourceforge.net. Simple but effective.
A summary :
* to build HTML manual with XSLT :
make postgres.xml
make xslthtml
* to build PDF manual with XSLT :
make postgres.xml
make postgres-A4.fo
fop.sh postgres-A4.fo postgres-A4.pdf
I think my fop install is broken because I'm not able to build the PDF
file...
Peter, if I said something stupid, please, tell it. This is just what I
understood from your mail and the Makefiles/xslt files you provide.
Regards.
--
Guillaume.
---(end of broadcast)---
TIP 6: explain analyze is your friend
Re: [DOCS] Switching to XML
-BEGIN PGP SIGNED MESSAGE- Hash: SHA256 Tom Lane wrote: > Yeah, but for purely downstream work like that, what's the objection to > just running the osx conversion? It seems to take just a few seconds. > > I'm still not seeing where we get return on our investment for > converting the master source files from one format to the other. > > regards, tom lane Does the designation of "downstream work" apply here? I was intending to contribute back any changes required, to enable anyone else to build the multiple volume version for printing. I wanted it to become an easily maintainable way for the project to have an up-to-date version of our manual available to bookstores, or directly available through lulu.com. I also would like to reiterate the fact that the localization efforts would appreciate not having to re-do their work for each release. Do we really want to continue considering this addition to the project as well as their work to be "second-class citizens" wrt the rest of the distribution? David Blewett -BEGIN PGP SIGNATURE- Version: GnuPG v1.4.5 (MingW32) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org iD8DBQFFfgg/Zmlc6wNjtLYRCK9pAKCtN+UDuiYMprloV6Kx9XM4X3jCXQCgvhZ3 sRgVSsSAwUhHhQ2aMMC4ehA= =XA3B -END PGP SIGNATURE- ---(end of broadcast)--- TIP 1: if posting/reading through Usenet, please send an appropriate subscribe-nomail command to [EMAIL PROTECTED] so that your message can get through to the mailing list cleanly
Re: [DOCS] Switching to XML
David Blewett <[EMAIL PROTECTED]> writes: > Does the designation of "downstream work" apply here? I was > intending to contribute back any changes required, to enable anyone > else to build the multiple volume version for printing. Changes required where? AFAICS the useful content of your work would probably be in the stylesheets, which there is already an XML version of. > I also would like to reiterate the fact that the localization > efforts would appreciate not having to re-do their work for each > release. How exactly does working from an osx translation rather than hand-edited sources handicap them? Or even more to the point, which part of their work don't they have to redo anyway? We certainly have never hesitated to whack the documentation around in small ways and large... regards, tom lane ---(end of broadcast)--- TIP 3: Have you checked our extensive FAQ? http://www.postgresql.org/docs/faq
Re: [DOCS] Switching to XML
Tom Lane a ecrit le 12/12/2006 02:47: David Blewett <[EMAIL PROTECTED]> writes: [...] I also would like to reiterate the fact that the localization efforts would appreciate not having to re-do their work for each release. How exactly does working from an osx translation rather than hand-edited sources handicap them? Or even more to the point, which part of their work don't they have to redo anyway? We certainly have never hesitated to whack the documentation around in small ways and large... I don't know for others but I think I can speak for the french team :) I also don't quite understand the whole point on the translation. I use Kompare to... hmmm... compare one release to another. I merge *manually* the differences, and then I translate them. I also need to transform SGML tags to XML tags ( stuff and no ending tags). Actually, the merge/translate step is much more difficult. If some projects prefer to use po (with xml2pot or po4all), "make postgres.xml" is the required step. The XML file built this way seems valid to me. Regards. -- Guillaume. ---(end of broadcast)--- TIP 5: don't forget to increase your free space map settings
Re: [DOCS] Switching to XML
Joshua D. Drake wrote: > 5. The format objects development (FOP) seems to be better maintained > then the dblatex/db2latex/pdflatex stuff. Check the facts. The latest stable FOP release was more than three years ago. The latest stable dblatex release was less than a month ago. -- Peter Eisentraut http://developer.postgresql.org/~petere/ ---(end of broadcast)--- TIP 9: In versions below 8.0, the planner will ignore your desire to choose an index scan if your joining column's datatypes do not match
