Editor for sgml files

On Mon, 9 Nov 2009, Richard Broersma wrote:

Out of curiosity, what are the favorite editor for authoring the
PostgreSQL document sgml files?

http://developer.postgresql.org/pgdocs/postgres/docguide-authoring.html

--
* Greg Smith gsmith@gregsmith.com http://www.gregsmith.com Baltimore, MD

On Mon, Nov 09, 2009 at 06:09:19PM -0800, Richard Broersma wrote:

Out of curiosity, what are the favorite editor for authoring the
PostgreSQL document sgml files? (I would be shocked if the whole
thing was developed from scratch using a simple text editor.)

You might be, but that's approximately what happened. Common editors
for this task are Emacs and Vim, each of which has varying levels of
support for SGML :)

Cheers,
David.
--
David Fetter <david@fetter.org> http://fetter.org/
Phone: +1 415 235 3778 AIM: dfetter666 Yahoo!: dfetter
Skype: davidfetter XMPP: david.fetter@gmail.com
iCal: webcal://www.tripit.com/feed/ical/people/david74/tripit.ics

Remember to vote!
Consider donating to Postgres: http://www.postgresql.org/about/donate

David Fetter <david@fetter.org> wrote:

On Mon, Nov 09, 2009 at 06:09:19PM -0800, Richard Broersma wrote:

Out of curiosity, what are the favorite editor for authoring the
PostgreSQL document sgml files? (I would be shocked if the whole
thing was developed from scratch using a simple text editor.)

You might be, but that's approximately what happened. Common editors
for this task are Emacs and Vim, each of which has varying levels of
support for SGML :)

As an FYI, I've been working with Netbeans a bit recently, and it actually
has pretty good support for SGML/XML-ish files. Shows you when you're
missing end tags and the like.

Might not be for everyone, but just an option thrown in the mix.

--
Bill Moran
http://www.potentialtech.com

On Mon, Nov 9, 2009 at 9:21 PM, Greg Smith <gsmith@gregsmith.com> wrote:

On Mon, 9 Nov 2009, Richard Broersma wrote:

Out of curiosity,  what are the favorite editor for authoring the
PostgreSQL document sgml files?

http://developer.postgresql.org/pgdocs/postgres/docguide-authoring.html

I'll have to take a look. Thanks!

--
Regards,
Richard Broersma Jr.

Visit the Los Angeles PostgreSQL Users Group (LAPUG)
http://pugs.postgresql.org/lapug

On Mon, Nov 9, 2009 at 10:34 PM, David Fetter <david@fetter.org> wrote:

You might be, but that's approximately what happened.  Common editors
for this task are Emacs and Vim, each of which has varying levels of
support for SGML :)

That is amazing. The layout and organization of the PostgreSQL manual
(to me) is superior to most other reference documents that I view.

Was there some sort of specification for the create of these documents
or was it simply the implementation of good practices? I notice for
example all reference pages have a consistent layout.

--
Regards,
Richard Broersma Jr.

Visit the Los Angeles PostgreSQL Users Group (LAPUG)
http://pugs.postgresql.org/lapug

On Tue, Nov 10, 2009 at 06:23:16AM -0800, Richard Broersma wrote:

On Mon, Nov 9, 2009 at 10:34 PM, David Fetter <david@fetter.org> wrote:

You might be, but that's approximately what happened. �Common editors
for this task are Emacs and Vim, each of which has varying levels of
support for SGML :)

That is amazing. The layout and organization of the PostgreSQL manual
(to me) is superior to most other reference documents that I view.

I suspect it's from steely discipline, attention to quality, and the
toolkits themselves.

Was there some sort of specification for the create of these documents
or was it simply the implementation of good practices? I notice for
example all reference pages have a consistent layout.

Well, there's the whole Docbook thing, which was pretty well thought
out. Apart from that, I don't know. Peter?

Cheers,
David.
--
David Fetter <david@fetter.org> http://fetter.org/
Phone: +1 415 235 3778 AIM: dfetter666 Yahoo!: dfetter
Skype: davidfetter XMPP: david.fetter@gmail.com
iCal: webcal://www.tripit.com/feed/ical/people/david74/tripit.ics

Remember to vote!
Consider donating to Postgres: http://www.postgresql.org/about/donate

On tis, 2009-11-10 at 07:00 -0800, David Fetter wrote:

Well, there's the whole Docbook thing, which was pretty well thought
out. Apart from that, I don't know. Peter?

Well, a lot of hard work. ;-) Just like there are coding standards and
best practices, there are standards and customs in writing and
publishing.

On Tue, Nov 10, 2009 at 2:04 PM, Peter Eisentraut <peter_e@gmx.net> wrote:

Well, a lot of hard work. ;-)  Just like there are coding standards and
best practices, there are standards and customs in writing and
publishing.

Are these published anywhere?

--
Regards,
Richard Broersma Jr.

Visit the Los Angeles PostgreSQL Users Group (LAPUG)
http://pugs.postgresql.org/lapug

On tis, 2009-11-10 at 14:10 -0800, Richard Broersma wrote:

On Tue, Nov 10, 2009 at 2:04 PM, Peter Eisentraut <peter_e@gmx.net> wrote:

Well, a lot of hard work. ;-) Just like there are coding standards and
best practices, there are standards and customs in writing and
publishing.

Are these published anywhere?

Um, well, that's like asking, how can I write good programs. ;-)

Off the top of my head, some sources I have found useful over the years:

* FreeBSD Documentation Project <http://www.freebsd.org/docproj/&gt;

* GNU Coding Standards, section Documentation
<http://www.gnu.org/prep/standards/standards.html#Documentation&gt;

* man-pages(7), which I adapted into our own style guide:
http://developer.postgresql.org/pgdocs/postgres/docguide-style.html

* The Elements of Style

* The Chicago Manual of Style

* Various publishers I have worked with over the years have the own
style guidelines.

Also, just like open-source projects adopt certain practices that make
the code more suitable for collaborative development, similar practices
can be found for collaborative documentation writing, e.g., version
control, frequent rebuilds and tests, consistent interfaces, robust
tools, etc.

In response to Peter Eisentraut <peter_e@gmx.net>:

* The Elements of Style

Hope this doesn't start a flame war, but:
http://chronicle.com/article/50-Years-of-Stupid-Grammar/25497

--
Bill Moran
http://www.potentialtech.com
http://people.collaborativefusion.com/~wmoran/

On ons, 2009-11-11 at 08:32 -0500, Bill Moran wrote:

In response to Peter Eisentraut <peter_e@gmx.net>:

* The Elements of Style

Hope this doesn't start a flame war, but:
http://chronicle.com/article/50-Years-of-Stupid-Grammar/25497

Yeah, you need to be prepared to reject about 30% of the advice and
guidelines in each of the sources I mentioned.

However, some of the prescriptionism in these various style guides that
a writer or journalist might ordinarily complain about is actually a
good idea for open-source documentation writing, because it enforces
consistency. For similar reasons we have commenting and indentation and
portability conventions, even though purists might complain about "35
years of stupid C code". ;-)