discuss: Thread: 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


		
____________________________________________________
Start your day with Yahoo! - make it your home page 
http://www.yahoo.com/r/hs 
 

> -----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