Using ulink

[Paul W. Frields]

(Possibly) helpful tip for the day:

FDP standard usage for the DocBook XML tag <ulink> is to always use the
link URL as the text for the link itself.  In other words, instead of
this:

<ulink url="http://some.link.to/somewhere/">A good link</ulink>

...use this:

<ulink
url="http://some.link.to/somewhere/">http://some.link.to/somewhere/</ulink>

But wait!  It gets easier.  DocBook XML specifies that when the XML tag
closes itself (i.e. you don't provide any link text), the link itself is
used as the text for any rendering process.  So what you should probably
do instead, for better XML readability, is this:

<ulink url="http://some.link.to/somewhere/"/>

Isn't that a lot easier?  I think so.  Remember the tag-closing slash
after closing the quotes for the URL, or xmlto will give you a hard time
when you attempt to build your document. :-)

-- 
Paul W. Frields, RHCE                          http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
 Fedora Documentation Project: http://fedora.redhat.com/projects/docs/

[Tommy Reynolds]

Uttered "Paul W. Frields" <stickster(a)gmail.com&gt;, spake thus:

>  But wait!  It gets easier.  DocBook XML specifies that when the XML
> tag
>  closes itself (i.e. you don't provide any link text), the link itself is
>  used as the text for any rendering process.  So what you should probably
>  do instead, for better XML readability, is this:
>  
>  <ulink url="http://some.link.to/somewhere/"/> 
Paul,

Could you (or someone who has time) check this using a small example
with Apache FOP?  This is so clever that it may not be implemented in
some rederers.  IIRC, the tentative PDF rendering solution was to
involve FOP.

Cheers

[Paul W. Frields]

On Wed, 2005-08-17 at 12:09 -0500, Tommy Reynolds wrote:
>  Uttered "Paul W. Frields" <stickster(a)gmail.com&gt;,
> spake thus:
>  
>  > But wait!  It gets easier.  DocBook XML specifies that when the XML tag
>  > closes itself (i.e. you don't provide any link text), the link itself is
>  > used as the text for any rendering process.  So what you should probably
>  > do instead, for better XML readability, is this:
>  > 
>  > <ulink url="http://some.link.to/somewhere/"/>
>  
>  Could you (or someone who has time) check this using a small example
>  with Apache FOP?  This is so clever that it may not be implemented in
>  some rederers.  IIRC, the tentative PDF rendering solution was to
>  involve FOP. 
Great idea -- I don't have FOP, but this is defined behavior in the
DocBook standards (as opposed to any cleverness on my part -- I just
read it in DocBook:TDG!), so I'll be very surprised if it doesn't
deliver as promised.  I'll yield this task to someone who has it
installed.  Is Mark Johnson out there?  I thought he used FOP, but I'm
not sure.

-- 
Paul W. Frields, RHCE                          http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
 Fedora Documentation Project: http://fedora.redhat.com/projects/docs/

[Tommy Reynolds]

Uttered "Paul W. Frields" <stickster(a)gmail.com&gt;, spake thus:

>  Great idea -- I don't have FOP, but this is defined behavior in
> the
>  DocBook standards (as opposed to any cleverness on my part -- I just
>  read it in DocBook:TDG!), so I'll be very surprised if it doesn't
>  deliver as promised. 
DocBook is so complicated that most renderers don't implement the
full behavior; their goal is full support, but non-commercial tools
often do the "useful" parts first and then fill in the neat stuff.

Better to be safe than President.

Cheers

[Rahul Sundaram]

Tommy Reynolds wrote:

> Uttered "Paul W. Frields" <stickster(a)gmail.com&gt;, spake
> thus:
>
>   
>
> >Great idea -- I don't have FOP, but this is defined behavior in the
> >DocBook standards (as opposed to any cleverness on my part -- I just
> >read it in DocBook:TDG!), so I'll be very surprised if it doesn't
> >deliver as promised.
> >    
> >
>
> DocBook is so complicated that most renderers don't implement the
> full behavior; their goal is full support, but non-commercial tools
> often do the "useful" parts first and then fill in the neat stuff.
>   
>  
I heard KDE takes up a useful subset and ensures that documents only use 
that. Might be something to look into

regards
Rahul

[Paul W. Frields]

On Wed, 2005-08-17 at 22:51 +0530, Rahul Sundaram wrote:
>  Tommy Reynolds wrote:
>  >Uttered "Paul W. Frields" <stickster(a)gmail.com&gt;, spake thus:
>  >>Great idea -- I don't have FOP, but this is defined behavior in the
>  >>DocBook standards (as opposed to any cleverness on my part -- I just
>  >>read it in DocBook:TDG!), so I'll be very surprised if it doesn't
>  >>deliver as promised.
>  >
>  >DocBook is so complicated that most renderers don't implement the
>  >full behavior; their goal is full support, but non-commercial tools
>  >often do the "useful" parts first and then fill in the neat stuff.
>  >  
>  I heard KDE takes up a useful subset and ensures that documents only use 
>  that. Might be something to look into 
I would think <ulink> is a pretty DocBook feature, and FOP isn't in our
official toolchain (yet?), but Tommy is absolutely right.  Personally, I
don't relish the idea of telling people what part of DocBook they can
use.  I think this is way too much work for too little return.  Stick to
the standards, it'll be OK.  :-)

On the other hand, if FOP can't support a pretty basic DocBook function
like this, I wonder where else it might fall down.  Frankly, I don't
know how much anyone cares about PDF generation for these things; if you
can see it in a Web browser, you can print it, save it, whatever.  CSS
will take care of eliminating Web navigation paraphrenalia (see Red Hat
Magazine for some good usage).

-- 
Paul W. Frields, RHCE                          http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
 Fedora Documentation Project: http://fedora.redhat.com/projects/docs/

[Tommy Reynolds]

Uttered "Paul W. Frields" <stickster(a)gmail.com&gt;, spake thus:

>  On the other hand, if FOP can't support a pretty basic DocBook
> function
>  like this, I wonder where else it might fall down.  Frankly, I don't
>  know how much anyone cares about PDF generation for these things; if you
>  can see it in a Web browser, you can print it, save it, whatever.  CSS
>  will take care of eliminating Web navigation paraphrenalia (see Red Hat
>  Magazine for some good usage). 
We need PDF's for professional, production-level printing.  After
all, the whole reason for XML'ing rather than HTML'ing is to allow
just this task: present in HTML & read in PDF.

Some of us consultant types can actually make money from Fedora, ya
know.  

Fedora: it isn't just for Red Hat anymore.

Cheers

[Mark Johnson]

Paul W. Frields wrote:
>  On Wed, 2005-08-17 at 12:09 -0500, Tommy Reynolds wrote:
>  
> >Uttered "Paul W. Frields" <stickster(a)gmail.com&gt;, spake thus:
> >
> >
> >>But wait!  It gets easier.  DocBook XML specifies that when the XML tag
> >>closes itself (i.e. you don't provide any link text), the link itself is
> >>used as the text for any rendering process.  So what you should probably
> >>do instead, for better XML readability, is this:
> >>
> >><ulink url="http://some.link.to/somewhere/"/>
> >
> >Could you (or someone who has time) check this using a small example
> >with Apache FOP?  This is so clever that it may not be implemented in
> >some rederers.  IIRC, the tentative PDF rendering solution was to
> >involve FOP.
>  
>  
>  Great idea -- I don't have FOP, but this is defined behavior in the
>  DocBook standards (as opposed to any cleverness on my part -- I just
>  read it in DocBook:TDG!), so I'll be very surprised if it doesn't
>  deliver as promised.  
Keep in mind that this is the "recommended" behavior for the 
stylesheets. In reality, an implementer can do whatever she wants.

Fortunately, though, the (xsl) stylesheets are mostly developed by the 
same folks who work on the DocBook schema standards, so the docbook xsl 
stylesheets are likely compliant.

>  I'll yield this task to someone who has it
>  installed.  Is Mark Johnson out there?  I thought he used FOP, but I'm
>  not sure. 
I'd be happy to do a FOP build if someone can suggest an FDP doc for the 
test build...

Cheers,
Mark


-- 
----------------------------------------------------------
Mark Johnson                     <mjohnson(a)redhat.com&gt;
OS Product Documentation
Engineering, Red Hat, Inc.       <http://www.redhat.com>
Tel: [phone]                Fax: [phone]
GPG fp: DBEA FA3C C46A 70B5 F120  568B 89D5 4F61 C07D E242

[Paul W. Frields]

On Wed, 2005-08-17 at 13:35 -0400, Mark Johnson wrote:
>  Paul W. Frields wrote:
>  > On Wed, 2005-08-17 at 12:09 -0500, Tommy Reynolds wrote:
>  > 
>  >>Uttered "Paul W. Frields" <stickster(a)gmail.com&gt;, spake thus:
>  >>
>  >>
>  >>>But wait!  It gets easier.  DocBook XML specifies that when the XML tag
>  >>>closes itself (i.e. you don't provide any link text), the link itself is
>  >>>used as the text for any rendering process.  So what you should probably
>  >>>do instead, for better XML readability, is this:
>  >>>
>  >>><ulink url="http://some.link.to/somewhere/"/>
>  >>
>  >>Could you (or someone who has time) check this using a small example
>  >>with Apache FOP?  This is so clever that it may not be implemented in
>  >>some rederers.  IIRC, the tentative PDF rendering solution was to
>  >>involve FOP.
>  > 
>  > 
>  > Great idea -- I don't have FOP, but this is defined behavior in the
>  > DocBook standards (as opposed to any cleverness on my part -- I just
>  > read it in DocBook:TDG!), so I'll be very surprised if it doesn't
>  > deliver as promised. 
>  
>  Keep in mind that this is the "recommended" behavior for the 
>  stylesheets. In reality, an implementer can do whatever she wants.
>  
>  Fortunately, though, the (xsl) stylesheets are mostly developed by the 
>  same folks who work on the DocBook schema standards, so the docbook xsl 
>  stylesheets are likely compliant.
>  
>  > I'll yield this task to someone who has it
>  > installed.  Is Mark Johnson out there?  I thought he used FOP, but I'm
>  > not sure.
>  
>  I'd be happy to do a FOP build if someone can suggest an FDP doc for the 
>  test build... 
Stuart's yum tutorial "yum-software-management" uses this XML syntax, so
it would make a good test candidate.

-- 
Paul W. Frields, RHCE                          http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
 Fedora Documentation Project: http://fedora.redhat.com/projects/docs/

[Mark Johnson]

Paul W. Frields wrote:
>  On Wed, 2005-08-17 at 13:35 -0400, Mark Johnson wrote: 
> >
> >I'd be happy to do a FOP build if someone can suggest an FDP doc for the 
> >test build...
>  
>  
>  Stuart's yum tutorial "yum-software-management" uses this XML syntax, so
>  it would make a good test candidate. 
Hi Paul,

OK, will give the yum tutorial a shot in the next few hours & report back.

Thanks,
Mark


-- 
----------------------------------------------------------
Mark Johnson                     <mjohnson(a)redhat.com&gt;
OS Product Documentation
Engineering, Red Hat, Inc.       <http://www.redhat.com>
Tel: [phone]                Fax: [phone]
GPG fp: DBEA FA3C C46A 70B5 F120  568B 89D5 4F61 C07D E242

[Mark Johnson]

Paul W. Frields wrote:
>  On Wed, 2005-08-17 at 13:35 -0400, Mark Johnson wrote: 
> >I'd be happy to do a FOP build if someone can suggest an FDP
> doc for the 
> >test build...
>  
>  Stuart's yum tutorial "yum-software-management" uses this XML syntax, so
>  it would make a good test candidate. 
I built the yum doc with FOP using the stock (*not* fdp) docbook-xsl 
stylesheets to see what the default ulink rendering behavior is. Looks 
like they do indeed render the value of the url attribute if the element 
is empty.

If you wanna take a look, the build is here:

http://people.redhat.com/mjohnson/fedora/yum-software-management-en.pdf

Cheers,
Mark

-- 
----------------------------------------------------------
Mark Johnson                     <mjohnson(a)redhat.com&gt;
OS Product Documentation
Engineering, Red Hat, Inc.       <http://www.redhat.com>
Tel: [phone]                Fax: [phone]
GPG fp: DBEA FA3C C46A 70B5 F120  568B 89D5 4F61 C07D E242

[Tommy Reynolds]

Uttered Mark Johnson <mjohnson(a)redhat.com&gt;, spake thus:

>  If you wanna take a look, the build is here:
>  
>  http://people.redhat.com/mjohnson/fedora/yum-software-management-en.pdf 
Nice!