Referring users to external web pages

Referring users to external web pages

[Simen Heggestøyl]

Hi.

Tom Tromey and I want to add a function to css-mode.el for looking up 
CSS
properties at the Mozilla Developer Network (MDN) wiki using Eww.

Is there a policy for referring users to external web pages in Emacs, 
or can we
go ahead?

The content at MDN is licensed under CC-BY-SA, if that matters.

-- Simen

Re: Referring users to external web pages

[John Wiegley]

>>>>> "SH" == Simen Heggestøyl <simenheg@gmail.com> writes:

SH> Tom Tromey and I want to add a function to css-mode.el for looking up CSS
SH> properties at the Mozilla Developer Network (MDN) wiki using Eww.

SH> Is there a policy for referring users to external web pages in Emacs, or
SH> can we go ahead?

SH> The content at MDN is licensed under CC-BY-SA, if that matters.

This will have to be decided by Richard, or someone at the FSF.

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

Re: Referring users to external web pages

[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. ]]]

  > SH> Is there a policy for referring users to external web pages in Emacs, or
  > SH> can we go ahead?

  > SH> The [documentation] at MDN is licensed under CC-BY-SA, if that matters.
  > This will have to be decided by Richard, or someone at the FSF.

That documentation is free, so it is ok for us to recommend it.

There is no ethical issue in having a special function to access those
pages.  Technically, though, if users need to remember that function's
name, this feature is more complexity than it is worth.  Can you find
a way to make it automatic so that users don't have anything extra to
remember?

Also, we don't want to pressure users in the direction of consulting
material over the net rather than having a local copy.  So please make
the function also work with a local copy, if there is a local copy.

By the way: Please don't use the word "content" to refer to published
works.  That term disparages those works.  See
https://gnu.org/philosophy/words-to-avoid.html.

-- 
Dr Richard Stallman
President, Free Software Foundation (gnu.org, fsf.org)
Internet Hall-of-Famer (internethalloffame.org)
Skype: No way! See stallman.org/skype.html.

Re: Referring users to external web pages

[Tom Tromey]

>>>>> "RMS" == Richard Stallman <rms@gnu.org> writes:

RMS> There is no ethical issue in having a special function to access those
RMS> pages.  Technically, though, if users need to remember that function's
RMS> name, this feature is more complexity than it is worth.  Can you find
RMS> a way to make it automatic so that users don't have anything extra to
RMS> remember?

The code rebinds `C-h S' in css-mode to use this new function.
C-h S is currently info-lookup-symbol, so it seemed analogous.

RMS> Also, we don't want to pressure users in the direction of consulting
RMS> material over the net rather than having a local copy.  So please make
RMS> the function also work with a local copy, if there is a local copy.

Ok.  This makes sense to me, I will make the base URL configurable.

As far as I know there's no commonly-installed, free CSS documentation.
Normally I'd write this code to look for an installed copy first, but I
don't think there's one to look for.

thanks,
Tom

Re: Referring users to external web pages

[Clément Pit--Claudel]

[-- Attachment #1.1: Type: text/plain, Size: 317 bytes --]

On 2017-01-19 18:05, Tom Tromey wrote:
> As far as I know there's no commonly-installed, free CSS documentation.
> Normally I'd write this code to look for an installed copy first, but I
> don't think there's one to look for.

I wonder how easy it would be to repackage MDN's documentation as an info manual.


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

Re: Referring users to external web pages

[Marcin Borkowski]

On 2017-01-20, at 00:34, Clément Pit--Claudel <clement.pit@gmail.com> wrote:

> On 2017-01-19 18:05, Tom Tromey wrote:
>> As far as I know there's no commonly-installed, free CSS documentation.
>> Normally I'd write this code to look for an installed copy first, but I
>> don't think there's one to look for.
>
> I wonder how easy it would be to repackage MDN's documentation as an info manual.

And if someone is going to do that, please also take into account the
JavaScript docs.  Making C-h S (and eldoc, for that matter) work with
standard JS functions would be really great.

Best,

--
Marcin Borkowski

Re: Referring users to external web pages

[Stefan Monnier]

>> As far as I know there's no commonly-installed, free CSS documentation.
>> Normally I'd write this code to look for an installed copy first, but I
>> don't think there's one to look for.
> I wonder how easy it would be to repackage MDN's documentation as an
> info manual.

An easier first step might be to make sure that those Mozilla pages get
cached locally after you access them, with a fairly long "time before
refresh" (and in such a way that subsequent accesses don't need *any*
network access).


        Stefan

Re: Referring users to external web pages

[Yuri Khan]

On Fri, Jan 20, 2017 at 11:24 PM, Stefan Monnier
<monnier@iro.umontreal.ca> wrote:

>> I wonder how easy it would be to repackage MDN's documentation as an
>> info manual.
>
> An easier first step might be to make sure that those Mozilla pages get
> cached locally after you access them, with a fairly long "time before
> refresh" (and in such a way that subsequent accesses don't need *any*
> network access).

I really dislike both of the above ideas.

MDN is a wiki. That means anybody* could add useful information at any
time. Both repackaging in a different format and caching aggressively
will defeat that advantage. It will also discourage or prevent the
user from participating.

Additionally, some MDN articles contain live examples which will only
make sense in a fairly capable web browser.

I would certainly appreciate being able to jump to a relevant MDN
article by pressing an easy key in Emacs, but I would prefer reading
it in my preferred browser.

*) Anybody who is not averse to having a Github account.

Re: Referring users to external web pages

[Tom Tromey]

>>>>> "Stefan" == Stefan Monnier <monnier@iro.umontreal.ca> writes:

Stefan> An easier first step might be to make sure that those Mozilla pages get
Stefan> cached locally after you access them, with a fairly long "time before
Stefan> refresh" (and in such a way that subsequent accesses don't need *any*
Stefan> network access).

You mean like having css-mode locally set url-automatic-caching and
url-cache-directory in the new EWW buffer?

I think that would work but I don't know if it should be the default,
because the URL docs say that the cache isn't cleared automatically, and
also I don't see any sort of maximum size setting in the cache code.

OTOH if you think it's still ok, despite that, I'll add something.

Tom

Re: Referring users to external web pages

[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. ]]]

  > > As far as I know there's no commonly-installed, free CSS documentation.
  > > Normally I'd write this code to look for an installed copy first, but I
  > > don't think there's one to look for.

  > I wonder how easy it would be to repackage MDN's documentation as an info manual.

Repackaging it is not necessary in order to have a local copy.
You could have a local copy of exactly what's on their web site.

So I'm saying that the Emacs code to access the documentation
should make provision to access a local copy if there is one.
Any repackaging is not part of Emacs's responsibility, but this
part is.

-- 
Dr Richard Stallman
President, Free Software Foundation (gnu.org, fsf.org)
Internet Hall-of-Famer (internethalloffame.org)
Skype: No way! See stallman.org/skype.html.