discuss: simplify documentation maintenance
Subject:
Re: [discuss] simplify documentation maintenance
From:
"David Horton" ####@####.####
Date:
31 Aug 2005 12:52:06 -0000
Message-Id: <W9209112896230491125492725@webmail4>
> -----Original Message-----
> From: Claudio Greco ####@####.####
> Sent: Wednesday, August 31, 2005 10:21 AM
> To: 'TLDP'
> Subject: [discuss] simplify documentation maintenance
>
> Hi,
>
> I've just subscribed to this list and plan to start a
> documentation project using Emacs/PSGML + DocBook.
> I would like to receive from you some feedback.
>
> I plan to split my doc into several XML entities for
> easier maintenance, but I don't like the way PSGML
> deals with them: its behavior is unpredictable and I
> have to set sgml-parent-document for every entity.
>
> From what I understand, serious documentation
> development is done with the tools I mentioned, so I
> was wondering whether you are using different
> techniques to overcome these issues.
>
> Now, there are three kinds of feedback I suppose I can
> get:
>
> 1. You're wrong: PSGML is not unpredictable
> I'm not very experienced with PSGML so I'm willing to
> change my mind...
> In any case I'm using a Debian installation with Emacs
> and PSGML packages, so any problems I'm having are not
> due to a buggy installation.
> With "unpredictable" I mean that most of the times C-c
> C-e does not work correctly when I'm editing the
> entity.
>
> 2. You're wrong: PSGML-based doc is not
> unmaintainable.
> The reason why I say it is unmaintainable is because
> I'm forced to set sgml-parent-document (using a
> comment at the end of the entity) for every entity
> but each entity can belong to several parents at the
> same time.
>
> 3. Do not use entity references, use other inclusion
> techniques...
>
>
> In any case, I want to use a DTD-aware editor so that:
> - I'm guided to writing a valid document
> - The editor must suggest me which elements are valid
> at each point (kind of PSGML C-c C-e)
>
>
> I thank you in advance!
>
> Claudio
>
Claudio,
I am a big fan of XMLMind's XML Editor for DocBook XML. It validates
your document against the DTD and will not let you do anything invalid.
It also handles documents that are split into multiple files. Their
web page [http://xmlmind.com/xmleditor] does a good job of describing
the features. There is also a tutorial at: http://www.happy-monkey.net/docbook/gui-editor.html.
Dave
