Thread: Editor for sgml files
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.) -- Regards, Richard Broersma Jr. Visit the Los Angeles PostgreSQL Users Group (LAPUG) http://pugs.postgresql.org/lapug -- Sent via pgsql-general mailing list (pgsql-general@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-general
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/> * GNU Coding Standards, section Documentation <http://www.gnu.org/prep/standards/standards.html#Documentation> * 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". ;-)