Re: [docbook-apps] WebHelp search indexes

[David Cramer <david@thingbag.net>]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

My suggestion (and I think this is what you plan to do if I follow the
thread) is to start with the latest build from the snapshots and
forget about 1.76.1. There will soon be a 1.77.0 (followed by a more
stable 1.77.1), but we won't change much in webhelp beyond docs and
bug fixes, so starting from the latest snapshot build is your best bet.

Webhelp also depends on the base html/xhtml xsls, so bug fixes in
there help you in webhelp.

The build.xml is indeed intended to be both something you can use out
of the box and something you can use for inspiration in creating your
own build script. I regret that I haven't documented it as well as I'd
like. When you have your Make file done, I'd love to link to it as
another example that people can use.

Btw., yet another alternative (and the one I use day-to-day) is the
Docbkx maven plugin. But if you don't want to use ant, I suppose maven
is right out :-)

David

[1] https://code.google.com/p/docbkx-tools/

On 02/03/2012 09:15 AM, Kasun Gajasinghe wrote:
> 
> 
> On Fri, Feb 3, 2012 at 7:48 PM, Stefan Hinz
> <stefan.hinz@oracle.com <mailto:stefan.hinz@oracle.com>> wrote:
> 
> Hi Kasun,
> 
> Thanks for a swift reply, and providing a truckload full of 
> information! I'll look at this in more detail next week, but I
> have a couple of general questions first, so excuse me for
> top-posting.
> 
> First of all, the reason I was asking here in the first place is 
> because I'd really like to avoid using Ant in our infrastructure. 
> Nothing against Ant, but our stuff is completely make-based, so
> any ant would look like an alien in our environment. :-) And no,
> we're not afraid to use Java -- we're using FOP (0.25 and 1.0) a
> lot.
> 
> So here are my questions:
> 
> (1) Do you think I could use the WebHelp snapshot on 
> http://snapshots.thingbag.net/__xsl/ 
> <http://snapshots.thingbag.net/xsl/> as a drop-in replacement for 
> the current 1.76.1 WebHelp XSL? From looking at the files there
> this seems to be the case. I'm just asking in case you're aware of
> that some of the stuff has conceptually changed to an extent that
> is guaranteed to break whatever I've set up using 1.76.1 WebHelp.
> 
> 
> I think this depends on how far you are going customize webhelp.
> But there wasn't any major conceptual changes like you asked. It
> still use JQuery, has the same structure of the html files, no
> changes on how users invoke the indexer, and the indexed contents
> etc. So, I think you should be fine. One thing though. The snapshot
> building was setup quite recently, so, I can not vouch that the
> snapshot builds are correctly built just yet. Others can clarify on
> this I believe.
> 
> 
> 
> (2) I'm not sure what you mean exactly when you're saying
> snapshot, bridged webhelp, and latest version. Isn't the snapshot
> the latest version one can get, unless you'd built directly from
> the svn repo?
> 
> 
> Sorry for the use of confusing words. By bridged I meant a mix of
> 1.76.1 and the latest snapshot. Yes, snapshot is the latest one can
> get.
> 
> 
> 
> That's it for now. :-) I'll try the procedure you've given below, 
> and will keep this forum updated on the progress.
> 
> Cheers,
> 
> Stefan
> 
> On Fri, Feb 3, 2012 at 4:09 PM, Stefan Hinz <stefan.hinz@oracle.com
> <mailto:stefan.hinz@oracle.com> <mailto:stefan.hinz@oracle.com 
> <mailto:stefan.hinz@oracle.com>__>> wrote:
> 
> At the MySQL Docs team, we build targets using make and xsltproc. 
> There's no documentation how to do that for creating WebHelp 
> output, though -- all the docs I've seen just explain how to build
> output with Ant.
> 
> Anyway, I've got this working with xsltproc and our build 
> infrastructure now, except for one thing: The search functionality 
> works, but it doesn't find anything. I compared the output created 
> by Ant (using the Oxygen Editor), and the one created by xsltproc, 
> and found that the latter doesn't create any index files in the 
> content/search/ directory. Those files are named index-1.js, 
> index-2.js, and index-3.js. If they're created, that is. :-)
> 
> The WebHelp documentation on this is very sparse, and again 
> Ant-specific. It says:
> 
> To build the indexer, you must have installed the JDK version 1.5
> or higher and set the ANT_HOME environment variable. Run ant 
> build-indexer to recompile nw-cms.jar
> 
> 
> Based on this, I assume you are using 1.76.1 of the stylesheets not
> a snapshot? Either way, since you are a user, recompiling of the 
> indexer is not needed.
> 
> AFAIR, 1.76.1 didn't have support for building webhelp via make. 
> So, if needed you could have just copy the Makefile from a snapshot
> to your webhelp directory, and tweak as necessary. Invoke the
> indexer is currently done by 'ant index' command. The make command
> also calls ANT inside the script.
> 
> 
> In the builds.xml configuration file for Ant, I see quite a few 
> lines relating to the indexer, but I don't know how to rewrite
> that for make.
> 
> 
> I suppose you are not eager to install ANT, eh? :)
> 
> Unfortunately, you can not run 1.76.1 without ANT. The indexer 
> there is specific to ANT, because it uses ANT task definition
> (taskdef). The good news is that the current snapshot does not
> depend on ANT. So, if needed you could just read the ANT script and
> convert it to make. But you need to have Java installed (with
> JAVA_HOME properly set.)
> 
> So, what you can do is just use the indexer from snapshot inside 
> 1.76.1. Are you interested in trying this bridged webhelp? Or use
> the latest version? Former also shouldn't be a big deal. I can help
> you out there if needed. Possible steps that comes into my mind
> is,
> 
> 1. Replace webhelpindexer.jar in docbook-xsl-1.76.1/extensions/__,
> and copy tagsoup-1.2.1.jar to the same directory. 2. Then read the
> 'index' target in the ant build.xml. This one is pretty easier to
> understand, not like the previous. 3. Adapt it to 'make'.
> 
> Apart from the file copying, the java task looks like the
> following without all the clutter. [1] You can do the same via make
> by invoking java with the relevant parameters and the classpath
> set.
> 
> ie. java -DhtmlDir=docs/content -DindexerLanguage="xx" 
> -DfillTheRest=true -classpath 
> path/to/lucene/1.jar:2.jar:/__path/to/tagsoup/jar
> 
> I probably have missed something here because I haven't tried
> this.
> 
> [1] <java classname="com.nexwave.__nquindexer.IndexerMain"
> fork="true"> <sysproperty key="htmlDir"
> value="${output-dir}/content"/__> <sysproperty
> key="indexerLanguage" value="${webhelp.indexer.__language}"/> 
> <sysproperty key="htmlExtension" value="${html.extension}"/> 
> <sysproperty key="doStem" value="${enable.stemming}"/> <sysproperty
> key="tocFile" value="${toc.file}"/>
> 
> <!--TagSoup SAX Parser for parsing even the bad html contents. see 
> http://sourceforge.net/__tracker/?func=detail&aid=__3401185&group_id=21935&atid=__373750--
>
> 
<http://sourceforge.net/tracker/?func=detail&aid=3401185&group_id=21935&atid=373750-->
> <http://sourceforge.net/__tracker/?func=detail&aid=__3401185&group_id=21935&atid=__373750--
>
> 
<http://sourceforge.net/tracker/?func=detail&aid=3401185&group_id=21935&atid=373750-->>>
> <sysproperty key="org.xml.sax.driver" 
> value="org.ccil.cowan.tagsoup.__Parser"/> <sysproperty
> key="javax.xml.parsers.__SAXParserFactory" 
> value="org.ccil.cowan.tagsoup.__jaxp.SAXFactoryImpl"/> <classpath> 
> <path refid="classpath"/> </classpath> </java>
> 
> Regards, --Kasun
> 
> 
> 
> Any pointers how to run the indexer from our make-based 
> environment?
> 
> -- Cheers,
> 
> Stefan Hinz <stefan.hinz@oracle.com 
> <mailto:stefan.hinz@oracle.com> <mailto:stefan.hinz@oracle.com 
> <mailto:stefan.hinz@oracle.com>__>>, MySQL Documentation Manager
> 
> Phone: +49-30-82702940 <tel:%2B49-30-82702940> 
> <tel:%2B49-30-82702940>, Fax: +49-30-82702941 
> <tel:%2B49-30-82702941> <tel:%2B49-30-82702941>,
> http://dev.mysql.com/doc
> 
> 
> ORACLE Deutschland B.V.&  Co. KG Registered Office: Riesstr. 25,
> 80992 Muenchen, Germany Commercial Register: Local Court Of Munich,
> HRA 95603 Managing Director: Jürgen Kunz
> 
> General Partner: ORACLE Deutschland Verwaltung B.V. Hertogswetering
> 163/167, 3543 AS Utrecht, Niederlande Register Of Chamber Of
> Commerce: Midden-Niederlande, No. 30143697 Managing Directors:
> Alexander van der Ven, Astrid Kepper, Val Maher
> 
> 
> ------------------------------____----------------------------__--__---------
>
> 
To unsubscribe, e-mail:
> docbook-apps-unsubscribe@__lis__ts.oasis-open.org 
> <http://lists.oasis-open.org> 
> <mailto:docbook-apps-__unsubscribe@lists.oasis-open.__org 
> <mailto:docbook-apps-unsubscribe@lists.oasis-open.org>> For
> additional commands, e-mail: 
> docbook-apps-help@lists.oasis-____open.org 
> <mailto:docbook-apps-help@lists.oasis-__open.org> 
> <mailto:docbook-apps-help@__lists.oasis-open.org 
> <mailto:docbook-apps-help@lists.oasis-open.org>>
> 
> 
> 
> 
> 
> -- ~~~*******'''''''''''''*******__~~~ Kasun Gajasinghe, University
> of Moratuwa, Sri Lanka. Blog: http://kasunbg.blogspot.com Twitter:
> http://twitter.com/kasunbg
> 
> 
> 
> -- Cheers,
> 
> Stefan Hinz <stefan.hinz@oracle.com 
> <mailto:stefan.hinz@oracle.com>>, MySQL Documentation Manager
> 
> Phone: +49-30-82702940 <tel:%2B49-30-82702940>, Fax:
> +49-30-82702941 <tel:%2B49-30-82702941>, http://dev.mysql.com/doc
> 
> ORACLE Deutschland B.V.&  Co. KG Registered Office: Riesstr. 25,
> 80992 Muenchen, Germany Commercial Register: Local Court Of Munich,
> HRA 95603 Managing Director: Jürgen Kunz
> 
> General Partner: ORACLE Deutschland Verwaltung B.V. Hertogswetering
> 163/167, 3543 AS Utrecht, Niederlande Register Of Chamber Of
> Commerce: Midden-Niederlande, No. 30143697 Managing Directors:
> Alexander van der Ven, Astrid Kepper, Val Maher
> 
> 
> 
> 
> -- ~~~*******'''''''''''''*******~~~ Kasun Gajasinghe, University
> of Moratuwa, Sri Lanka. Blog: http://kasunbg.blogspot.com Twitter:
> http://twitter.com/kasunbg

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.11 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iQEcBAEBAgAGBQJPLA+XAAoJEMHeSXG7afUh6cUIAIOgXMyLYM3AKv6uEauqEBcr
SzyCwJhGYQAfnz99VnIlfewvt6FQVYt23kPY+WEh+qNbTArkswLA14Eji0DCc+RV
CpSCLqZP5mlCvZUdXiY8kmnjbQNs2+m2WXAuwT1KXrTn2HyZDRjtntksWYRC0co2
Cxa72xIp9TkHt2DqGujjbiTFdI+903vyZ6gFeL4rYEZwXcUWeXt03ymJeLhUXHeF
ChBwa0YCpzTXJznk9OeSFBmh8svZwZSPPoJi+ugBVA/XF1WsFEJiokAam20nPzUN
I1pSWeI6tiDLpxU5nr+L5sz42qbocRYJVnB4095iFv2M+AdR48EqYHx8BEhwX0Y=
=9+1E
-----END PGP SIGNATURE-----