pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedRe: Authoring Tools WAS: Switching to XML
17+ messages / 7 participants
[nested] [flat]
* Re: Authoring Tools WAS: Switching to XML
@ 2006-12-11 17:54 Josh Berkus <josh@agliodbs.com>
0 siblings, 1 reply; 17+ messages in thread
From: Josh Berkus @ 2006-12-11 17:54 UTC (permalink / raw)
To: Peter Eisentraut <peter_e@gmx.net>; +Cc: Joshua D. Drake <jd@commandprompt.com>; David Fetter <david@fetter.org>; Guillaume Lelarge <guillaume@lelarge.info>; pgsql-docs
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
^ permalink raw reply [nested|flat] 17+ messages in thread
* Re: Authoring Tools WAS: Switching to XML
@ 2006-12-11 18:12 Joshua D. Drake <jd@commandprompt.com>
parent: Josh Berkus <josh@agliodbs.com>
0 siblings, 2 replies; 17+ messages in thread
From: Joshua D. Drake @ 2006-12-11 18:12 UTC (permalink / raw)
To: Josh Berkus <josh@agliodbs.com>; +Cc: Peter Eisentraut <peter_e@gmx.net>; David Fetter <david@fetter.org>; Guillaume Lelarge <guillaume@lelarge.info>; pgsql-docs
> 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
^ permalink raw reply [nested|flat] 17+ messages in thread
* Re: Authoring Tools WAS: Switching to XML
@ 2006-12-11 18:34 Tom Lane <tgl@sss.pgh.pa.us>
parent: Joshua D. Drake <jd@commandprompt.com>
1 sibling, 1 reply; 17+ messages in thread
From: Tom Lane @ 2006-12-11 18:34 UTC (permalink / raw)
To: Joshua D. Drake <jd@commandprompt.com>; +Cc: Josh Berkus <josh@agliodbs.com>; Peter Eisentraut <peter_e@gmx.net>; David Fetter <david@fetter.org>; Guillaume Lelarge <guillaume@lelarge.info>; pgsql-docs
"Joshua D. Drake" <jd@commandprompt.com> 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
^ permalink raw reply [nested|flat] 17+ messages in thread
* Re: Authoring Tools WAS: Switching to XML
@ 2006-12-11 18:40 Joshua D. Drake <jd@commandprompt.com>
parent: Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 1 reply; 17+ messages in thread
From: Joshua D. Drake @ 2006-12-11 18:40 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: Josh Berkus <josh@agliodbs.com>; Peter Eisentraut <peter_e@gmx.net>; David Fetter <david@fetter.org>; Guillaume Lelarge <guillaume@lelarge.info>; pgsql-docs
On Mon, 2006-12-11 at 13:34 -0500, Tom Lane wrote:
> "Joshua D. Drake" <jd@commandprompt.com> 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 <? xml declartion and only have the
docbook dtd declartion.
Warning, it is ugly :) but it does indeed work.
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
^ permalink raw reply [nested|flat] 17+ messages in thread
* Re: Authoring Tools WAS: Switching to XML
@ 2006-12-11 19:08 Tom Lane <tgl@sss.pgh.pa.us>
parent: Joshua D. Drake <jd@commandprompt.com>
0 siblings, 1 reply; 17+ messages in thread
From: Tom Lane @ 2006-12-11 19:08 UTC (permalink / raw)
To: Joshua D. Drake <jd@commandprompt.com>; +Cc: Josh Berkus <josh@agliodbs.com>; Peter Eisentraut <peter_e@gmx.net>; David Fetter <david@fetter.org>; Guillaume Lelarge <guillaume@lelarge.info>; pgsql-docs
"Joshua D. Drake" <jd@commandprompt.com> 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 <? xml declartion and only have 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
^ permalink raw reply [nested|flat] 17+ messages in thread
* Re: Authoring Tools WAS: Switching to XML
@ 2006-12-11 19:23 Joshua D. Drake <jd@commandprompt.com>
parent: Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 0 replies; 17+ messages in thread
From: Joshua D. Drake @ 2006-12-11 19:23 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: Josh Berkus <josh@agliodbs.com>; Peter Eisentraut <peter_e@gmx.net>; David Fetter <david@fetter.org>; Guillaume Lelarge <guillaume@lelarge.info>; pgsql-docs
> 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
^ permalink raw reply [nested|flat] 17+ messages in thread
* Re: Authoring Tools WAS: Switching to XML
@ 2006-12-11 19:27 Josh Berkus <josh@agliodbs.com>
parent: Joshua D. Drake <jd@commandprompt.com>
1 sibling, 1 reply; 17+ messages in thread
From: Josh Berkus @ 2006-12-11 19:27 UTC (permalink / raw)
To: Joshua D. Drake <jd@commandprompt.com>; +Cc: Peter Eisentraut <peter_e@gmx.net>; David Fetter <david@fetter.org>; Guillaume Lelarge <guillaume@lelarge.info>; pgsql-docs
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
^ permalink raw reply [nested|flat] 17+ messages in thread
* Re: Authoring Tools WAS: Switching to XML
@ 2006-12-11 19:36 Joshua D. Drake <jd@commandprompt.com>
parent: Josh Berkus <josh@agliodbs.com>
0 siblings, 1 reply; 17+ messages in thread
From: Joshua D. Drake @ 2006-12-11 19:36 UTC (permalink / raw)
To: josh@agliodbs.com; +Cc: Peter Eisentraut <peter_e@gmx.net>; David Fetter <david@fetter.org>; Guillaume Lelarge <guillaume@lelarge.info>; pgsql-docs
> "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
^ permalink raw reply [nested|flat] 17+ messages in thread
* Re: Authoring Tools WAS: Switching to XML
@ 2006-12-11 20:07 Josh Berkus <josh@agliodbs.com>
parent: Joshua D. Drake <jd@commandprompt.com>
0 siblings, 1 reply; 17+ messages in thread
From: Josh Berkus @ 2006-12-11 20:07 UTC (permalink / raw)
To: pgsql-docs; +Cc: Joshua D. Drake <jd@commandprompt.com>; Peter Eisentraut <peter_e@gmx.net>; David Fetter <david@fetter.org>; Guillaume Lelarge <guillaume@lelarge.info>
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
^ permalink raw reply [nested|flat] 17+ messages in thread
* Re: Authoring Tools WAS: Switching to XML
@ 2006-12-12 15:26 Peter Eisentraut <peter_e@gmx.net>
parent: Josh Berkus <josh@agliodbs.com>
0 siblings, 1 reply; 17+ messages in thread
From: Peter Eisentraut @ 2006-12-12 15:26 UTC (permalink / raw)
To: josh@agliodbs.com; +Cc: pgsql-docs@postgresql.org, "Joshua D. Drake" <jd@commandprompt.com>; David Fetter <david@fetter.org>; Guillaume Lelarge <guillaume@lelarge.info>
Josh Berkus wrote:
> Anyway, from the sound of it whether or not there are better
> authoring tools for XML than SGML is "undetermined pending further
> investigation."
I'll be the first to welcome better editing options, but so far I have
only heard them being theorized about.
--
Peter Eisentraut
http://developer.postgresql.org/~petere/
^ permalink raw reply [nested|flat] 17+ messages in thread
* Re: Authoring Tools WAS: Switching to XML
@ 2006-12-13 17:14 Bruce Momjian <bruce@momjian.us>
parent: Peter Eisentraut <peter_e@gmx.net>
0 siblings, 1 reply; 17+ messages in thread
From: Bruce Momjian @ 2006-12-13 17:14 UTC (permalink / raw)
To: Peter Eisentraut <peter_e@gmx.net>; +Cc: josh@agliodbs.com, pgsql-docs@postgresql.org, "Joshua D. Drake" <jd@commandprompt.com>; David Fetter <david@fetter.org>; Guillaume Lelarge <guillaume@lelarge.info>
I have read the two long XML threads, and see these issues for
converting to XML:
o authoring, in two parts:
o WYSIWYG - this seems unattainable because such editors are
going to modify the surrounding XML, which will affect
hand-edited changes
o tag assistance - this seems possible, e.g. tag completion,
drop down list of tags available for this section
o output generation - the XML toolchain is more widely used, but Tom has
fixed the performance issue we have had for years. The fact that the
tool maintainers were unable to fix it themselves reflects badly on
their maintenance of this toolchain.
o translation - does XML have better tools to assist in translating our
manuals, and is this better than outputting XML via our makefile?
It would be nice to use htmltidy to clean up the xml before each
release, but I wonder whether it understand the tags well enough to
provide better formatting than we do now manually.
Tom, I think we need that SGML patch placed on our ftp site and a
reference to it made in our documentation. I can do it of you want.
--
Bruce Momjian bruce@momjian.us
EnterpriseDB http://www.enterprisedb.com
+ If your life is a hard drive, Christ can be your backup. +
^ permalink raw reply [nested|flat] 17+ messages in thread
* Re: Authoring Tools WAS: Switching to XML
@ 2006-12-14 20:58 Josh Berkus <josh@agliodbs.com>
parent: Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 17+ messages in thread
From: Josh Berkus @ 2006-12-14 20:58 UTC (permalink / raw)
To: pgsql-docs; +Cc: Bruce Momjian <bruce@momjian.us>; Peter Eisentraut <peter_e@gmx.net>; Joshua D. Drake <jd@commandprompt.com>; David Fetter <david@fetter.org>; Guillaume Lelarge <guillaume@lelarge.info>
Bruce,
> o WYSIWYG - this seems unattainable because such editors are
> going to modify the surrounding XML, which will affect
> hand-edited changes
It would be more accurate to say that we have not identified a WYSWYG tool
which does not mess up the source. There may be one, it would just take a
fair amount of testing to find it.
> o tag assistance - this seems possible, e.g. tag completion,
> drop down list of tags available for this section
Yes, and graphically-enhanced tag support using XML IDEs. Command-line tag
completion is available via Emacs-SGML, but there are a lot more tools
which do it for XML (including Emacs).
--
--Josh
Josh Berkus
PostgreSQL @ Sun
San Francisco
^ permalink raw reply [nested|flat] 17+ messages in thread
* Re: Authoring Tools WAS: Switching to XML
@ 2006-12-14 21:23 Scott Marlowe <smarlowe@g2switchworks.com>
parent: Josh Berkus <josh@agliodbs.com>
0 siblings, 1 reply; 17+ messages in thread
From: Scott Marlowe @ 2006-12-14 21:23 UTC (permalink / raw)
To: josh@agliodbs.com; +Cc: pgsql-docs@postgresql.org, Bruce Momjian <bruce@momjian.us>; Peter Eisentraut <peter_e@gmx.net>; Joshua D. Drake <jd@commandprompt.com>; David Fetter <david@fetter.org>; Guillaume Lelarge <guillaume@lelarge.info>
On Thu, 2006-12-14 at 14:58, Josh Berkus wrote:
> Bruce,
>
> > o WYSIWYG - this seems unattainable because such editors are
> > going to modify the surrounding XML, which will affect
> > hand-edited changes
>
> It would be more accurate to say that we have not identified a WYSWYG tool
> which does not mess up the source. There may be one, it would just take a
> fair amount of testing to find it.
Is this strictly a question of indentation, or one of actually mangling
tags and such?
^ permalink raw reply [nested|flat] 17+ messages in thread
* Re: Authoring Tools WAS: Switching to XML
@ 2006-12-14 21:34 Tom Lane <tgl@sss.pgh.pa.us>
parent: Scott Marlowe <smarlowe@g2switchworks.com>
0 siblings, 2 replies; 17+ messages in thread
From: Tom Lane @ 2006-12-14 21:34 UTC (permalink / raw)
To: Scott Marlowe <smarlowe@g2switchworks.com>; +Cc: josh@agliodbs.com, pgsql-docs@postgresql.org, Bruce Momjian <bruce@momjian.us>; Peter Eisentraut <peter_e@gmx.net>; Joshua D. Drake <jd@commandprompt.com>; David Fetter <david@fetter.org>; Guillaume Lelarge <guillaume@lelarge.info>
Scott Marlowe <smarlowe@g2switchworks.com> writes:
> On Thu, 2006-12-14 at 14:58, Josh Berkus wrote:
>> It would be more accurate to say that we have not identified a WYSWYG tool
>> which does not mess up the source. There may be one, it would just take a
>> fair amount of testing to find it.
> Is this strictly a question of indentation, or one of actually mangling
> tags and such?
What we need is something that does not change regions of the file that
the user did not intend to modify. I think horizonal-white-space-only
changes could be worked around if the user is careful to use diff
--ignore-space-change when submitting the patch, but I suspect that an
editor that thinks it can mangle whitespace will also figure that it can
change line boundaries, and then diff will never be able to extract any
signal from that noise.
regards, tom lane
^ permalink raw reply [nested|flat] 17+ messages in thread
* Re: Authoring Tools WAS: Switching to XML
@ 2006-12-14 21:37 Scott Marlowe <smarlowe@g2switchworks.com>
parent: Tom Lane <tgl@sss.pgh.pa.us>
1 sibling, 0 replies; 17+ messages in thread
From: Scott Marlowe @ 2006-12-14 21:37 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: josh@agliodbs.com, pgsql-docs@postgresql.org, Bruce Momjian <bruce@momjian.us>; Peter Eisentraut <peter_e@gmx.net>; Joshua D. Drake <jd@commandprompt.com>; David Fetter <david@fetter.org>; Guillaume Lelarge <guillaume@lelarge.info>
On Thu, 2006-12-14 at 15:34, Tom Lane wrote:
> Scott Marlowe <smarlowe@g2switchworks.com> writes:
> > On Thu, 2006-12-14 at 14:58, Josh Berkus wrote:
> >> It would be more accurate to say that we have not identified a WYSWYG tool
> >> which does not mess up the source. There may be one, it would just take a
> >> fair amount of testing to find it.
>
> > Is this strictly a question of indentation, or one of actually mangling
> > tags and such?
>
> What we need is something that does not change regions of the file that
> the user did not intend to modify. I think horizonal-white-space-only
> changes could be worked around if the user is careful to use diff
> --ignore-space-change when submitting the patch, but I suspect that an
> editor that thinks it can mangle whitespace will also figure that it can
> change line boundaries, and then diff will never be able to extract any
> signal from that noise.
Ahhhh. I see.
Well, I don't mind teaching myself some docbook, but the first time I
looked at adding to the docs I was overwhelmed with what I didn't know,
and didn't even see a starting point. I'll look in the appendices and
see what I can see.
^ permalink raw reply [nested|flat] 17+ messages in thread
* Re: Authoring Tools WAS: Switching to XML
@ 2006-12-15 06:15 David Fetter <david@fetter.org>
parent: Tom Lane <tgl@sss.pgh.pa.us>
1 sibling, 1 reply; 17+ messages in thread
From: David Fetter @ 2006-12-15 06:15 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: Scott Marlowe <smarlowe@g2switchworks.com>; josh@agliodbs.com, pgsql-docs@postgresql.org, Bruce Momjian <bruce@momjian.us>; Peter Eisentraut <peter_e@gmx.net>; Joshua D. Drake <jd@commandprompt.com>; Guillaume Lelarge <guillaume@lelarge.info>
On Thu, Dec 14, 2006 at 04:34:06PM -0500, Tom Lane wrote:
> Scott Marlowe <smarlowe@g2switchworks.com> writes:
> > On Thu, 2006-12-14 at 14:58, Josh Berkus wrote:
> >> It would be more accurate to say that we have not identified a
> >> WYSWYG tool which does not mess up the source. There may be one,
> >> it would just take a fair amount of testing to find it.
>
> > Is this strictly a question of indentation, or one of actually
> > mangling tags and such?
>
> What we need is something that does not change regions of the file
> that the user did not intend to modify. I think
> horizonal-white-space-only changes could be worked around if the
> user is careful to use diff --ignore-space-change when submitting
> the patch, but I suspect that an editor that thinks it can mangle
> whitespace will also figure that it can change line boundaries, and
> then diff will never be able to extract any signal from that noise.
Could post-processing with tidy clean this up? I'm pretty sure that
tidy's output is deterministic, at least if the editor hasn't mangled
tags...
Cheers,
D
--
David Fetter <david@fetter.org> http://fetter.org/
phone: +1 415 235 3778 AIM: dfetter666
Skype: davidfetter
Remember to vote!
^ permalink raw reply [nested|flat] 17+ messages in thread
* Re: Authoring Tools WAS: Switching to XML
@ 2006-12-15 06:39 Joshua D. Drake <jd@commandprompt.com>
parent: David Fetter <david@fetter.org>
0 siblings, 0 replies; 17+ messages in thread
From: Joshua D. Drake @ 2006-12-15 06:39 UTC (permalink / raw)
To: David Fetter <david@fetter.org>; +Cc: Tom Lane <tgl@sss.pgh.pa.us>; Scott Marlowe <smarlowe@g2switchworks.com>; josh@agliodbs.com, pgsql-docs@postgresql.org, Bruce Momjian <bruce@momjian.us>; Peter Eisentraut <peter_e@gmx.net>; Guillaume Lelarge <guillaume@lelarge.info>
> > What we need is something that does not change regions of the file
> > that the user did not intend to modify. I think
> > horizonal-white-space-only changes could be worked around if the
> > user is careful to use diff --ignore-space-change when submitting
> > the patch, but I suspect that an editor that thinks it can mangle
> > whitespace will also figure that it can change line boundaries, and
> > then diff will never be able to extract any signal from that noise.
>
> Could post-processing with tidy clean this up? I'm pretty sure that
> tidy's output is deterministic, at least if the editor hasn't mangled
> tags...
>
Yes tidy makes things pretty darn clean. However, there is one thing
that it won't do and that is remove extra tags. Thus something like
OpenOffice is still a no-op.
Joshua D. Drake
> Cheers,
> D
--
=== 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
^ permalink raw reply [nested|flat] 17+ messages in thread
end of thread, other threads:[~2006-12-15 06:39 UTC | newest]
Thread overview: 17+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2006-12-11 17:54 Re: Authoring Tools WAS: Switching to XML Josh Berkus <josh@agliodbs.com>
2006-12-11 18:12 ` Joshua D. Drake <jd@commandprompt.com>
2006-12-11 18:34 ` Tom Lane <tgl@sss.pgh.pa.us>
2006-12-11 18:40 ` Joshua D. Drake <jd@commandprompt.com>
2006-12-11 19:08 ` Tom Lane <tgl@sss.pgh.pa.us>
2006-12-11 19:23 ` Joshua D. Drake <jd@commandprompt.com>
2006-12-11 19:27 ` Josh Berkus <josh@agliodbs.com>
2006-12-11 19:36 ` Joshua D. Drake <jd@commandprompt.com>
2006-12-11 20:07 ` Josh Berkus <josh@agliodbs.com>
2006-12-12 15:26 ` Peter Eisentraut <peter_e@gmx.net>
2006-12-13 17:14 ` Bruce Momjian <bruce@momjian.us>
2006-12-14 20:58 ` Josh Berkus <josh@agliodbs.com>
2006-12-14 21:23 ` Scott Marlowe <smarlowe@g2switchworks.com>
2006-12-14 21:34 ` Tom Lane <tgl@sss.pgh.pa.us>
2006-12-14 21:37 ` Scott Marlowe <smarlowe@g2switchworks.com>
2006-12-15 06:15 ` David Fetter <david@fetter.org>
2006-12-15 06:39 ` Joshua D. Drake <jd@commandprompt.com>
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