docbook: Thread:

& titles

Umm -- I'm having problems with knowing where to place document titles
and sub-titles in DocBook 4.1 (article) markup for use by the LDP.


If I put them under <article><title> and <article><subtitle>, then
render the markup for html using jade/openjade and the ldp.dsl, the
title of the overall document is placed as banner-text at the top of
every rendered html page except the first (as I would expect); followed
*immediately* by the text of the subtitle (which I would expect either
to be suppressed, or at least placed on a line of its own).
Also, on the first page, the sub-title is not placed after the title
line at the top of the page, but instead is rendered as a rubric after
all body text, and before the banner-text of the footer.


If on the other hand I place them in the <articleinfo> section (i.e. as
<articleinfo><title> and <articleinfo><subtitle> -- which for me is
counter-intuitive), then after rendering, the title and sub-title show
as the first two lines of the first html page; but nothing appears as
a banner-text header on any succeeding html pages.


The "write-around" I have currently come up with is to mark the
document title first as <article><title>; then again as <articleinfo>
<title>; and to mark the sub-title as <articleinfo><subtitle> only.

But this is a horrendous example of marking-up to produce a desired
visual effect in ONE rendering process only, and makes me most unhappy.
Now -- if I were a dsssl stylesheet programmer...
(It would be much nicer to come to the list with a solution, instead
of a problem.)

Unfortunately, I'm not; the best I can do is describe the problem and
hope that someone else realises what's happening, and where.

Any help or suggestions?
-- 
Martin Wheeler       -        StarTEXT - Glastonbury - BA6 9PH - England
[1] ####@####.####                   http://www.startext.co.uk/

On Jan 25,  1:48am, Martin WHEELER wrote:
> Subject: <article> & <articleinfo> titles
> Umm -- I'm having problems with knowing where to place document titles
> and sub-titles in DocBook 4.1 (article) markup for use by the LDP.
>
>
> If I put them under <article><title> and <article><subtitle>, then
> render the markup for html using jade/openjade and the ldp.dsl, the
> title of the overall document is placed as banner-text at the top of
> every rendered html page except the first (as I would expect); followed
> *immediately* by the text of the subtitle (which I would expect either
> to be suppressed, or at least placed on a line of its own).
> Also, on the first page, the sub-title is not placed after the title
> line at the top of the page, but instead is rendered as a rubric after
> all body text, and before the banner-text of the footer.
>
>
> If on the other hand I place them in the <articleinfo> section (i.e. as
> <articleinfo><title> and <articleinfo><subtitle> -- which for me is
> counter-intuitive), then after rendering, the title and sub-title show
> as the first two lines of the first html page; but nothing appears as
> a banner-text header on any succeeding html pages.
>
> The "write-around" I have currently come up with is to mark the
> document title first as <article><title>; then again as <articleinfo>
> <title>; and to mark the sub-title as <articleinfo><subtitle> only.
>
> But this is a horrendous example of marking-up to produce a desired
> visual effect in ONE rendering process only, and makes me most unhappy.
> Now -- if I were a dsssl stylesheet programmer...

"dsssl stylesheet programmer"...a rare breed apparently...;-)

Anyway, this looks like a bug to me; something didn't carry over
with the change from artheader to articleinfo.

I compared these two HOWTOs:

http://linuxdoc.org/HOWTO/Bootdisk-HOWTO/
    done in DocBook 3.1

http://linuxdoc.org/HOWTO/mini/Nvidia-OpenGL-Configuration/
    done in DocBook 4.1

Both contain the <title> *within* <artheader> for 3.1 and
<articleinfo> for 4.1, yet the title only carries over onto
subsequent pages in the 3.1 (Bootdisk-HOWTO) instance.

So you'd like to see the title carried over to all pages
(3.1 behavior), correct?

What about the subtitles? Do we want soemthing like this on
all HTML pages (centered; as in Bootdisk-HOWTO):

	my_title<br>
        my_subtitle

lmk and I'll try to get this fixed.

-- 
Greg Ferguson     - s/w engr / mtlhd         | gferg at sgi.com
SGI Tech Pubs     - http://techpubs.sgi.com/ |
Linux Doc Project - http://www.linuxdoc.org/ | gferg at metalab.unc.edu

On Thu, 25 Jan 2001, Greg Ferguson wrote:

> Anyway, this looks like a bug to me; something didn't carry over
> with the change from artheader to articleinfo.

That's how it looks to me.

> So you'd like to see the title carried over to all pages
> (3.1 behavior), correct?

Please.

> What about the subtitles? Do we want soemthing like this on
> all HTML pages (centered; as in Bootdisk-HOWTO):
> 
> 	my_title<br>
>         my_subtitle

Would be nice, yes.  (Although something in the back of my mind is
telling me that this position is sometimes used for version or edition?)

TIA
(Could you let us know *where* the fix takes place?  Might help in
future debugging exercises.)
-- 
Martin Wheeler       -        StarTEXT - Glastonbury - BA6 9PH - England
[1] ####@####.####                   http://www.startext.co.uk/

On Jan 25, 10:55pm, Martin WHEELER wrote:
> Subject: Re: <article> & <articleinfo> titles
> On Thu, 25 Jan 2001, Greg Ferguson wrote:
>
> > Anyway, this looks like a bug to me; something didn't carry over
> > with the change from artheader to articleinfo.
>
> That's how it looks to me.
>
> > So you'd like to see the title carried over to all pages
> > (3.1 behavior), correct?
>
> Please.
>
> > What about the subtitles? Do we want soemthing like this on
> > all HTML pages (centered; as in Bootdisk-HOWTO):
> >
> > 	my_title<br>
> >         my_subtitle
>
> Would be nice, yes.  (Although something in the back of my mind is
> telling me that this position is sometimes used for version or edition?)
>
> TIA
> (Could you let us know *where* the fix takes place?  Might help in
> future debugging exercises.)

I didn't get to the <br> for the subtitle, but I do have
a fix for getting the article title on all pages of the document.
Described below...

In common/dbcommon.dsl, approx line #1001, there is this processing
code:

------

(define (article-title nd)
  (let* ((artchild  (children nd))
         (artheader (select-elements artchild (normalize "artheader")))
         (ahtitles  (select-elements (children artheader)
                                     (normalize "title")))
...

------

This function tries to prepare a proper title string, but in this
case, the code was never updated to roll with the changeover to using
"articleinfo" v. "artheader".

So in ldp.dsl I provide a fix for this method, which works for either
permutation ("articleinfo" or "artheader") :

------

(define (article-title nd)
  (let* ((artchild  (children nd))
         (artheader (select-elements artchild (normalize "artheader")))
         (artinfo   (select-elements artchild (normalize "articleinfo")))
         (ahdr (if (node-list-empty? artheader)
                   artinfo
                   artheader))
         (ahtitles  (select-elements (children ahdr)
                                     (normalize "title")))
         (artitles  (select-elements artchild (normalize "title")))
         (titles    (if (node-list-empty? artitles)
                        ahtitles
                        artitles)))
    (if (node-list-empty? titles)
        ""
        (node-list-first titles))))

------

The results can be seen in the Nvidia-OpenGL-Configuration mini-HOWTO
which I re-published (a DocBook 4.1 sgml file):

  http://linuxdoc.org/HOWTO/mini/Nvidia-OpenGL-Configuration/

(I ran a 3.1 DocBook file thru as well, to verify that works ok)

The modifed ldp.dsl is checked into our CVS tree and is available
in the author's resource area of the web site; or directly from:

  http://linuxdoc.org/authors/tools/ldp.dsl

r,

-- 
Greg Ferguson     - s/w engr / mtlhd         | gferg at sgi.com
SGI Tech Pubs     - http://techpubs.sgi.com/ |
Linux Doc Project - http://www.linuxdoc.org/ | gferg at metalab.unc.edu