RE: DOCBOOK-APPS: Best Practices

[Kenneth Johansson <ke-joh at sectra dot se>]

I don't know if we should continue this offlist?

 

I have a scenario which might shed light on what I need in a markup guide.

 

Example from http://www.dpawson.co.uk/docbook/markup.html :

You make a cross reference by identifying where you want to go, and then making a link to it. To identify where you want to go, you add an id attribute to the element you are targeting. An id attribute is a simple text string without spaces that uniquely identifies that element in your document. Each id attribute has to be unique within your document, or your document won't validate. For example, if you want to cross reference to a table of sales figures, you add the id attribute to the table start tag like this:

<table id="MyJulySales">

To form a link to that table, you have two DocBook elements to choose from. In both cases you add a linkend attribute whose value is the id of the element you are pointing to. The two elements are xref and link.

Here we have the "id" attribute. In DocBook there is no simple attribute-tag, but there are the parameter, option and varname tags. Did I forget any? Which one should I use to markup the "id" attribute?

 

What tags to combine and in what order they should be combined is something I think my users would appreciate.

 

best regards,

 

/Kenneth

 

 

-----Original Message-----
From: Kenneth Johansson [mailto:ke-joh at sectra dot se]
Sent: Tuesday, February 25, 2003 19:20
To: Sean Wheller; docbook-apps at lists dot oasis-open dot org
Subject: RE: DOCBOOK-APPS: Best Practices

Hi,

 

Good points!

 

I'm familiar with the KDE Markup guide. What I need is that and more; a guide that tells the user in which order they should place tags, to get the best looking content when processing the files.

 

Your <graphic/> example is a nice example. I'll have more on this tomorrow.

 

regards,

 

/Kenneth 

-----Original Message-----
From: Sean Wheller [mailto:swheller at bigpond dot net dot au]
Sent: Tuesday, February 25, 2003 16:42
To: Kenneth Johansson; docbook-apps at lists dot oasis-open dot org
Subject: RE: DOCBOOK-APPS: Best Practices

Thanks Kenneth,

 

The foundation for markup is provided by the docbook TDG. So perhaps we should clarify what/why the markup guide is required. The way I see it, there are some things people will want their authors to use and some that they will not. To remain consistent, authors should adhere to some agreed convention. Something like coding guidelines for programming.

For example: graphics, you may just use the <graphic/> element or you may want people to use the full hog <mediaobject> and all. Many such instances exist. The idea of the markup guide for me is to provide a working baseline that can be customized as required. It should not be as in-depth as the TDG, if people want detail they should use the TDG.

 

A little example of the markup guide concept can be glimpsed at the KDE project http://i18n.kde.org/doc/markup/index.html . They also have some other ideas, like the crash course to docbook.

 

Your thoughts appreciated.

 

BTW. Can anyone suggest a place where we can store the files on CVS?

 

Sean Wheller

 -----Original Message-----
From: Kenneth Johansson [mailto:ke-joh at sectra dot se]
Sent: Tuesday, February 25, 2003 8:19 PM
To: Sean Wheller; docbook-apps at lists dot oasis-open dot org
Subject: RE: DOCBOOK-APPS: Best Practices

Hi,

 

I am willing to help out. I have very little experience with DocBook but I need to produce a Markup/Style Guide very soon. I have begun but I find it very difficult to explain best practices in markup since I don't have any experience.

 

regards,

 

/Kenneth

-----Original Message-----
From: Sean Wheller [mailto:swheller at bigpond dot net dot au]
Sent: Sunday, February 23, 2003 04:02
To: docbook-apps at lists dot oasis-open dot org
Subject: DOCBOOK-APPS: Best Practices

Hello all,

 

Is anyone maintaining a "Best Practices" to do with developing an XML Authoring system?

 

To explain:

 

For non-technical persons, or those short on time, who already realize the benefit of XML Authoring, the implementation process can seem to be complex and lengthy. Often this would result in management concluding that while long-term benefit can be demonstrated, the cost and risk associated with implementation of an XML Authoring system is prohibitively costly and risky. That benefit will not be attained for the short to medium term.

 

In an effort to reduce the barrier to entry I would like to develop a document called  "Best Practices for Implementation of an XML Authoring". This document is a not a business case. Rather it is an addendum to the business case. The document assumes that a business case has been demonstrated and that the solution will include the use of DocBook XML DTD or Scheme. As a by product, the document may provide input or insight to enable more accurate assessment of the cost involved.

 

The purpose of the document is to demonstrate a readily available, acceptable solution, cost optimized and implemental within a reasonable time frame of six months. The content should assist in fast tracking the implementation by providing "Best Practices" or a "Standard" by which to measure and select systems/methods:

• Desktop Tool chain
• Revision Control
• Database Storage
• Translation System
• Porting Legacy to XML
• Training Authors
• Markup Guide
• Style Guide

If I have left anything out, please let me know.

 

Naturally I have been able to locate some of this information by reading across a number of Web Sites, but I cannot find a single resource that is made credible by way of community backing. Some Web Sites are maintained by people on doc-book-apps and generally I can consider them useful input. Others are not and generally have a marketing bias. While many articles concur with one another, they generally have conflicts in their suggestions, which inevitably leads to  debate and ultimately results in my having to perform a detailed competitive analysis across a number of tools. A task I dread as it takes me of the fast track.

 

The question is: What are the "Best Practices" as seen by people that have extensive experience in the subject?

Does such a guideline exist?

Can we produce it as benchmark?

 

If this is not being done, I am willing to contribute to coordinating and developing the document as a resource. However, in a document of such nature it is important to have majority consensus within the community. I will therefore need the assistance of list members with input and resolution of just what is preferred "Best Practice".

 

Please feel free to contact me if you feel you can provide the baseline for discussion one one or more of the points above.

If you feel that I have neglected something please let me know.

 

Alternately, if you feel that this project should not be undertaken, please say so.

 

Best,

 

Sean Wheller

swheller at bigpond dot net dot au

XWriter