RE: [docbook] Why do formalparas only allow one para?

["Rowland, Larry" <larry.rowland@hp.com>]

Kate,

My chequered past includes a dozen years in human factors.
I have actually designed and conducted usability tests of documents
using formalparas in the past and have found that the readers
have little difficulty in forming the connection between a run-in
heading and a single paragraph.  Part of that may come from the
training given the writers producing the test stimulus materials
on never using a formalpara as an introduction to following content.  
In testing documents from other organizations that sometimes
chose to use a formalpara as an introduction to a set of paras,
and sometimes as a single standalone element, users tended to be 
more confused about the scope of the formalparas.  This is only 
true of the run-in heading -- a title as a line preceding the para 
is quite confusing.  It is quite common for test results to 
depend on other characteristics of the test materials in testing 
publishing formats.

An alternative to consider is one of the admonitions (there are
five in DocBook: note, tip, important, warning, caution).  These
are available pretty much anywhere a paragraph is and allow any
number of paras (or other block elements).  If you provide a 
title element (which is optional) it replaces the default title
(which is the type of admonition -- Note, Tip, etc).  It is 
clearly delimited from the surrounding text.  A relatively simple
customization of the transforms can be used to suppress the icon
normally associated with the admonition if you think it is not
appropriate for your usage.  You could use a role attribute to
trigger distinctive formatting if you need all five of the 
admonitions in your existing documentation strategy, something
like a note with a role of definition.  

Best Regards,
Larry Rowland
 

________________________________

From: Kate.Wringe@sybase.com [mailto:Kate.Wringe@sybase.com] 
Sent: Tuesday, July 28, 2009 9:03 AM
To: Rowland, Larry
Cc: Dave Pawson; David Cramer; docbook@lists.oasis-open.org; Jirka Kosek; Scott Hudson
Subject: RE: [docbook] Why do formalparas only allow one para?



As it stands today,  there is a usability problem with formalparas--the reader is forced to figure out if the paragraph that follows a formalpara belongs to the formalpara or not. 

The processing instructions (http://www.docbook.org/tdg5/en/html/formalpara.html) for formalpara do not suggest that formalparas should be visually set apart (e.g., indented, etc.,) from other paras in the output. 
Although it is quite clear that run-in title and para that immediately follows the title belong together, there is nothing to suggest how to interpret the following paras (and other elements). 

The reader (and the writer) must figure out  whether or not the paras following formalparas belong to the formalpara or not.  This problem exists even if the writer uses formalparas "properly" and does not intend the paras following the formalpara to belong to the formalpara. 


Kate 




"Rowland, Larry" <larry.rowland@hp.com> 

07/24/2009 04:48 PM 

	
To
	David Cramer <dcramer@motive.com>, "Kate.Wringe@sybase.com" <Kate.Wringe@sybase.com>, Dave Pawson <davep@dpawson.co.uk> 
cc
	"docbook@lists.oasis-open.org" <docbook@lists.oasis-open.org>, Jirka Kosek <jirka@kosek.cz>, Scott Hudson <scott.hudson@flatironssolutions.com> 
Subject
	RE: [docbook] Why do formalparas only allow one para?

	




David, 
  
That can be dependent on the transforms.  Our transforms use an inline, run-in header (as mentioned by Kate in her message) of bold text that is at the beginning of the first line of the para (delimited by a period at the end of the title if no other punctuation is provided).  This is quite effective since there is no question what content is associated with the title; it is part of the paragraph.  However, a second paragraph would no longer have that visual association.  I believe that currently both PDF and HTML DocBook transforms format it that way. 
  
Best Regards, 
Larry 


________________________________

From: David Cramer [mailto:dcramer@motive.com] 
Sent: Friday, July 24, 2009 2:10 PM
To: Rowland, Larry; Kate.Wringe@sybase.com; Dave Pawson
Cc: docbook@lists.oasis-open.org; Jirka Kosek; Scott Hudson
Subject: RE: [docbook] Why do formalparas only allow one para?

Larry, 
Are you saying that the current presentation of formalpara is flawed in that it does not make it clear that content following a formalpara is not part of the formalpara? 
  
David 


________________________________

From: Rowland, Larry [mailto:larry.rowland@hp.com] 
Sent: Friday, July 24, 2009 12:09 PM
To: David Cramer; Kate.Wringe@sybase.com; Dave Pawson
Cc: docbook@lists.oasis-open.org; Jirka Kosek; Scott Hudson
Subject: RE: [docbook] Why do formalparas only allow one para?

Kate, 
  
There are actually usability reasons for the formalpara not allowing multiple paras. If I have two paras in a formalpara immediately followed by a para not associated with the two paras, how do I tell that the third para is not part of the two-para formalpara? This is also why DocBook does not allow paras to follow a section -- how do you tell the section has ended. 

I understand the frustration, and have dealt with the problem in the past by using variablelists (as you described), by using lists within the para for enumeration of the content items, and by redesigning the content to use sections when appropriate, because they all provide a method for the reader to determine that I have finished the formal element. Part of designing solutions that circumvent DocBook's structure is to make sure the reader can tell what the author intended, since the reader frequently does not have access to the markup that shows the containment relationship, and the format of the output is all that the reader has available. The current render of a formalpara does not provide any indication after the para that the formalpara has ended.  If you do modify the DTD, I would recommend adding some sort of obvious marker following the last element of the formalpara to indicate it has ended.  The reason I say last element is that once you open up the question of more than one para, you also have to deal with the question of what else is legal inside the new thing you have created?  How about lists, figures, mediaobjects, and all the other block level elements? 

I sympathize with the problem, since I have struggled with it in the past, but please make sure the reader can tell what the writer intended -- that has always been a goal in my development of transforms and grammars that feed them. Coming up with new designs for markup is pretty easy, making sure they can effectively communicate the author's intent is much harder since the reader does not usually have access to the markup, just a formatted page (or audio stream or whatever the markup controls -- Markup, it's not just for text anymore!). 

Best Regards, 

Larry Rowland 



________________________________

From: David Cramer [mailto:dcramer@motive.com] 
Sent: Friday, July 24, 2009 9:51 AM
To: Kate.Wringe@sybase.com; Dave Pawson
Cc: docbook@lists.oasis-open.org; Jirka Kosek; Scott Hudson
Subject: RE: [docbook] Why do formalparas only allow one para?

Kate, 
One option is to customize the DocBook DTD or schema. I happen to have this handy because I did this already for our version of DocBook. In this case, you'd create your own sybasebook.dtd variant of the DocBook DTD containing the following: 
  
<!ENTITY % docbook PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
                         "path_to/4.5/docbookx.dtd"> 
%docbook; 
  
<!ELEMENT formalpara (title, (%ndxterm.class;)*, para+ )> 
<!-- End --> 
  
The current DocBook xslts will probably render the formalparas with multiple paras just fine, however you could also have a preprocessing step that terms them back into legal DocBook formalparas before passing the doc on to the DocBook xsls. 
  
Longer term, you could submit an RFE or look at the topic element that Scott mentioned (I'm not current on that discussion). 
  
David 
  


________________________________

From: Kate.Wringe@sybase.com [mailto:Kate.Wringe@sybase.com] 
Sent: Friday, July 24, 2009 8:17 AM
To: Dave Pawson
Cc: David Cramer; docbook@lists.oasis-open.org; Jirka Kosek; Scott Hudson
Subject: Re: [docbook] Why do formalparas only allow one para?


What we need is a free-floating container element that takes a title and allows other block elements (e.g, indexterms, paras, lists, etc.,) within it. 
We want a container element because it is useful for reuse and relocation of content. We want the element to be free-floating because we need to be able 
to put the element anywhere and have other content elements follow it (including itself). 

The problem with bridgeheads is that they are just titles and you can't show the relationship between the title and the content that follows it. To xinclude you'd have 
xinclude the bridgehead as well as each element that follows. We would prefer to have one container element that you could put an ID on and be able to conditionalize it and/or xinclude it. 

We actually have two cases where we need free-floating container elements with titles: 
1) One where the title is not inline -- this element would be akin to simplesect if simplesect was not non-floating. 
2) One where  the title is inline -- this element would be akin to formalpara if formalpara allowed you to have more than one para and allowed other block elements. 

Currently for 1) we use sidebars instead of bridgeheads because we  needed a sub-section-level container element with a title, that could be used anywhere and multiple times within a section. 
Simplesect, because it is non-floating, did not meet our requirements. 

We are looking for a solution for 2) because formalparas do not meet our needs, but they are the best alternative we have right now. 

Thanks again, 

Kate 





Dave Pawson <davep@dpawson.co.uk> 

07/24/2009 12:25 AM 

	

To
	David Cramer <dcramer@motive.com> 
cc
	Scott Hudson <scott.hudson@flatironssolutions.com>, Kate.Wringe@sybase.com, Jirka Kosek <jirka@kosek.cz>, docbook@lists.oasis-open.org 
Subject
	Re: [docbook] Why do formalparas only allow one para?


	





Why not use a bridgehead and multiple paras?

formalpara is singular? Hence one para?



regards

-- 
Dave Pawson
XSLT XSL-FO FAQ.
http://www.dpawson.co.uk