From mboxrd@z Thu Jan  1 00:00:00 1970
From: Gavin Smith <gavinsmith0123@gmail.com>
Subject: Re: Any interest in using HTML for locally-installed Texinfo
	documentation?
Date: Sun, 7 Apr 2019 17:28:04 +0100
Message-ID: <20190407162804.GA28500@darkstar.example.net>
References: <CAKPWYQ3WWUTG=RcA1RrZ=yb4Shwh5ehzpQAO-32r_WEk7M58eQ@mail.gmail.com>
	<87a7h8u4r4.fsf@gnu.org> <20190402150245.GA30067@darkstar>
	<256d60e8-0148-1dd3-4c9d-86e14b42060b@bothner.com>
Mime-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Return-path: <guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org>
Received: from eggs.gnu.org ([209.51.188.92]:44180)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <gavinsmith0123@gmail.com>) id 1hDQjF-0000yO-0v
	for guix-devel@gnu.org; Mon, 08 Apr 2019 05:38:14 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <gavinsmith0123@gmail.com>) id 1hDQjD-000541-IN
	for guix-devel@gnu.org; Mon, 08 Apr 2019 05:38:12 -0400
Content-Disposition: inline
In-Reply-To: <256d60e8-0148-1dd3-4c9d-86e14b42060b@bothner.com>
List-Id: "Development of GNU Guix and the GNU System distribution."
	<guix-devel.gnu.org>
List-Unsubscribe: <https://lists.gnu.org/mailman/options/guix-devel>,
	<mailto:guix-devel-request@gnu.org?subject=unsubscribe>
List-Archive: <http://lists.gnu.org/archive/html/guix-devel/>
List-Post: <mailto:guix-devel@gnu.org>
List-Help: <mailto:guix-devel-request@gnu.org?subject=help>
List-Subscribe: <https://lists.gnu.org/mailman/listinfo/guix-devel>,
	<mailto:guix-devel-request@gnu.org?subject=subscribe>
Errors-To: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org
Sender: "Guix-devel" <guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org>
To: Per Bothner <per@bothner.com>
Cc: guix-devel@gnu.org, Texinfo <bug-texinfo@gnu.org>

On Tue, Apr 02, 2019 at 09:46:05AM -0700, Per Bothner wrote:
> Both Electron and QtWebEngine have mechanisms for communicating between
> the "browser" window and the main application, which is not sandboxed.
> (For QtWebEngine the main application is regular non-sandboxed C++ code.)
> For a desktop browser like Firefox, one could pass important environment
> variables in the URL.  For bi-directional communication between a
> sandboxed desktop browser and the C/C++ wrapper program one can always
> use WebSockets or XmlHttpRequest ("AJAX").

I've started work on a documentation browser using QtWebEngine.  The 
work can be seen in the qt-info branch of the Texinfo Git repository:

http://git.savannah.gnu.org/cgit/texinfo.git/tree/js/docbrowser?h=qt-info

To build this, qmake must be installed.  It can be built by opening 
docbrowser.pro with qtcreator.  Running qmake would probably also work:
I have a Makefile inside the build directory build-docbrowser-Desktop-Debug/
(inside the js/ directory, at the same level as docbrowser/) with a 
comment:

#############################################################################
# Makefile for building: docbrowser
# Generated by qmake (3.1) (Qt 5.9.6)
# Project:  ../docbrowser/docbrowser.pro
# Template: app
# Command: /usr/bin/qmake-qt5 -o Makefile ../docbrowser/docbrowser.pro -spec linux-g++ CONFIG+=debug CONFIG+=qml_debug
#############################################################################



It's at a very early stage of development, but shows how bidirectional
communication with info.js can work.  This uses QWebChannel for bi-directional
communication: I believe domterm uses libwebsockets which is not specific to
Qt.

The QTINFO_DATADIR environment variable must be set to the "js" directory of
the sources.  The program can find manuals under the "examples" subdirectory.

The index search doesn't work because of this bug:

https://bugreports.qt.io/browse/QTBUG-54433

The drop-down list for indices would have to be implemented on the C++ 
side.

I don't know how far I am going to push this, but should do a bit more 
on it in the next few days.  (Development is slow for me because I am not very
familiar with Qt, C++, or JavaScript.)  The next things for me to work on are
proper handling of inter-manual links, as well as injecting info.js into the
HTML pages (instead of requiring it to be referenced in the HTML files in a
<script> tag).

> Note below I'm talking in terms of an ideal long-term roadmap.
> Medium-term one would prioritize, of course.
> 
> I'm assuming you would prefer to not require either Qt or Electron as
> a dependency.  In that case my recommendation is two separate commands,
> supplied by two separate distribution packages:
> 
> (1) A plain 'info' command can parse command-lines, find the right
> html file, and then either open a window in the default desktop browser,
> or display the file using 'emacs -nw'.  (If old-style info files are
> available, it could also display those directly.) If qtinfo or electroninfo are
> installed, they could be used to open a window instead.

This can be considered if a desktop browser is ever finished.

> > This doesn't address the issue of multiple installed versions of the
> > same manual or manuals in different "prefix hierarchies".  I imagine the
> > Info browser would interpret the "../" string specially in a link and
> > go looking through a search path for the referenced manual.  Again, this
> > may be difficult to implement in standard web browsers due to security
> > restrictions.
> 
> It can be done in a standard web browsers using WebSockets or
> XmlHttpRequest (AJAX), but that's more work.

The current state of the work intercepts links to external manuals (but 
doesn't do much with them yet).

> If curious, you can look at the Qt code for DomTerm at:
> https://github.com/PerBothner/DomTerm/tree/master/qtdomterm
> This handles creating a QtWebEngine window, menus, and bi-directional
> communication with the JavaScript in the QtWebEngine window.  It's not
> super-compact, but it's quite reasonable. (The main C code for
> process/pty management is in the lws-term directory.)

I never got this to work, but it was useful to be able to look at the source
code.