Building documentation, chunkfast.xsl URL in doc/style/kawa.xsl

Building documentation, chunkfast.xsl URL in doc/style/kawa.xsl

[Sudarshan S Chawathe]

[-- Attachment #1: Type: text/plain, Size: 1146 bytes --]


In order to build the Kawa documentation (with sources for the invoke
branch from the Gitlab repo) following the instructions at

  https://www.gnu.org/software/kawa/Source-distribution.html

I found that I needed to edit the URL for chunkfast.xsl in
doc/style/kawa.xsl.  (Otherwise I got errors about failing to load
external entity style/chunkfast.xsl.)  I have included a patch below for
completeness, even though the change it is quite trivial.

The Debian docs seem to suggest the change should be generally
applicable but I am not sure.  Even if the patch doesn't make sense in
general, this message may help others with a setup similar to mine,
which is Debian 8 (Jessie).  I got the idea for the replacement URL from
/usr/share/doc/docbook-xsl/README.Debian.gz file of the docbook-xsl
package on Debian.

With this change, I was able to build the HTML documentation and the
resulting HTML pages look like the ones on the gnu.org Kawa site, with
the exception that the table of contents in the left pane are missing,
and in their place is a link to the table of contents.  (I didn't
investigate that issue further yet.)

Regards,

-chaw


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: kawa-chunkfast-url.diff --]
[-- Type: text/x-diff, Size: 506 bytes --]

diff --git a/doc/style/kawa.xsl b/doc/style/kawa.xsl
index 5fbca2b..e0f904b 100644
--- a/doc/style/kawa.xsl
+++ b/doc/style/kawa.xsl
@@ -2,7 +2,7 @@
                 xmlns:d="http://docbook.org/ns/docbook"
                 version="1.0">
   <!--<xsl:import href="html/chunktoc.xsl"/>-->
-<xsl:import href="chunkfast.xsl"/>
+<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/chunkfast.xsl"/>
 <xsl:import href="docbook-to-html.xsl"/>
 
 <xsl:param name="html.namespace"></xsl:param>

Re: Building documentation, chunkfast.xsl URL in doc/style/kawa.xsl

[Per Bothner]

On 04/30/2017 10:26 AM, Sudarshan S Chawathe wrote:
> 
> In order to build the Kawa documentation (with sources for the invoke
> branch from the Gitlab repo) following the instructions at
> 
>    https://www.gnu.org/software/kawa/Source-distribution.html
> 
> I found that I needed to edit the URL for chunkfast.xsl in
> doc/style/kawa.xsl.  (Otherwise I got errors about failing to load
> external entity style/chunkfast.xsl.)  I have included a patch below for
> completeness, even though the change it is quite trivial.

Strange. That's really not a good fix - we really want to be able to
build every when offline - assuming you have the needed prerequisites
installed correctly.

What is the $DPATH for
   configure --with-docbook-stylesheets=$PATH

Mine (on Fedora) is:
/usr/share/sgml/docbook/xsl-ns-stylesheets-1.79.1

When in doc I do: make web/index.html

I see:

xsltproc --path /usr/share/sgml/docbook/xsl-ns-stylesheets-1.79.1/html:./style \
   --stringparam base.dir ./web  \
   etc etc

There should be a file $DPATH/html/chunkfast.xsl
-- 
	--Per Bothner
per@bothner.com   http://per.bothner.com/

Re: Building documentation, chunkfast.xsl URL in doc/style/kawa.xsl

[Sudarshan S Chawathe]

> Strange. That's really not a good fix - we really want to be able to
> build every when offline - assuming you have the needed prerequisites
> installed correctly.

I agree re. offline building.  And, to the configure option mentioned
below is probably the way to go.  Thanks!

For completeness sake...

My understanding of the suggested URL for chunkfast.xsl is that it is a
canonical name for it, and that an installed docbook-xsl system should
use the locally installed stylesheet matching that canonical name.  This
is based on a very quick scan of the Docbook XSL README and so may be
quite wrong.  The relevant text from the README is:

    ----------------------------------------------------------------------
    How to use the stylesheets
    ----------------------------------------------------------------------
    The base canonical URI for these stylesheets is:

      http://docbook.sourceforge.net/release/xsl/current/

    You call any of the stylesheets in this distribution by doing one
    of the following:

      - Use the base canonical URI in combination with one of the
        pathnames below. For example, for "chunked" HTML, output:

        http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl


> What is the $DPATH for
>    configure --with-docbook-stylesheets=$PATH

I somehow overlooked that option to configure, and hadn't set it.  That
would be an easier fix.

> Mine (on Fedora) is:
> /usr/share/sgml/docbook/xsl-ns-stylesheets-1.79.1

I think the Debian equivalent (from the Debian README for the
docbook-xsl package) would be

  /usr/share/xml/docbook/stylesheet/docbook-xsl

> There should be a file $DPATH/html/chunkfast.xsl

Yes, there is 

  /usr/share/xml/docbook/stylesheet/docbook-xsl/html/chunkfast.xsl

so that seems like the right thing.


So, bottom line, the configure option should do the trick (although the
canonical names thing is interesting). 

Regards,

-chaw

Re: Building documentation, chunkfast.xsl URL in doc/style/kawa.xsl

[Per Bothner]

On 04/30/2017 11:38 AM, Sudarshan S Chawathe wrote:

>> There should be a file $DPATH/html/chunkfast.xsl
> 
> Yes, there is
> 
>    /usr/share/xml/docbook/stylesheet/docbook-xsl/html/chunkfast.xsl
> 
> so that seems like the right thing.
> 
> 
> So, bottom line, the configure option should do the trick (although the
> canonical names thing is interesting).

Be aware that there are two sets of stylesheets: the newer DocBook 5 are
namespace-aware, and the olrder ones aren't.
Kawa requires the former.

On Fedora there is both:

lrwxrwxrwx.  1 root root   25 Jul  8  2016 xsl-ns-stylesheets -> xsl-ns-stylesheets-1.79.1
drwxr-xr-x. 28 root root 4096 Nov 16 15:23 xsl-ns-stylesheets-1.79.1
lrwxrwxrwx.  1 root root   22 Jul  8  2016 xsl-stylesheets -> xsl-stylesheets-1.79.1
drwxr-xr-x. 20 root root 4096 Nov 16 14:49 xsl-stylesheets-1.79.1

Kawa needs the xsl-ns-stylesheets ones.

Medium-term I'm hoping we can improve texinfo's makeinfo so we don't need DocBook.
There is a Google Summer of Code will should move us forwards in that respect.
-- 
	--Per Bothner
per@bothner.com   http://per.bothner.com/

Re: Building documentation, chunkfast.xsl URL in doc/style/kawa.xsl

[Sudarshan S Chawathe]

> Be aware that there are two sets of stylesheets: the newer DocBook 5 are
> namespace-aware, and the olrder ones aren't.
> Kawa requires the former.

That is a good catch; thanks!

> On Fedora there is both:
> 
> lrwxrwxrwx.  1 root root   25 Jul  8  2016 xsl-ns-stylesheets -> xsl-ns-stylesheets-1.79.1
> drwxr-xr-x. 28 root root 4096 Nov 16 15:23 xsl-ns-stylesheets-1.79.1
> lrwxrwxrwx.  1 root root   22 Jul  8  2016 xsl-stylesheets -> xsl-stylesheets-1.79.1
> drwxr-xr-x. 20 root root 4096 Nov 16 14:49 xsl-stylesheets-1.79.1
> 
> Kawa needs the xsl-ns-stylesheets ones.

Debian too seems to have both (and both are installed on my system, not
sure if that's the default): packages are docbook-xsl and
docbook-xsl-ns.

So based on the above, the correct path to give to configure's
--with-docbook-stylesheets option on Debian would be

  /usr/share/xml/docbook/stylesheet/docbook-xsl-ns

To test it all, I just did a fresh build starting from git pull and
everything worked great, except for building kawa.pdf.

The 'make' also built kawa-manual.epub by default, which I'm guessing is
a side effect of using the --with-docbook-stylesheets option, as I don't
recall that happening on my earlier builds.  I was also able to build
the "fancy" and "plain" HTML docs properly.

The only minor problem seems to be building kawa.pdf, which is likely
something outdated on my system. I did use a newish version of texinfo
(6.3) since I know that's needed by Kawa.  Not sure if it's worth
chasing, but I'm including the error from 'make kawa.pdf' (in the doc
subdirectory) below for reference.

Regards,

-chaw


  [163] [164] [165]
  ../../../.././kawa.texi:8889: Argument of @parseargline has an extra }.
  <inserted text> 
                 @par 
  <to be read again> 
                     }
  @next ...required-arg}|@stxref  {guard})@sup  {*}}
                                                    @futurelet @next @smartita...
  l.1 ...s  {required-arg}|@stxref {guard})@sup {*}}
                                                    @texinfoc
  @scanmacro ...atspaces }@scantokens {#1@texinfoc }
                                                    @aftermacro 
  l.1 ...uired-arg}|@stxref {guard})@sup{*}@texinfoc
                                                    
  ...
  l.8889 ...{(@stxref{required-arg}|@stxref{guard})}
                                                     [@stxlit{#!optional} @stx...
  
  ?

Re: Building documentation, chunkfast.xsl URL in doc/style/kawa.xsl

[Per Bothner]

On 04/30/2017 01:25 PM, Sudarshan S Chawathe wrote:
> So based on the above, the correct path to give to configure's
> --with-docbook-stylesheets option on Debian would be
> 
>    /usr/share/xml/docbook/stylesheet/docbook-xsl-ns

I noted that in the instructions.

> To test it all, I just did a fresh build starting from git pull and
> everything worked great, except for building kawa.pdf.
> 
> The 'make' also built kawa-manual.epub by default, which I'm guessing is
> a side effect of using the --with-docbook-stylesheets option, as I don't
> recall that happening on my earlier builds.  I was also able to build
> the "fancy" and "plain" HTML docs properly.

Yep.

I tweaked the instructions for building the documentation
to hopefully make tings clearer.

> The only minor problem seems to be building kawa.pdf, which is likely
> something outdated on my system. I did use a newish version of texinfo
> (6.3) since I know that's needed by Kawa.  Not sure if it's worth
> chasing, but I'm including the error from 'make kawa.pdf' (in the doc
> subdirectory) below for reference.

I made a minor fix to kawa.texi that avoids the problem.

Thanks for your testing!
-- 
	--Per Bothner
per@bothner.com   http://per.bothner.com/

Re: Building documentation, chunkfast.xsl URL in doc/style/kawa.xsl

[Sudarshan S Chawathe]

> > The only minor problem seems to be building kawa.pdf, which is likely
> > something outdated on my system. I did use a newish version of texinfo
> > (6.3) since I know that's needed by Kawa.  Not sure if it's worth
> > chasing, but I'm including the error from 'make kawa.pdf' (in the doc
> > subdirectory) below for reference.
> 
> I made a minor fix to kawa.texi that avoids the problem.

Thanks!  I just re-built everything starting from git pull and am happy
to report that everything was successful, including in particular
kawa.pdf.

-chaw