Subject: Doc <synopsis> changes

From: Rod Taylor <[email-masked]>
Date: 23 Feb 2003 10:44:54 -0500

I needed to make the synopsis areas more consistent for a side project. 
By far the simplest way to do that was to change them into <cmdsynopsis>
entities.

Benefits include increased consistency in spacing and formatting, nice
<synopfragment> linkouts (click the (1)), and the ability to share
code.  It may be possible to generate railroad diagrams from the marked
up copy. 

The biggest problem is you cannot indent sections anymore, but that may
be correctable with a stylesheet change.

New CREATE TABLE:
http://www.rbt.ca/docs/reference/sql-createtable.html#SQL-CREATETABLE-REFERENCES-FRAGMENT

Old CREATE TABLE:
http://candle.pha.pa.us/main/writings/pgsql/sgml/sql-createtable.html

Patch submitted to -patches. Another pass will be made for formatting
details if this method is accepted.

Yes, I've updated psql's create_help.pl to deal with the SGML formatted
areas.

-- 
Rod Taylor <[email-masked]>

PGP Key: http://www.rbt.ca/rbtpub.asc

---

From: Peter Eisentraut <[email-masked]>
Date: Sun, 23 Feb 2003 20:57:55 +0100 (CET)

> http://www.rbt.ca/docs/reference/sql-createtable.html#SQL-CREATETABLE-REFERENCES-FRAGMENT

Sorry, but that is very ugly.  Unless you also provide stylesheet updates
with this, I don't think we can accept that.

-- 
Peter Eisentraut   [email-masked]

---

From: Rod Taylor <[email-masked]>
Date: 23 Feb 2003 15:01:51 -0500

> with this, I don't think we can accept that.

Agreed, it's ugly.  I have a decent stylesheet -- but it's an XSLT. I'll
see what I can do about updating the dsssl.

-- 
Rod Taylor <[email-masked]>

---

From: Rod Taylor <[email-masked]>
Date: 27 Feb 2003 11:54:42 -0500

> with this, I don't think we can accept that.

Minor changes made to indenting.

Cleaned up a good chunk of the 'repeatable' elements to be clearer.

Anyway, I think it looks as good as the old version did -- but could be
wrong ;)  Any further suggestions?

I link to createtable, as it is the poorest of the set.

NOTE: The change of brackets on the CREATE CONSTRAINT TRIGGER change.

They're quoted in the original -- but that isn't how one types in the
function name. 

Any suggestions on further formatting or style?

-- 
Rod Taylor <[email-masked]>

---

From: Peter Eisentraut <[email-masked]>
Date: Fri, 28 Feb 2003 13:43:16 +0100 (CET)

> wrong ;)  Any further suggestions?

I think the cmdsynopsis element is fundamentally unsuitable for SQL
commands, because their syntax isn't simply command + arguments.

---

From: Rod Taylor <[email-masked]>
Date: 28 Feb 2003 08:35:36 -0500

> commands, because their syntax isn't simply command + arguments.

Hmm.. wish you would have said that the first time.  Anyway, I've
accomplished what I was asked to, so I'll leave it at that.

Thanks for your thoughts.

-- 
Rod Taylor <[email-masked]>