"modern" doc viewer for info/html

"modern" doc viewer for info/html

[Nic Ferrier]

Hi all

Here: http://gnudoc.ferrier.me.uk/

is something that (I think) Bob Chassell challenged me to do 10 years
ago. A "modern" HTML based viewer for info/html.

This is only the Emacs Lisp manual because I wanted to use the real,
online documents, rather than regenerating them and the GNU docs site is
sadly a bit of a mess appearing to have no standard url for accessing
docs.

But it could easily be extended to all the other GNU doc manuals.

This is only an experiment but I am pretty confident that a JS based app
could emulate info in the browser almost exactly, with only the search
command being a little tricky to handle.

Anyway, it's a curiosity.

Possibly the most curious thing is that the backend is written with
Elnode, my Emacs webserver:

https://github.com/nicferrier/gnudoc-js/blob/master/gnudoc.el

for those who are interested.


I'm not sure I'll take this any further but I did want to show some of
the possibilities and fulfil a long standing request.



Nic Ferrier

Re: "modern" doc viewer for info/html

[Yuri Khan]

On Sat, Aug 2, 2014 at 6:53 AM, Nic Ferrier <nferrier@ferrier.me.uk> wrote:

> Here: http://gnudoc.ferrier.me.uk/
>
> is something that (I think) Bob Chassell challenged me to do 10 years
> ago. A "modern" HTML based viewer for info/html.


Ten years ago it might not be evident (Firefox was called Firebird
back then), but nowadays, when you use a printable character as a
navigation command in a Javascript application, you need to invoke
preventDefault() on the event object. Otherwise, in certain browser
configurations, the character may start an incremental search.

Case in point: I am using Firefox 31, with Preferences | Advanced |
General | [x] Search for text when I start typing. I click any link on
the front page, which displays that node. I then press 'l' on my
keyboard. This takes me back to the index and starts an incremental
search for 'l', which it finds in the 'Lisp Data Types' link. The
incremental search bar grabs keyboard focus, remains active for a few
seconds, and then disappears without returning focus to the page. As a
result, I cannot use any further letter-based navigation commands.


Unrelated: Some links in the top-level index occupy two lines, but
nothing in their appearance gives a hint about that. The list reads as
if it were:

* …
* Packaging
* Antinews
* GNU Free
* Documentation License
* GPL
* …

Re: "modern" doc viewer for info/html

[Eli Zaretskii]

> From: Nic Ferrier <nferrier@ferrier.me.uk>
> Date: Sat, 02 Aug 2014 00:53:07 +0100
> 
> Here: http://gnudoc.ferrier.me.uk/
> 
> is something that (I think) Bob Chassell challenged me to do 10 years
> ago. A "modern" HTML based viewer for info/html.

Where's the capability to lookup a subject by matching against the
index entries (what every Info reader does when I press 'i')?  Without
this, any documentation viewer is much less efficient, except for the
first reading.

I also sorely miss keyboard navigation, like having the SPC key go to
the next node at the end of the current node.

Btw, some cross-references don't work, for example "The Minibuffer" in
the "The Echo Area" node.

> I'm not sure I'll take this any further but I did want to show some of
> the possibilities and fulfil a long standing request.

How is this different from using the HTML produced by makeinfo?

Re: "modern" doc viewer for info/html

[Nic Ferrier]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Nic Ferrier <nferrier@ferrier.me.uk>
>> Date: Sat, 02 Aug 2014 00:53:07 +0100
>> 
>> Here: http://gnudoc.ferrier.me.uk/
>> 
>> is something that (I think) Bob Chassell challenged me to do 10 years
>> ago. A "modern" HTML based viewer for info/html.


>
> Where's the capability to lookup a subject by matching against the
> index entries (what every Info reader does when I press 'i')?  Without
> this, any documentation viewer is much less efficient, except for the
> first reading.

I haven't done that bit. It's maybe one of the bits that I will
implement because the example is worth showing.


> I also sorely miss keyboard navigation, like having the SPC key go to
> the next node at the end of the current node.

That can be done too. I'll see.


> Btw, some cross-references don't work, for example "The Minibuffer" in
> the "The Echo Area" node.

Yeah. The markup is terrible.

>> I'm not sure I'll take this any further but I did want to show some of
>> the possibilities and fulfil a long standing request.
>
> How is this different from using the HTML produced by makeinfo?

I think it's clear that it's a different, more capable viewer for the
trade off of using JavaScript.

Some people object to use JavaScript on political grounds. It's another
one of those things that makes GNU people different.

But JavaScript does make a great user experience, so we're back to this
argument again.


Nic

Re: "modern" doc viewer for info/html

[Nic Ferrier]

Yuri Khan <yuri.v.khan@gmail.com> writes:

> On Sat, Aug 2, 2014 at 6:53 AM, Nic Ferrier <nferrier@ferrier.me.uk> wrote:
>
> Ten years ago it might not be evident (Firefox was called Firebird
> back then), but nowadays, when you use a printable character as a
> navigation command in a Javascript application, you need to invoke
> preventDefault() on the event object. Otherwise, in certain browser
> configurations, the character may start an incremental search.
>
> Case in point: I am using Firefox 31, with Preferences | Advanced |
> General | [x] Search for text when I start typing. I click any link on
> the front page, which displays that node. I then press 'l' on my
> keyboard. This takes me back to the index and starts an incremental
> search for 'l', which it finds in the 'Lisp Data Types' link. The
> incremental search bar grabs keyboard focus, remains active for a few
> seconds, and then disappears without returning focus to the page. As a
> result, I cannot use any further letter-based navigation commands.

I like the way you make the response sound so snarky. 

I had missed that. Is fixed.

> Unrelated: Some links in the top-level index occupy two lines, but
> nothing in their appearance gives a hint about that. The list reads as
> if it were:
>
> * …
> * Packaging
> * Antinews
> * GNU Free
> * Documentation License
> * GPL
> * …

Not sure what to do about that. This isn't a product, it's an example of
what could be done.


Nic

Re: "modern" doc viewer for info/html

[Eli Zaretskii]

> From: Nic Ferrier <nferrier@ferrier.me.uk>
> Cc: emacs-devel@gnu.org
> Date: Sat, 02 Aug 2014 09:24:32 +0100
> 
> > How is this different from using the HTML produced by makeinfo?
> 
> I think it's clear that it's a different, more capable viewer for the
> trade off of using JavaScript.

Can you elaborate about the differences, feature- and
functionality-wise?  Because all I see is HTML pages with hyperlinks,
which is what you get with "makeinfo --html".  I'm sure I'm missing
something, but what?

TIA

Re: "modern" doc viewer for info/html

[Rasmus]

First, thanks for your work Nic!

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Nic Ferrier <nferrier@ferrier.me.uk>
>> Cc: emacs-devel@gnu.org
>
>> Date: Sat, 02 Aug 2014 09:24:32 +0100
>> 
>> > How is this different from using the HTML produced by makeinfo?
>> 
>> I think it's clear that it's a different, more capable viewer for the
>> trade off of using JavaScript.
>
> Can you elaborate about the differences, feature- and
> functionality-wise?  Because all I see is HTML pages with hyperlinks,
> which is what you get with "makeinfo --html".  I'm sure I'm missing
> something, but what?

There is some more info here:

    https://github.com/nicferrier/gnudoc-js/

But I am still a bit puzzled about the exact purpose.  But it seems
the program is a "front-end" to the output of makeinfo --html.  Is
that correct?

Is the goal of the exercise to replicate the Info reader in the
browser?

Again thanks,
Rasmus

-- 
Hvor meget poesi tror De kommer ud af et glas isvand?

Re: "modern" doc viewer for info/html

[Eli Zaretskii]

> From: Rasmus <rasmus@gmx.us>
> Date: Sat, 02 Aug 2014 11:34:04 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> From: Nic Ferrier <nferrier@ferrier.me.uk>
> >> Cc: emacs-devel@gnu.org
> >
> >> Date: Sat, 02 Aug 2014 09:24:32 +0100
> >> 
> >> > How is this different from using the HTML produced by makeinfo?
> >> 
> >> I think it's clear that it's a different, more capable viewer for the
> >> trade off of using JavaScript.
> >
> > Can you elaborate about the differences, feature- and
> > functionality-wise?  Because all I see is HTML pages with hyperlinks,
> > which is what you get with "makeinfo --html".  I'm sure I'm missing
> > something, but what?
> 
> There is some more info here:
> 
>     https://github.com/nicferrier/gnudoc-js/

Thanks, but I asked about features and functionality, not about the
implementation details.

Re: "modern" doc viewer for info/html

[Nic Ferrier]

Eli Zaretskii <eliz@gnu.org> writes:

>> There is some more info here:
>> 
>>     https://github.com/nicferrier/gnudoc-js/
>
> Thanks, but I asked about features and functionality, not about the
> implementation details.

That's the main difference between info and this. Info is a finished
product, this is just a demo of what could be done.

Re: "modern" doc viewer for info/html

[Nic Ferrier]

Rasmus <rasmus@gmx.us> writes:

> But I am still a bit puzzled about the exact purpose.  But it seems
> the program is a "front-end" to the output of makeinfo --html.  Is
> that correct?

It is that, yes.


> Is the goal of the exercise to replicate the Info reader in the
> browser?

The goal is to show how easily it could be done.

I may replicate 25% of the features. So far it has taken me 1 day.


Nic

Re: "modern" doc viewer for info/html

[Lennart Borgman]

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

On Sat, Aug 2, 2014 at 1:12 PM, Nic Ferrier <nferrier@ferrier.me.uk> wrote:

> Eli Zaretskii <eliz@gnu.org> writes:
>
> >> There is some more info here:
> >>
> >>     https://github.com/nicferrier/gnudoc-js/
> >
> > Thanks, but I asked about features and functionality, not about the
> > implementation details.
>
> That's the main difference between info and this. Info is a finished
> product, this is just a demo of what could be done.
>
>
>
How about search engines, Nic?

Yes, I know it is not a finished product, but what are your thoughts about
it. Google, for example, want a plain html page for indexing. And I guess
other search engines wants that too.

[-- Attachment #2: Type: text/html, Size: 1687 bytes --]

Re: "modern" doc viewer for info/html

[Eli Zaretskii]

> From: Nic Ferrier <nferrier@ferrier.me.uk>
> Cc: Rasmus <rasmus@gmx.us>,  emacs-devel@gnu.org
> Date: Sat, 02 Aug 2014 12:12:05 +0100
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> There is some more info here:
> >> 
> >>     https://github.com/nicferrier/gnudoc-js/
> >
> > Thanks, but I asked about features and functionality, not about the
> > implementation details.
> 
> That's the main difference between info and this. Info is a finished
> product, this is just a demo of what could be done.

Sorry, I don't follow.

First, I wasn't talking about Info.  I was talking about the HTML
format that is produced from the Texinfo source.  I said I didn't see
the difference between browsing that and browsing your pages.

And second, I asked specifically about features and functionality that
the HTML files produced by "makeinfo --html", when browsed by a modern
Web browser, don't provide or support.

Let me put it another way: when you say "this is just a demo of what
could be done", what exactly does this demo demonstrate, apart of the
ability to produce HTML content?

Re: "modern" doc viewer for info/html

[Nic Ferrier]

lennart.borgman@gmail.com writes:

> On Sat, Aug 2, 2014 at 1:12 PM, Nic Ferrier <nferrier@ferrier.me.uk> wrote:
>
>> Eli Zaretskii <eliz@gnu.org> writes:
>>
>> >> There is some more info here:
>> >>
>> >>     https://github.com/nicferrier/gnudoc-js/
>> >
>> > Thanks, but I asked about features and functionality, not about the
>> > implementation details.
>>
>> That's the main difference between info and this. Info is a finished
>> product, this is just a demo of what could be done.
>>
>>
>>
> How about search engines, Nic?
>
> Yes, I know it is not a finished product, but what are your thoughts about
> it. Google, for example, want a plain html page for indexing. And I guess
> other search engines wants that too.

There's nothing about the architecture of this that would stop it being
indexed.

And indexing and presenting a different UI are two different
concerns. As I said before, this just proxies existing GNU
documentation. The existing documentation is very good for indexing and
it's still there. I'm not replacing it. I'm just making a "better" UI
for it.


Nic

Re: "modern" doc viewer for info/html

[Lennart Borgman]

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

On Sat, Aug 2, 2014 at 2:26 PM, Nic Ferrier <nferrier@ferrier.me.uk> wrote:

> lennart.borgman@gmail.com writes:
>
> > On Sat, Aug 2, 2014 at 1:12 PM, Nic Ferrier <nferrier@ferrier.me.uk>
> wrote:
> >
> >> Eli Zaretskii <eliz@gnu.org> writes:
> >>
> >> >> There is some more info here:
> >> >>
> >> >>     https://github.com/nicferrier/gnudoc-js/
> >> >
> >> > Thanks, but I asked about features and functionality, not about the
> >> > implementation details.
> >>
> >> That's the main difference between info and this. Info is a finished
> >> product, this is just a demo of what could be done.
> >>
> >>
> >>
> > How about search engines, Nic?
> >
> > Yes, I know it is not a finished product, but what are your thoughts
> about
> > it. Google, for example, want a plain html page for indexing. And I guess
> > other search engines wants that too.
>
> There's nothing about the architecture of this that would stop it being
> indexed.
>
> And indexing and presenting a different UI are two different
> concerns. As I said before, this just proxies existing GNU
> documentation. The existing documentation is very good for indexing and
> it's still there. I'm not replacing it. I'm just making a "better" UI
> for it.
>
> Nic
>

Sounds good. (But of course the html URLs and your URLs must be tied
together for the search engines to point to your version. There are tools
for that.)

[-- Attachment #2: Type: text/html, Size: 3283 bytes --]

Re: "modern" doc viewer for info/html

[Nic Ferrier]

Eli Zaretskii <eliz@gnu.org> writes:

> First, I wasn't talking about Info.  I was talking about the HTML
> format that is produced from the Texinfo source.  I said I didn't see
> the difference between browsing that and browsing your pages.
>
> And second, I asked specifically about features and functionality that
> the HTML files produced by "makeinfo --html", when browsed by a modern
> Web browser, don't provide or support.
>
> Let me put it another way: when you say "this is just a demo of what
> could be done", what exactly does this demo demonstrate, apart of the
> ability to produce HTML content?

The existing HTML info is just HTML. It's nothing like the Info viewer
in Emacs.

You have to click on everything, there's no ability to look anything up
in an index, or search for anything.

My demo doesn't do much of this either. But you can see how it could.

I might implement things like looking up in an index, because it won't take much time.


Nic

Re: "modern" doc viewer for info/html

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

It is ok to use Javascript code if it carries a free license,
but the pages should work (even if not as conveniently)
with Javascript disabled.  Can you do that?

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: "modern" doc viewer for info/html

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

    Is the goal of the exercise to replicate the Info reader in the
    browser?

Yes, that is a useful thing to do.  If we replace the Info reader with
browsers, and Info files with HTML, that would make Texinfo
considerably more useful.  We could also extend the scope of possible
markup and effects.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: "modern" doc viewer for info/html

[Nic Ferrier]

Richard Stallman <rms@gnu.org> writes:

> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
>
> It is ok to use Javascript code if it carries a free license,
> but the pages should work (even if not as conveniently)
> with Javascript disabled.  Can you do that?

The web app is already AGPL'd, most of the library dependencies are MIT
licenced.

Getting this to "downgrade" when JS isn't there is something I haven't
done. It could be done but nearly all the functionality will be lost -
indexing, all keyboard navigation, everything.

We could make changes to makeinfo that would make better HTML that would
downgrade better but that's a different job.


Nic

Re: "modern" doc viewer for info/html

[Rasmus]

Nic Ferrier <nferrier@ferrier.me.uk> writes:

> Richard Stallman <rms@gnu.org> writes:
>
>> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
>> [[[ whether defending the US Constitution against all enemies,     ]]]
>> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
>>
>> It is ok to use Javascript code if it carries a free license,
>> but the pages should work (even if not as conveniently)
>> with Javascript disabled.  Can you do that?
>
> The web app is already AGPL'd, most of the library dependencies are MIT
> licenced.
>
> Getting this to "downgrade" when JS isn't there is something I haven't
> done. It could be done but nearly all the functionality will be lost -
> indexing, all keyboard navigation, everything.

I use NoScript and at the moment the website does not work without js
enabled.  I guess it should (at least) serve the "regular" html pages.

I guess this will come with time.

-- 
. . . The proofs are technical in nature and provides no real understanding

Re: "modern" doc viewer for info/html

[Nic Ferrier]

Rasmus <rasmus@gmx.us> writes:

>> Getting this to "downgrade" when JS isn't there is something I haven't
>> done. It could be done but nearly all the functionality will be lost -
>> indexing, all keyboard navigation, everything.
>
> I use NoScript and at the moment the website does not work without js
> enabled.  I guess it should (at least) serve the "regular" html pages.
>
> I guess this will come with time.

I would guess not, I only wanted to make a demo.

But if people think it's any good then I guess I'll continue working on
it.

Nic

Re: "modern" doc viewer for info/html

[Lennart Borgman]

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

On Aug 3, 2014 1:32 AM, "Nic Ferrier" <nferrier@ferrier.me.uk> wrote:
>
>
> I would guess not, I only wanted to make a demo.
>
> But if people think it's any good then I guess I'll continue working on
> it.
>
> Nic
>

All the things are clearly doable today. And useful.

Though some server side code is probably needed for a good search
experience too.

[-- Attachment #2: Type: text/html, Size: 534 bytes --]

Re: "modern" doc viewer for info/html

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

    Getting this to "downgrade" when JS isn't there is something I haven't
    done. It could be done but nearly all the functionality will be lost -
    indexing, all keyboard navigation, everything.

At least that is better than nothing.  But why can't the indexing
be done in the HTML itself?

    We could make changes to makeinfo that would make better HTML that would
    downgrade better but that's a different job.

We should certainly do that if helps.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: "modern" doc viewer for info/html

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

Please do keep working on it -- if completed, it could make our
documentation system much more useful.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.