This is the mail archive of the docbook@lists.oasis-open.org mailing list for the DocBook project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]

Re: modular architecture with DocBook


/ Bács Andrea <andi@cardinal.hu> was heard to say:
| 	My aim is to construct well structured documents in highly modular way from
| very small standard parts, which contain the most elementary operation
| descriptions, written in separate files. By this way could be handled the
| description of a continuously changing system. The whole document has to be

I've always found the most fundamental challenge in systems like this
is one of authoring. If you can get your authors to write things so
that they make sense when pasted together in orders other than the one
the author had in mind, you're 90% of the way there.

| built about a given scheme and different parameters,  like a tree structure,
| from these modular parts. The output must be a HTML Help, and a printable
| good-looking document format. XSL stylesheets would be preferred to get this
| output because our firm has a little bit experience using it in home banking
| system development.

Someone recently contributed an XSL stylesheet that produces HTML Help.

| My questions:
| Is DocBook suitable to realise this kind of structure: document which
| contains links to its subdocuments (in separate files) to the downmost,
| elementary (parapgraph) level?

You're building a fairly sophisticated processing system on top of the
markup. The extent to which DocBook is a good choice for the markup
depends in part on what sort of things you're documenting. If it's
computer hardware or software, it's probably an ideal choice.

| Is it possible to use marked sections, 

Not in XML.

| or express different conditions on
| attributes and entities, to include (or ignore ) during compiling some parts
| of the documentation?

Sure, there are many effectivity attributes in DocBook, and you could
add more of them in a customization layer if you needed them.

| Do I have to write a costumization of DocBook, or the DTD already includes
| some possibilities, that enable these condition formulations?

Built in, you've got 

<!ENTITY % arch.attrib
	--Arch: Computer or chip architecture to which element applies; no 
	default--
	"Arch		CDATA		#IMPLIED">

<!ENTITY % condition.attrib
	--Condition: General-purpose effectivity attribute--
	"Condition	CDATA		#IMPLIED">

<!ENTITY % conformance.attrib
	--Conformance: Standards conformance characteristics--
	"Conformance	NMTOKENS	#IMPLIED">

<!ENTITY % os.attrib
	--OS: Operating system to which element applies; no default--
	"OS		CDATA		#IMPLIED">

<!ENTITY % revision.attrib
	--Revision: Editorial revision to which element belongs; no default--
	"Revision	CDATA		#IMPLIED">

<!ENTITY % security.attrib
	--Security: Security classification; no default--
	"Security	CDATA		#IMPLIED">

<!ENTITY % userlevel.attrib
	--UserLevel: Level of user experience to which element applies; no 
	default--
	"UserLevel	CDATA		#IMPLIED">

<!ENTITY % vendor.attrib
	--Vendor: Computer vendor to which element applies; no default--
	"Vendor		CDATA		#IMPLIED">


| Can somebody give me advice: which Tool to use for writing documents and
| stylesheets,

Depends what platforms it has to run on and whether you want free tools
or have a budget. IMHO, nothing beats Emacs+PSGML-mode (or my own
DocBook IDE mode hack, for that matter) as a free, cross-platform tool.
Arbortext and SoftQuad both make commercial tools for editing XML.
(As do others, I'm sure.)

| to generate the mentioned HTML output? The handling of special
| (hungarian) characters is a must.

XSL is almost surely the way to go. The DocBook XSL Stylesheets
now support Hungarian, but I haven't any experience with Hungarian
so there may be issues I'm unware of. Please report them, if there
are.

| Spelling check in hungarian is also
| welcome. 

Uhm. Well, that'd be an authoring issue. I wouldn't be surprised to
learn that (one of) the Emacs spell checkers supports Hungarian, but
I've never had cause to check.

| What about intelligent version management methods and tools for DocBook
| documents?

CVS is your friend. OTOH, if you have cash to spend, there are lots of
companies selling high-end document management systems that understand
XML. And for an application as complex as yours, they might offer
significant benefits.

| XML Spy and XMetal can import MS Word documents, but without images and
| without structure. There are also problems with special character's and
| link's handling. As I see, it's good only for text import. Does anybody know
| a better way?

Dragging unstructured markup uphill is always painful. It just can't be
done by machine. Arbortext has a nice integration/UI for dragging word
documents uphill in a semi-automatic manner (disclaimer: I used to work
for Arbortext so I'm not unbiased.)

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | That which we call sin in others,
http://www.oasis-open.org/docbook/ | is experiment for us.--Emerson
Chair, DocBook Technical Committee |

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]