[ docbook-Feature Requests-1069169 ] Semantic markup for headings

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 454-5900

Feature Requests item #1069169, was opened at 2004-11-19 11:07
Message generated for change (Settings changed) made by xmldoc
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=373750&aid=1069169&group_id=21935

Category: DocBook XSL
Group: HTML
Status: Open
Resolution: None
Priority: 5
Submitted By: Emma Jane Hogbin (ejhogbin)
>Assigned to: Nobody/Anonymous (nobody)
Summary: Semantic markup for headings

Initial Comment:
Headings for "examples" should use one of h1-h6, not .

----------------------------------------------------------------------

Comment By: Michael Smith (xmldoc)
Date: 2004-11-19 16:05

Message:
Logged In: YES 
user_id=118135

This is the right place to submit reports about any
errors you have found, and any suggestions you have for
markup improvements. Sorry if I gave you the impression
that it wasn't.

That said, please understand the 
output you're seeing now is generated by the
stylesheets by design. It is not invalid and does not
(in my opinion) violate the principle of "generating
clean XHTML suitable for styling with a separate CSS
stylesheet". If you don't want example titles to
be bold, the following CSS stylesheet fragment does that.

  p.title b {
    font-weight: normal;
  }

I guess it would be possible to have an h1-h6 heading
generated for formal objects such as examples. It's
just a matter of somebody from the team deciding
whether or not it's worth doing, and then implementing it.
I don't personally think it's worth it, but somebody
else from the team might. So I'll move status on this
back to Open. Sorry for having closed it out so abruptly.

----------------------------------------------------------------------

Comment By: Emma Jane Hogbin (ejhogbin)
Date: 2004-11-19 15:11

Message:
Logged In: YES 
user_id=898304

The following markup should being using a heading (h1-h6)
for the <title> in <example>, not a combination of and .

Here is sample markup:
 <foil id="markup-screen">
 <title>Screen Output</title>
 <para>This is very similar to HTML's &lt;pre&gt;set
formatting. White space will be preserved so 
be careful of your tabs!</para>
<example id="ex-programlisting">
<title>Showing Your Reader What They Will See</title>

In the output:
<p class="title"><b>Example 1. Showing Your Rea....

By wrapping the HTML as such it becomes more difficult to
control the style through CSS. I would have thought that it
was possible to create a variable in XSLT which can report
what the current heading level is and then return an
appropriate HTML tag.

This suggestion for markup change is based on an email to
the list from Bob Stayton asking for "suggestions for
generating clean XHTML suitable for styling with a separate
CSS stylesheet." If this is not the right place to submit
the errors I have found, and the suggestions I have for
markup improvements please let me know where I should report
the errors and make the suggestions.

thanks :)
emma

----------------------------------------------------------------------

Comment By: Michael Smith (xmldoc)
Date: 2004-11-19 14:13

Message:
Logged In: YES 
user_id=118135

Emma Jane,

When you submit reports, please be very specific about
exactly what you are requesting. In this case, the
original description you submitted refers to:

  Headings for "examples"

But your most recent comments refers to:

  foil = title + content

Exactly what DocBook element(s) are you talking about?
The example element? The foil elememnt?

What you need to do is describe what your source has
(or better yet, upload a test document) and then
decribe exactly what output you are seeing.

In this case, you mentioned you were seeing
 in output. The markup gets
generated for DocBook "formal objects" such as the
example element. So based on your description, I
assumed that you were referring to the example element.

The stylesheets that generate output for the example
element are the DocBook XSL Stylesheets, not the Slides
stylesheets. The Slides stylesheets themselves contain
no logic for handling the the example element. They
import the XSL stylesheets. That's why I moved this issue.

Regardless, as far as the goes, the
 in that output will not be removed (though it may
be changed to ) -- because if it's not there,
titles of formal objects in HTML output will not be
rendedered in bold unless a user has an external CSS
stylesheet associated with the document. Not all users
will and not all want to.

----------------------------------------------------------------------

Comment By: Emma Jane Hogbin (ejhogbin)
Date: 2004-11-19 12:49

Message:
Logged In: YES 
user_id=898304

This was part of DocBook _SLIDES_, not DocBook XML. There
aren't sectX in DocBook. It's just the slides (foil = title
+ content). The <b> should be removed as the formatting
instructions should be put in the title class.

Can you please move it back to DocBook Slides? Thanks.

----------------------------------------------------------------------

Comment By: Michael Smith (xmldoc)
Date: 2004-11-19 11:49

Message:
Logged In: YES 
user_id=118135

Oops. I didn't complete what I meant to write; I should
have written:

I guess we could just choose a heading, say h4, and use
that for rending titles for all formal objects, but
that would violate the HTML principle that h1-h6
headings should not be used out of order. That is,
there is no way we could ensure that something like the
following wouldn't end up getting output:

  h1
  h2
  h4
  h3
  h4

That is, we could well end up outputting an h4 heading
for a formal object before outputting an h3 heading for
a section title.

The h1-h6 headings are basically intended for marking
up the titles of the major _sections_ of a document,
not for marking up titles of things like examples and
such that might appear at any level in the sectioning
hiearchy.

----------------------------------------------------------------------

Comment By: Michael Smith (xmldoc)
Date: 2004-11-19 11:41

Message:
Logged In: YES 
user_id=118135

p class="title" _is_ semantic markup. It's even
(arguably) better semantic markup than h1-h6.

The reason the stylesheets don't generate a h1-h6
heading for the example element or for other formal
objects is that a formal object might be a child of a
parent section that has an h1 heading. Or it might be a
child of a h4 section. So there's no way to determine
which h1-h6 heading would be appropriate.

I guess we could just choose a heading, say h4, and
use that for rending titles for all formal objects.

----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=373750&aid=1069169&group_id=21935