Menu

webhelp stylesheets

Anonymous
2012-08-11
2012-08-21
  • Anonymous

    Anonymous - 2012-08-11

    Hello!

    I have a finished DocBook (5) that should serve as an online support for an IT service. The output as html works fine (even though DocBook 5 isn´t fully supportet yet) but I´d prefer to use the webhelp output.
    However I get the following error:

    ERROR:
    webhelp only works when a recent snapshot of the DocBook stylesheets is
    installed. Your version of the DocBook styles at
    /usr/share/xml/docbook/stylesheet/docbook-xsl-ns
    is not webhelp capable.

    Can you pls tell me what stylesheets are needed? I´ve searched the web but couldn´t find anything.

    thx in advance
    regards
    Marina

    PS: I also have docbook-xsl installed

     
    • Thomas Schraitle

      Hi Marina,

      thanks for the feedback!

      First, the Webhelp target is currently reworked by a Google Summer of Code student. I don't know when this will be finished. After it is finished, we will adapt our code to the latest changes.

      Depending on your version of the DocBook stylesheet, this may or may not work with our customizations, causing the above error. You can try it with the latest version 1.77.1. Download it from the upstream project or use the corresponding mechanism of your operating system.

      I've opened Ticket#93. You can visit this ticket from time to time or subscribe to the RSS feed to get the latest updates.

      Regards,
      Tom

       
  • Anonymous

    Anonymous - 2012-08-13

    Hi Tom!

    Thanks for the quick reply and support! I´m already on 1.77.1 but anyway I think I´ll go with the simple html version until the webhelp issue is resolved.

    Keep up the good work!
    regards
    marina

     
    • Frank Sundermeyer

      Hi Marina,

      if you already have installed 1.77, it should work, so this may be a bug in DAPS.

      I am currently testing for the existence of

      extensions/webhelpindexer.jar
      extensions/lucene-analyzers-.jar
      extensions/lucene-core-
      .jar
      extensions/tagsoup-*.jar

      in the installation directory of the DocBook Stylesheets (which, in turn, I retrieve via an xmlcatalog command). These jars are needed for webhelp.

      Which distribution do you use?
      Could be that "your" docbook-stylesheets package has these jar-files somewhere in e.g. /usr/share/java/... , while we decided to leave them under /usr/share/xml/docbook/stylesheet/nwalsh/current/extensions/ (toms maintains that package for SUSE).

      I have to admit that /usr/share/java/ would be the better location for jar-files, so I probably should support different locations for the jar-files.

      Would you do me a favor and tell me where those jar-files are located in your distribution? If you are using an rpm based distribution, run

       rpm -ql docbook-xsl-stylesheets | egrep "\.jar$"
      

      on a Debian based distribution it would be

       dpkg -L docbook-xsl-stylesheets | egrep "\.jar$"
      

      (assuming the DocBook Stylesheet package is named "docbook-xsl-stylesheets").

       
      • Marina

        Marina - 2012-08-14

        Hi Frank!

        Thanks for the help! First off, I´m on an Ubuntu 11.10 distro and I don´t think it´s a daps-bug but simply me being unable to get it done correctly (sorry I´m new to all this). I installed my docbook-xsl and docbook-xsl-ns via apt-get install command (assuming it was the up-to-date version). Additionally I downloaded the 1.77.1 stylesheets manually (just to be save) and put them in my opt folder and installed it from there. However I got an error message after installing:

        Testing with xmlcatalog...
        /opt/docbook-xsl-1.77.1/install.sh: line 853: /opt/docbook-xsl-1.77.1/.urilist: No such file or directory

        Testing with Apache XML Commons Resolver...
        /opt/docbook-xsl-1.77.1/install.sh: line 853: /opt/docbook-xsl-1.77.1/.urilist: No such file or directory

        Unfortunately the command dpkg -L docbook-xsl-stylesheets | egrep ".jar$" didn´t return any output at all probably due to the cause that the stylesheets installed with the above error? (btw I also tried putting docbook-xsl and docbook-xsl-ns as names)
        The .jar files you mentioned are also in my opt directory. Would it suffice to just move them to /usr/share/xml/docbook/stylesheet/nwalsh/ or should I reinstall the stylesheets directly into that directory? Can the .urilist error be ignored??

        sorry for the many questions
        kind regards
        Marina

        PS: is there a way to tell daps where to take the .jar files from?

         

        Last edit: Marina 2012-08-14
        • Thomas Schraitle

          Hi Marina,

          I'm not sure what you really did, so I can't answer all of them in detail. Therefor I've picked some issues that seems to be easy to answer. :)

          Additionally I downloaded the 1.77.1 stylesheets manually (just to be save) and put them in my opt folder and installed it from there. However I got an error message after installing:

          Well, the preferred way is to install it through your package manager (or via apt-get) to avoid any problems.
          However, it seems, there is no 1.77.x version at the moment, neither for Debian nor Ubuntu. Either you (a) wait, or (b) try to package it yourself. It shouldn't be really difficult, but I'm not familiar with packaging in Debian/Ubuntu. Unfortunately, I can't assist you here as I'm not familiar with Debian/Ubuntu. Maybe you can ask on the docbook mailinglist or look at http://stackoverflow.com/questions/130894/how-to-build-a-debian-ubuntu-package-from-source.

          Ok, putting this aside for the moment. You can list the content of a package by using the apt-file command in your terminal:

          $ apt-file list docbook-xsl
          

          Combine that with what Frank wrote earlier:

          $ apt-file list docbook-xsl | egrep "\.jar$"
          

          That should give you (hopefully) a list of jar files. Maybe the jar's where moved into a different package (docbook-xsl-saxon?)


          Of course, the best thing would be to have a package for Ubuntu. However, this is a bit too much for us, so can support only openSUSE at the moment.

          Regards,
          Tom

           
  • Marina

    Marina - 2012-08-20

    Hi Tom!

    Seems my last post got lost somehow, guess that happens when you're not logged in. Anyways, here's the output of your command:

    docbook-xsl-saxon: /usr/share/java/docbook-xsl-saxon.jar
    docbook-xsl-saxon: /usr/share/java/docbook-xsl-saxon_1.00.jar

    seems you were right with saxon. Would it suffice to move them into the right directories?? I also tried packaging 1.77.1 but unfortunately it's not as simple as described in the post. So I guess my only choice would be to wait.

    thanks as always!
    Marina

     
    • Thomas Schraitle

      Hi Marina,

      Would it suffice to move them into the right directories??

      Well, the above JAR files doesn't have to do with Webhelp, unfortunately. You need the webhelpindexer.jar. For example, in our packages it looks likes this:

      $ rpm -ql docbook-xsl-stylesheets | egrep "\.jar$"
      /usr/share/xml/docbook/stylesheet/nwalsh/1.77.1/extensions/lucene-analyzers-3.0.0.jar
      /usr/share/xml/docbook/stylesheet/nwalsh/1.77.1/extensions/lucene-core-3.0.0.jar
      /usr/share/xml/docbook/stylesheet/nwalsh/1.77.1/extensions/saxon65.jar
      /usr/share/xml/docbook/stylesheet/nwalsh/1.77.1/extensions/tagsoup-1.2.1.jar
      /usr/share/xml/docbook/stylesheet/nwalsh/1.77.1/extensions/webhelpindexer.jar
      /usr/share/xml/docbook/stylesheet/nwalsh/1.77.1/extensions/xalan27.jar
      

      Maybe the above JARs can be optimized as well (removing the part with the version number in the filename), but that is a different topic.

      I also tried packaging 1.77.1 but unfortunately it's not as simple as described in the post. So I guess my only choice would be to wait.

      I'm sorry to hear that.
      Well, after thinking about your problem, probably there is a method. However, you need to circumvent your DocBook stylesheets on your system. Maybe try the following workaround, tested on Ubuntu 11.10:

      1. Download the latest version of the DocBook stylesheets.

      2. Create a directory "dbxslt/". In our example, I create it under $HOME, so the full path is $HOME/dbxslt/.

      3. Unpack the stylesheet from step 1 into $HOME/dbxslt/. Your stylesheets are now located in $HOME/dbxslt/docbook-xsl-1.77.1/.

      4. Create a new file docbook-xsl-stylesheets.xml. It doesn't matter where you save it, but I would recommend it to store it under $HOME/dbxslt/. Write the following contents and replace the user "XXX" with your real login name:

       <catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
        <rewriteSystem systemIdStartString="http://docbook.sourceforge.net/release/xsl/1.77.1" rewritePrefix="file:///home/XXX/dbxslt/docbook-xsl-1.77.1"/>
        <rewriteURI uriStartString="http://docbook.sourceforge.net/release/xsl/1.77.1" rewritePrefix="file:///home/XXX/dbxslt/docbook-xsl-1.77.1"/>
        <rewriteSystem systemIdStartString="http://docbook.sourceforge.net/release/xsl/current" rewritePrefix="file:///home/XXX/dbxslt/docbook-xsl-1.77.1"/>
        <rewriteURI uriStartString="http://docbook.sourceforge.net/release/xsl/current" rewritePrefix="file:///home/XXX/dbxslt/docbook-xsl-1.77.1"/>
        <nextCatalog catalog="file:///etc/xml/catalog"/>
       </catalog>
      
      1. Open the file etc/config from your DAPS working copy and search for the variable XML_MAIN_CATALOG. The default is /etc/xml/catalog; change it to /home/XXX/dbxslt/docbook-xsl-stylesheets.xml (and replace the XXX with your login name).

      2. Test it with the DAPS User Guide as follows:

      $ cd daps/doc # wherever you have checked out from the DAPS SVN repo
      # Replace the $ABSPATH with the absolute path:
      $ ../bin/daps -vv --dapsroot $ABSPATH/daps/ -d DC-daps-user html
      
      1. Test the HTML if it contains the right version string:
      $ xmllint -format build/daps-user/html/daps-user/index.html | grep '<meta name="generator"'
      

      You should see something like this:

          <meta name="generator" content="DocBook XSL Stylesheets V1.77.1" />
      

      WebHelp does work for me with the above modifications.

      Hope that helps.

      Regards,
      Tom

       
  • Marina

    Marina - 2012-08-20

    Hi Tom!

    Thanks a lot for the step-by-step guide and the effort!! I followed each step carefully and gave it a test run with your DC-daps-user sample file. It worked like a charm! However I get this output:

    < meta name="generator" content="DocBook XSL Stylesheets V1.75.2" / >

    anyways the webhelp format processed without errors despite still showing V1.75.2. But when I try this with my own docbook files I get the same error as usual:

    ERROR:
    webhelp only works when a recent snapshot of the DocBook stylesheets is installed. Your version of the DocBook styles at /usr/share/xml/docbook/stylesheet/docbook-xsl-ns is not webhelp capable.

    Do I have to make additional changes to each config file? I figured your DC-daps-user file differs from mine in the styleroot path. However the /usr/share/xml/docbook/stylesheet/suse directory doesn't seem to exist within my stylesheet folder :-/

    Also I located all the .jar files you mentioned. They are in my /usr/share/xml/docbook/stylesheet/docbook-xsl-1.77.1/extensions/webhelpindexer.jar instead of the nwalsh directory. How about I just copy/paste them there??

     

    Last edit: Marina 2012-08-20
    • Thomas Schraitle

      Hi Marina,

      hmn, that's interesting. Obviously, I made something different or I forgot to add a missing step. I will look tomorrow again.

      Do I have to make additional changes to each config file? I figured your DC-daps-user file differs from mine in the styleroot path. However the /usr/share/xml/docbook/stylesheet/suse directory doesn't seem to exist within my stylesheet folder :-/

      Ahh, yes. You're absolutely right. I forgot to tell you to modify the DC file as well. Replace the following variables in the DC file with that one:

      STYLEROOT="../suse/xslt"
      HTML_CSS="./daps.css"
      EPUB_CSS="./daps.css"
      

      I hope that gives you a better result.

      Also I located all the .jar files you mentioned. They are in my /usr/share/xml/docbook/stylesheet/docbook-xsl-1.77.1/extensions/webhelpindexer.jar instead of the nwalsh directory. How about I just copy/paste them there??

      Well, the nwalsh directory is a SUSE specific thing. :) However, internally, a variable is set where to find the path to the DocBook stylesheets. You can find out, where your stylesheets are located on your system. The following command works on every Linux platform, but may return different results:

      $ xmlcatalog /etc/xml/catalog http://docbook.sourceforge.net/release/xsl/current/
      file:///usr/share/xml/docbook/stylesheet/nwalsh/1.77.1/
      

      For openSUSE, you get the above path. For Ubuntu you (should) get file:///usr/share/xml/docbook/stylesheet/docbook-xsl/.

      The important point is, although the paths to the directory may be different, the content itself MUST NOT. DAPS assumes a correctly structured sub directory, otherwise it will not work.

      To make a long story short: No, you don't need to copy them. If you package manager has successfully installed them, they contain the correct structure already.
      However, you can check, if daps has found all the necessary dependencies. Use the configure script to check that:

      $ cd daps/
      $ ./configure
      configure:
      
        Configuring DAPS, the DocBook Authoring and Publishing Suite....
      
      checking for a BSD-compatible install... /usr/bin/install -c
      checking wheather build environment is san... yes
      ...
      

      The above script checks some dependencies, for example, if you have installed fop, jing, and other important tools. At the end it gives you a summary. Take special attention to the "no" parts. Usually you can ignore DocBook 5 support.

      I'm sorry that you run into all sorts of troubles. However, I don't know how to build packages for Ubuntu (yet). Maybe I will know in the future, or another helpful soul will send us patches. I know that hurts. We try to make it work for other distributions, but we can only guarantee it for openSUSE.

      Thanks for the input!

      Regards,
      Tom

       
      • Marina

        Marina - 2012-08-21

        Hi Tom!

        Please don't feel bad about that missing webhelp stylesheet package :-) I can manage with the html output as well....it would just have been nice to have. But I think it won't be long until all is working for other linuxes as well. Daps is still the best and simplest tool for processing docbooks I found so far (and I tried some). Also your support is amazing!
        By the way my daps configuration tells me that my environment is sane. I get a few "no"s but none of them being serious I think:

        • gawk
        • epubcheck
        • w3m
        • xep and jing
        • dia and xfig
        • //W3C//DTD SVG 1.1 Basic//EN

        that's it. Everything else is "yes" and ok. The last thing I'm gonna try is converting my DB5 into DB4 and process it into webhelp. Maybe it's really just the -ns- part. The xml catalog exactly returns what you predicted BUT whenever I try to process my files to webhelp the error given is:

        Your version of the DocBook styles at
        /usr/share/xml/docbook/stylesheet/docbook-xsl-ns
        is not webhelp capable.

        so I suppose it recognizes my DB5 format and therefore looks for the docbook-xsl-ns stylesheets instead of the docbook-xsl ones?

        UPDATE:
        converted some pages to docbook4 but the processing gave me the same results (this time actually referring to the docbook-xsl stylesheets). Well this means I gotta wait ...

        regards
        Marina

         

        Last edit: Marina 2012-08-21
        • Thomas Schraitle

          Hi Marina,

          Please don't feel bad about that missing webhelp stylesheet package :-) I can manage with the html output as well

          I've written an answer for your, but it seems SF didn't post it. Too bad. ;-(

          In retrospect, I suggested to move the old stylesheets and replace them with the new one like this:

          $ sudo mv /usr/share/xml/docbook/stylesheet/docbook-xsl /usr/share/xml/docbook/stylesheet/docbook-xsl-1.75.2
          $ sudo cp -a dbxslt/docbook-xsl-1.77.1 /usr/share/xml/docbook/stylesheet/docbook-xsl
          

          That seem to work for me with the webhelp target.

          Daps is still the best and simplest tool for processing docbooks I found so far (and I tried some). Also your support is amazing!

          Thank you! :-)

          By the way my daps configuration tells me that my environment is sane. I get a few "no"s but none of them being serious I think:

          gawk

          There is a package for Ubuntu. Not sure, where it is used, but better install it.

          epubcheck

          You need it only, if you want to check the validity of your EPUBs.

          w3m

          Also I would recommend to install it. You need it, if you want to have text output. That is created by HTML to text through w3m.

          xep and jing

          XEP is a commercial FO formatter. There is no external package available. For jing, I would recommend to install it.

          dia and xfig

          Also install it. You need them, if you have dia or xfig pictures and you need to export them to SVG or PNG.

          //W3C//DTD SVG 1.1 Basic//EN

          This is the SVG schema. Not sure, if there is a package for Ubuntu.

          Your version of the DocBook styles at
          /usr/share/xml/docbook/stylesheet/docbook-xsl-ns
          is not webhelp capable.

          This error message will go away, if you run the above two commands (mv and cp). At least, on my system. :)

          so I suppose it recognizes my DB5 format and therefore looks for the docbook-xsl-ns stylesheets instead of the docbook-xsl ones?

          No, it's simpler. It's a stylesheet issue. If the version number is below 1.77(?), you'll get this message. It has nothing to do with your DocBook version.

          I tried other methods, but the easiest is to replace the installed DocBook stylesheets. Normally, this shouldn't be recommended, but for the time being it's the easiest way...

          Regards,
          Tom

           
          • Marina

            Marina - 2012-08-21

            OMG I can't believe it after all the futile tries it finally worked!!! THANK YOU SO MUCH!!:-)
            I copied the stylesheets as you said and it worked fine for a DB4 format (NOT for my DB5). So I repeated the steps with the docbook-xsl-ns stylesheets and it processed my DB5 (with some errors though):

            now my index.html has a redirect(?) to a folder named "content/index.html" but that file apparently doesn't exist. Here's the content of the created index.html:

            <?xml version="1.0" encoding="utf-8" standalone="no"?>
            <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
            <html xmlns="http://www.w3.org/1999/xhtml">
              <head>
                <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
                <link rel="shortcut icon" href="favicon.ico" />
                <meta http-equiv="Refresh" content="1; URL=content/index.html" />
                <title>sense Portal Online Support </title>
              </head>
              <body>
                          If not automatically redirected, click <a href="content/index.html">content/index.html</a></body>
            </html>
            

            I can however open any other created html file and navigate through the webhelp from there. I attached my errorlog, it contains one fatal error. Maybe you can make more of it... anyways I'm happy enough with the output I have now so thanks a bunch for all your efforts!!

             
            • Thomas Schraitle

              Hi Marina,

              OMG I can't believe it after all the futile tries it finally worked!!! THANK YOU SO MUCH!!:-)

              You're welcome. :-)

              now my index.html has a redirect(?) to a folder named "content/index.html" but that file apparently doesn't exist.

              Hmn. I can't reproduce that. For me, the index.html file is correctly displayed.

              I attached my errorlog, it contains one fatal error.

              I can't see any errorlog. Could you attach it again, please?

              Thanks,
              Tom

               
              • Thomas Schraitle

                Hi,

                here is my index.html file. See attachement.

                Tom

                 
                • Marina

                  Marina - 2012-08-21

                  Can't see your attachment either?? :-D seems to be a sf problem. Attached my errorlog again...maybe it works this time

                   

                  Last edit: Marina 2012-08-21
  • Marina

    Marina - 2012-08-20

    UPDATE:

    Ok, I just tried my luck to simply replace your sample xml files with my own and tried to process them into webhelp like I did before. Didn't work: get the same stylesheet version error. It seems that it is somehow still referring to my /usr/share/xml/docbook/stylesheet/docbook-xsl-ns. So I thought I'd download the ns-1.77.1 for the docbook5 version (since mine is version 5) and repeat your workaround. Same error. So it's probably an issue with docbook 5 not yet being supported right? Would it be worth a try to convert my DB5 into DB4 and try again?

     

    Last edit: Thomas Schraitle 2012-08-21

Anonymous
Anonymous

Add attachments
Cancel





Want the latest updates on software, tech news, and AI?
Get latest updates about software, tech news, and AI from SourceForge directly in your inbox once a month.