Is there a nice XSL stylesheet for client-side DocBook rendering?

views:

366

answers:

+3 Q:

Is there a nice XSL stylesheet for client-side DocBook rendering?

I want the DocBook documents in my SVN repository to look nice if someone looks at them in a web browser. I've started to write a CSS stylesheet, but I think that it will have significant limitations -- particularly ones regarding hyperlinks.

There is a large body of DocBook XSL stylesheets at the DocBook site , but they don't seem to be appropriate for browser rendering. I don't want to generate static documents and put them into SVN. I want them to be basically readable for other developers without much hassle.

I could write my own browser-appropriate XSL stylesheet to convert DocBook to HTML, but it seems like someone else must have already done this. I just don't know where to find it.

+2 A:

You are right, the DocBook XSL stylesheets are very heavy, and are not really suitable for running in a browser. The DocBook Wiki lists some CSS stylesheets, perhaps one of those might work for you?

The only one I have experience of is the one which XMLMind XML Editor apparently uses to present DocBook documents.

Jukka Matilainen 2009-09-16 19:58:56

I started going down the CSS road and it was looking good, at least after I faced the fact that IE would not recognize CSS2.1 selectors when rendering XML and rewrote the styles.But then I wanted to make DocBook <ulink> elements turn into hyperlinks, and I don't think this can be done in CSS.

Steven Huwig 2009-09-17 12:59:24

One of the CSS stylesheets linked from the Wiki page claims `ulink` rendering support on Mozilla and Opera. I don't know how it does it and whether it's using standard CSS or some extensions. http://www.badgers-in-foil.co.uk/projects/docbook-css/

Jukka Matilainen 2009-09-17 17:01:04

I didn't look at the code but clicking on a hyperlink on the demo crashed Safari hard. :)

Steven Huwig 2009-09-18 02:38:05

+1 A:

[Edited because I misread the question]

You certainly wouldn't want to run the stylesheets via a browser and the PI but then you wouldn't want to do that for any reasonably complex content. Do it server side if you're running over a web server or as a batch task. Is there any way that you can interpose a server side process in svn?

DocBook is a complex 'language' and capturing even most of the subleties of DocBook is very difficult. Using the DocBook XSL is not complex at all and I really would recommend you go in that direction if you can. The stylesheets are designed to be customised and are extremely well documented by Bob Stayton in DocBook XSL: The Complete Guide.

Nic Gibson 2009-09-17 08:33:25

I really don't want to deploy anything on the SVN server since it's a company-wide service. The stylesheets also don't have to be publication- or distribution-quality -- I just want fellow developers to be able to browse to the SVN URL and not need a special tool to read the documentation.

Steven Huwig 2009-09-17 13:01:04

Simplified DocBook is a better characterization of the source, though I think the declared DTD is the full DocBook.

Steven Huwig 2009-09-17 13:03:34

I've not seen any particularly good implementations that I'd recommend. I would suspect that you might be stuck creating one yourself. I've done this myself and it's been under a day's work with a simple variant on DocBook (I'd offer them to you but they're rather special purpose).

Nic Gibson 2009-09-17 13:06:40

I've actually started the work and am only bothering with the tags I'm using. Not very hard but it'd still be better if it already existed.I've deferred the actual styling to the W3C Core styles, so the XSLT is pretty much translating article/title to h1, section/title to h3, ulink to a href, etc.

Steven Huwig 2009-09-17 13:14:58

+1 A:

After quite a bit of searching, I believe the answer is "there is not a nice XSL stylesheet for client-side DocBook rendering," besides the bespoke ones like the one I implemented.

Steven Huwig 2009-09-23 01:31:00

Typically you'd produce a 'rendition' for reading/display. The rendition can either be PDF, a single HTML page, or set of HTML pages. It's rare that you deliver docbook directly to web.

Can I ask what you're trying to accomplish and why?
Is this for internal delivery or external?

I hate getting the question that asks "can your technology do X?" It assumes a lot of knowledge about the product (plus, usually the answer is "yes" but that doesn't answer the real question). It's always best when I ask -- "what are you trying to accomplish" -- so I can tell you whether or not any piece of technology is a good fit (or I can point you to some other piece that's a much better fit, or a better way to go about it).

Liz Fraleyc 2010-03-08 18:02:54

This is for internal delivery. We have the DocBook XML hosted in an SVN repository. It would be nice if staff that were visiting the document through SVN's HTTP interface in a browser were able to see a human-readable presentation instead of the raw XML.

Steven Huwig 2010-03-08 18:28:42

And you can't produce a rendition so they're looking at the finished doc rather than the source?

Liz Fraleyc 2010-03-11 02:13:53

It's not really a good practice to check generated files into a source code repository.

Steven Huwig 2010-04-01 15:59:24

Actually, it can be. It depends on the business goal you're trying to achieve. For example, if we were talking SW source code build process/repository and context-sensitive help from CHM (microsoft compiled help), then you'd want the CHM in the repository and the SW build to include it in the final deliverable. Also, as soon as you start adding output formats and multiple languages and depending on simple 1-1 relationship between source and presentation, you're in for a world of hurt.

Liz Fraleyc 2010-04-02 22:05:27

I realize that's not what you're doing. If you can cut down what's allowed in your docbook DTD (so you don't have all possibilities in there), you'll be a lot better off and your transform will be easier. Is that possible?

Liz Fraleyc 2010-04-02 22:25:35

+1 A:

I've done some XSLT+CSS very basic and incomplete implementation for browserside DocBook styling. You can check it out here http://github.com/arsi/db2xhtml

But I would like to see more advanced project if available somewhere!

Arsi Atomi 2010-06-18 10:32:50

ansaurus

tags:

views:

answers:

Is there a nice XSL stylesheet for client-side DocBook rendering?

related questions