Asciidoc to Html with client-side search

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
24 messages Options
12
Reply | Threaded
Open this post in threaded view
|

Asciidoc to Html with client-side search

DocEvaluator
This post was updated on .
Hello,
I am currently evaluating different markup languages to shift our software documentation to a reasonable and maintainable state. Of course the output shall be super-duper user-friendly
I am speaking of html output, PDF is not of interest.

I already evaluated Restructured Text (rst) and what I really, really like is the fact that you get a client-side search integrated in your html output (I used Sphinx, of course). So, a user just opens his local documentation with his browser and can use that nice, integrated search feature (see Blender as on of the many examples: https://www.blender.org/manual/contents.html)

Nevertheless Asciidoc is also a good alternative (let's not get into the details of the pros and cons), but I miss examples for that client-side search. I assume that I have to produce Docbook XML first, but after this...?!? I also found some nice hints in the thread http://discuss.asciidoctor.org/Recommendations-for-multi-page-and-single-page-documentation-td118.html, which contains a link to the "docbook webhelp format". The docbook webhelp format output looks great, but can I produce this with Asciidoctor as a toolchain?

Currently I am stuck and glad for any help.

[Another topic is that me and my coworkers are working on Windows, but installing the toolchain on windows will be a different topic/issue.]
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc to Html with client-side search

rappard
​Would Eclipse Help be an option? E.g., https://wiki.eclipse.org/Mylyn/WikiText.

That said, if I recall correctly the work on integrating AsciiDoc into Eclipse was started fairly recently. So I'm not sure it's fully mature yet (no offense meant) for your purposes.

--Martin
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc to Html with client-side search

DocEvaluator
Well, the output looks okay, but I do not see the connection between Asciidoc (or Docbook, which gets generated from Asciidoc) and the Eclipse Help system. I tried to follow http://www.ibm.com/developerworks/library/os-echelp/, but this looks like there's too much manual work involved.

Maybe there are some generators, which generate Eclipse help or Docbook web-based help from Docbook input? So that my chain will look like
Asciidoc ----Asciidoctor----> Docbook XML   ---- unknown generator ----> html with search
Of course the coolest solution would be:
Asciidoc ----Asciidoctor/unknown generator----> html with search
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc to Html with client-side search

rappard
Perhaps AsciiDoc -> DocBook -> HTML Help then?

--Martin
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc to Html with client-side search

DocEvaluator
Oh yes, that was a good hint, thank you Martin!

Because in my company we have windows(*) systems and use a network proxy, I had a hard time because I did could not get a2x to work with my system proxy. Furthermore, a2x then uses the whole libxml2 libraries and I also did not know how to configure a proxy for those (the toolchain is still a little mystery to me). Instead of getting my proxy settings to work, I changed
"\asciidoc-8.6.9\docbook-xsl\htmlhelp.xsl" to not reference 'http://docbook.sourceforge.net....' but to reference a local copy of the file.
And I changed docbook45.conf in a similar way, so that is generates (temporarily needed) XML files, which also references local copies of "docbookx.dtd" and not a remote resource on oasis-open.org.

Anyway, html help finally worked! It is of course not the most fancy stuff on this world, but technically it includes what I need. Under this circumstances Asciidoc is usable for us (or can at least compete with RST).

(*) it seems that Windows doesn't get much attention from Asciidoctor or Docbook side, ey?
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc to Html with client-side search

mojavelinux
Administrator

(*) it seems that Windows doesn't get much attention from Asciidoctor or Docbook side, ey? 

I can't speak for the DocBook toolchain since that is not part of this project. But I can tell you that Asciidoctor is most certainly tested on Windows and several of the developers on the project use a Windows-based system. So we definitely give it attention, but always welcome more testers.


I had a hard time because I did could not get a2x to work with my system proxy. Furthermore, a2x then uses the whole libxml2 libraries and I also did not know how to configure a proxy for those (the toolchain is still a little mystery to me). Instead of getting my proxy settings to work, I changed
"\asciidoc-8.6.9\docbook-xsl\htmlhelp.xsl" to not reference 'http://docbook.sourceforge.net....' but to reference a local copy of the file.
And I changed docbook45.conf in a similar way, so that is generates (temporarily needed) XML files, which also references local copies of "docbookx.dtd" and not a remote resource on oasis-open.org.

This is one of the main reasons I created fopub. fopub is the same thing as a2x, except it only requires a JVM and does not reach out to the network to resolve DTDs.


fopub doesn't currently allow you to specify htmlhelp as an output format, but it wouldn't be difficult to add. The flag just needs to be passed through to the DocBook toolchain runner. Somewhere around: https://github.com/asciidoctor/asciidoctor-fopub/blob/master/fopub.bat#L65-L75 (for the Windows script).

Keep in mind that if you are using a2x, you have the option of producing DocBook with Asciidoctor:

asciidoctor -b docbook master.adoc
a2x -f htmlhelp master.xml

 

Anyway, html help finally worked! It is of course not the most fancy stuff on this world, but technically it includes what I need. Under this circumstances Asciidoc is usable for us (or can at least compete with RST).

Great to hear it!

Cheers,

-Dan


--
Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc to Html with client-side search

mojavelinux
Administrator
In reply to this post by DocEvaluator

On Wed, Feb 24, 2016 at 1:43 AM, Dan Allen <[hidden email]> wrote:
fopub doesn't currently allow you to specify htmlhelp as an output format, but it wouldn't be difficult to add. The flag just needs to be passed through to the DocBook toolchain runner. Somewhere around: https://github.com/asciidoctor/asciidoctor-fopub/blob/master/fopub.bat#L65-L75 (for the Windows script).

I filed an issue to add htmlhelp to fopub.


-Dan


--
Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc to Html with client-side search

mojavelinux
Administrator
In reply to this post by DocEvaluator

On Fri, Feb 19, 2016 at 1:48 AM, DocEvaluator [via Asciidoctor :: Discussion] <[hidden email]> wrote:
, integrated search feature (see Blender as on of the many examples: https://www.blender.org/manual/contents.html)

It's very likely something like this will happen in the AsciiBinder project {1}, though I'm not ruling out the idea of integrating help into the single-page HTML output. Of course, the other option is to add search using either docinfo or, better yet, a Postprocessor. Asciidoctor is very hackable.

-Dan

Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc to Html with client-side search

mojavelinux
Administrator
In reply to this post by DocEvaluator

On Fri, Feb 19, 2016 at 1:48 AM, DocEvaluator [via Asciidoctor :: Discussion] <[hidden email]> wrote:
[another topic is that me and my coworkers are working on Windows, but installing the toolchain is a different topic/issue.]

again, we welcome testers and feedback. We want the experience to be as seamless as possible.

-Dan


--
Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc to Html with client-side search

DocEvaluator
Thank you Dan, for your feedback!

mojavelinux wrote
> [another topic is that me and my coworkers are working on Windows, but
> installing the toolchain is a different topic/issue.]

again, we welcome testers and feedback. We want the experience to be as
seamless as possible.
I will try this and hope to find the time to give some hints. Maybe I will just write down in another forum thread, what my steps on windows were. By the way: up to now, I have not used Asciidoctor, only Asciidoc itself, but I assume that I can my feedback regarding Windows and Asciidoc in this forum, too?

Regarding Asciidoctor I was wondering that there are no installation instructions for Windows online. I could swear, that there were some Windows hints online a few days ago (telling that Windows installation could get complicated), but now I do not find anything. You now, I never worked with Ruby, I do not even know what a ruby gem is. Of course I will google this, but nevertheless an installation instruction for Windows would be handy and easier.
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc to Html with client-side search

DocEvaluator
In reply to this post by mojavelinux
mojavelinux wrote
> , integrated search feature (see Blender as on of the many examples:
> https://www.blender.org/manual/contents.html)
>

It's very likely something like this will happen in the AsciiBinder project
{1}, though I'm not ruling out the idea of integrating help into the
single-page HTML output. Of course, the other option is to add search using
either docinfo or, better yet, a Postprocessor. Asciidoctor is very
hackable.

-Dan

:1: http://www.asciibinder.org/
The description sounds promising, I will evaluate asciibinder!
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc to Html with client-side search

DocEvaluator
In reply to this post by mojavelinux
> This is one of the main reasons I created fopub. fopub is the same thing as
> a2x, except it only requires a JVM and does not reach out to the network to
> resolve DTDs.

> https://github.com/asciidoctor/asciidoctor-fopub

Okay, but from an Asciidoc-newbie point-of-view this is again another tool to test/integrate. It would be much better if a2x and/or the libxml2-tools would work like expected (or at least would use my proxy settings). Instead of trying fopub at the moment, I will try to understand the a2x toolchain to find the real root of my problems.

> Keep in mind that if you are using a2x, you have the option of producing
> DocBook with Asciidoctor:

> asciidoctor -b docbook master.adoc
> a2x -f htmlhelp master.xml

Nice hint, as soon as I will test Asciidoctor itself, I can give this a try. This is a good option if I can't get my proxy settings to work with the a2x toolchain (see above) and I as I understood this will be a performance boost in Docbook generation, too.

Thx,
Eike
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc to Html with client-side search

rappard
In reply to this post by DocEvaluator
> Regarding Asciidoctor I was wondering that there are no installation
> instructions for Windows online. I could swear, that there were some
> Windows hints online a few days ago (telling that Windows
> installation could get complicated), but now I do not find anything.
> You now, I never worked with Ruby, I do not even know what a ruby
> gem is. Of course I will google this, but nevertheless an
> installation instruction for Windows would be handy and easier.

Obviously I do not speak for everyone, but my experience is that people who use Asciidoctor, Ruby and similar tools on Windows usually run things from Cygwin. This is not meant to cast aspersions on Windows' built-in command line - I suspect cross-platform compatibility/usage [*] and better online documentation (sh >> bat) are the two most important reasons.
​​


--Martin
​​

[*: conveniently "forgetting" the differences between the various *nix shells ;-) ]​​

Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc to Html with client-side search

mojavelinux
Administrator

On Wed, Feb 24, 2016 at 6:18 AM, rappard [via Asciidoctor :: Discussion] <[hidden email]> wrote:
people who use Asciidoctor, Ruby and similar tools on Windows usually run things from Cygwin.

Don't forget about Babun, which is definitely the smoothest path to using Cygwin, and a great experience overall.


-Dan


--
Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc to Html with client-side search

mojavelinux
Administrator
In reply to this post by DocEvaluator

On Wed, Feb 24, 2016 at 5:31 AM, DocEvaluator [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Regarding Asciidoctor I was wondering that there are no installation instructions for Windows online.

This is an open issue. See https://github.com/asciidoctor/asciidoctor.org/issues/399

Once you have Ruby (and ideally RVM), the rest is the same on all platforms.

 $ gem install asciidoctor

The tricky part, and what that doc should explain, is how to get it so that "gem install" doesn't install into the system but rather into the user space. One windows, this doesn't matter much since the installation of Ruby doesn't get intertwined with the system, but it's very important on *nix platforms. This guide would explain all this.

-Dan


--
Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc to Html with client-side search

mojavelinux
Administrator
In reply to this post by DocEvaluator

On Wed, Feb 24, 2016 at 5:31 AM, DocEvaluator [via Asciidoctor :: Discussion] <[hidden email]> wrote:
By the way: up to now, I have not used Asciidoctor, only Asciidoc itself, but I assume that I can my feedback regarding Windows and Asciidoc in this forum, too?

AsciiDoc Python is a separate project, so it's best to report issues that relate specifically to that tool to that forum (https://groups.google.com/forum/#!forum/asciidoc) or issue tracker (https://github.com/asciidoc/asciidoc/issues).

It's important to keep in mind, though, that AsciiDoc Python is in maintenance mode and development doesn't happen very fast or frequently. Asciidoctor is where all the action around AsciiDoc happens now (at a rapid pace, I might add).

-Dan


--
Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc to Html with client-side search

jnilo
This post was updated on .
In reply to this post by DocEvaluator
Hello all
I am jumping into this thread since I have exactly the same objective as DocEvaluator, that is being able to create and maintain a web based help file from asciidoctor files with search capabilities.
And I am also working under windows .
I have developped a windows command file (gcbdoc.bat) which - from an asciidoctor input file (gcbasic.adoc) - allows the generation of all types of formats: xml, html, html5, pdf, chm and webhelp. And I am currently working on the epub part of it.
So, from a windows shell, if I type:
gcbdoc gcbasic webhelp
I get the following result.
And if I type:
gcbdoc gcbasic all
I get all the format generated at once.
I'll be more than happy to share this experience (that would be my tribute to this great asciidoctor project) which is mixing asciidoc together with docbook in a windows context.
Let me know if this could be of interest.
But obviously I would dream being able to type:
asciidoctor -b webhelp gcbasic.adoc
and to get  a webhelp-like output directly from asciidoctor (since webhelp does not appear to be very-well maintained).
Dan: what do you think ?
All the best
Jacques

Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc to Html with client-side search

mojavelinux
Administrator

On Thu, Feb 25, 2016 at 11:45 PM, jnilo [via Asciidoctor :: Discussion] <[hidden email]> wrote:
I would dream being able to type:
asciidoctor -webhelp gcbasic.adoc
and to get  a webhelp-like output directly from asciidoctor (since webhelp does not appear to be very-well maintained).
Dan: what do you think ?

The converter you're proposing aligns with Asciidoctor PDF {1} and Asciidoctor EPUB3 {2}. Therefore, I imagine it being in a repository named asciidoctor-webhelp. Then, the command would be:

asciidoctor -r asciidoctor-webhelp -b webhelp master.adoc

or simply:

asciidoctor-webhelp master.adoc

If, under the covers, this converts to DocBook, then converts to webhelp, that's just an implementation detail the the user of the command doesn't have to worry about.

I know there are many people who would be interested in such a converter. Remember that Asciidoctor has a full converter API that you can use to handle conversion in any way that Ruby can orchestrate (which is pretty much anything).

-Dan

Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc to Html with client-side search

mojavelinux
Administrator
In reply to this post by jnilo

On Thu, Feb 25, 2016 at 11:45 PM, jnilo [via Asciidoctor :: Discussion] <[hidden email]> wrote:
I have developped a windows command file (gcbdoc.bat)

If you leverage the Asciidoctor converter API, then you don't have to worry about Unix or Windows launch scripts. You can piggyback on the asciidoctor command and it will just work anywhere that Asciidoctor already runs (which is anywhere).

-Dan


--
Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoc to Html with client-side search

mojavelinux
Administrator
In reply to this post by jnilo

On Fri, Feb 26, 2016 at 12:39 AM, Dan Allen <[hidden email]> wrote:
(which is anywhere).

including the JVM (via AsciidoctorJ), I might add :)

-Dan


--
Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen
12