From mboxrd@z Thu Jan 1 00:00:00 1970 From: =?utf-8?Q?Ludovic_Court=C3=A8s?= Subject: Re: Any interest in using HTML for locally-installed Texinfo documentation? Date: Tue, 02 Apr 2019 11:37:51 +0200 Message-ID: <87a7h8u4r4.fsf@gnu.org> References: Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Return-path: In-Reply-To: (Gavin Smith's message of "Mon, 1 Apr 2019 13:55:55 +0100") List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-texinfo-bounces+gnu-bug-texinfo2=m.gmane.org@gnu.org Sender: "bug-texinfo" To: Gavin Smith Cc: guix-devel@gnu.org, Texinfo List-Id: guix-devel.gnu.org Hello Gavin, Gavin Smith skribis: > Documentation for GNU packages and others is often installed in the > Info format, a plain text format. Using a plaintext based format for > documentation does not take advantage of bitmapped displays that have > been available for decades. It does not allow styling of text or > reflowing of text. Much information is lost in the conversion from > Texinfo to Info and any attempt in, for example, Emacs to re-add this > information is unreliable. > > Nonetheless, Info viewers have continued to have advantages over web > browsers. They are fast, and have features for searching the manual > with index lookup. They allow the use of keyboard commands. > > In attempt to bring some of the benefits of the Info viewers to HTML > documentation in web browsers, in 2017, as part of Google Summer of > Code, Matthieu Lirzin worked on a JavaScript interface that works with > the HTML that texi2any produces. His work is substantially complete. > A manual with this interface added is at > https://www.gnu.org/software/texinfo/manual/texinfo-html/Overview.html. > All the important keyboard commands that work in the Info viewers are > implemented, including index lookup. Nice! Org-info.js achieved something similar (info "(org) JavaScript support") and I agree that it=E2=80=99s a great improvement. I hope we can eventually upload manuals on gnu.org that take advantage of this features when viewed with browsers that support JavaScript (=E2=80=9Cprogressive enhancement=E2=80=9D as they call it.) We could chan= ge Gnulib=E2=80=99s =E2=80=98gendocs.sh=E2=80=99 to do the right thing. I=E2=80=99d suggest im= proving the CSS to make the document less dense, but that=E2=80=99s a minor issue. (For some reason =E2=80=98i=E2=80=99 does open the index search box for me,= but then hitting enter doesn=E2=80=99t produce any effect. The other navigation com= mands work fine, though.) > I believe this work has great potential to increase the ease of > accessing documentation, including documentation locally installed on > a user's own computer. When a user is using a bitmapped display (e.g. > with X11), this could become the default way that they access > documentation. I hear the argument; it=E2=80=99s true that not everyone uses Emacs or is familiar with the standalone Info reader. Rendering of Info manuals in Emacs is not bad, but a modern browser can do a better job. Yet I=E2=80=99m not completely sold to the everything in the browser approa= ch, and everything in JavaScript. In an ideal world (for me), we=E2=80=99d rat= her provide a local documentation viewer that renders Texinfo directly. TTN=E2=80=99s IXIN experiment was a step in the right direction IMO, but I understand this approach is not something that=E2=80=99s happening now. When talking about ease of access, we can=E2=80=99t ignore keyword searches. How would you do =E2=80=98info -k=E2=80=99? How would you even simply poin= t your browser to a specific manual? What about inter-manual cross-references? Would we need a mechanism similar to =E2=80=98hxmlxref.cnf=E2=80=99 but tha= t would browse local manuals? What would be the recommended solution for Emacs and console users? > I am contacting you because the distribution level may be the best > place to push this forward. There are two reasons: > * The distribution could take care of installation of HTML > documentation files (at the moment, there is no standard place to > install these, and Automake does not support installing HTML files > generated from Texinfo). > * It could also take responsibility for checking web browser > compatibility. Even if we don't use the JavaScript interface for > documentation on the GNU website due to browser compatibility > concerns, an OS distribution would have control over which browser was > used to view documentation. I think we could do this in Guix when we have answers to the questions above. :-) There=E2=80=99s a side issue, which is that HTML documentation tends to take quite a lot of space, but we=E2=80=99ll see whether that=E2=80=99s a proble= m. > Although I have little knowledge of Guix, it is the natural choice of > operating system distribution to contact about this possibility, as > both Texinfo and Guix are GNU projects. A good idea! We should also consider working on adjusting policies and practices in GNU, too. At that point, it=E2=80=99ll be easier to reach out= to other distros. Thank you, Ludo=E2=80=99.