[GENERAL] Editor for sgml files
Richard Broersma
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-...@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-general
Greg Smith
> 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 gsm...@gregsmith.com http://www.gregsmith.com Baltimore, MD
David Fetter
> 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 <da...@fetter.org> http://fetter.org/
Phone: +1 415 235 3778 AIM: dfetter666 Yahoo!: dfetter
Skype: davidfetter XMPP: david....@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
Bill Moran
>
> 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
Richard Broersma
> 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
--
Richard Broersma
> 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
--
David Fetter
> On Mon, Nov 9, 2009 at 10:34 PM, David Fetter <da...@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 <da...@fetter.org> http://fetter.org/
Phone: +1 415 235 3778 AIM: dfetter666 Yahoo!: dfetter
Skype: davidfetter XMPP: david....@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
--
Peter Eisentraut
> 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.
Richard Broersma
> 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
--
Peter Eisentraut
> On Tue, Nov 10, 2009 at 2:04 PM, Peter Eisentraut <pet...@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.
Bill Moran
> * 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/
Peter Eisentraut
> In response to Peter Eisentraut <pet...@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". ;-)