discuss: simplify documentation maintenance
Subject:
simplify documentation maintenance
From:
Claudio Greco ####@####.####
Date:
31 Aug 2005 10:21:41 -0000
Message-Id: <20050831102114.72537.qmail@web33415.mail.mud.yahoo.com>
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
