(Re)generate: (find-psne-intro)
Source code:  (find-eev "eev-intro.el" "find-psne-intro")
More intros:  (find-eev-quick-intro)
              (find-eval-intro)
              (find-eepitch-intro)
This buffer is _temporary_ and _editable_.
Is is meant as both a tutorial and a sandbox.



Note: this intro needs to be rewritten!
It expands an idea that was mentioned briefly at:
  (find-eev-quick-intro "9.3. Hyperlinks to PDF files")
  (find-eev-quick-intro "9.3. Hyperlinks to PDF files" "local copies")



1. Local copies of files from the internet

Emacs knows how to fetch files from the internet, but for most purposes it is better to use local copies. Suppose that the environment variable $S is set to ~/snarf/; then running this * (eepitch-shell) * (eepitch-kill) * (eepitch-shell) mkdir -p $S/http/www.gnu.org/software/emacs/ cd $S/http/www.gnu.org/software/emacs/ wget http://www.gnu.org/software/emacs/emacs-paper.html echo 'http://www.gnu.org/software/emacs/emacs-paper.html' >> ~/.psne.log # (find-fline "$S/http/www.gnu.org/software/emacs/emacs-paper.html") # (find-w3m "$S/http/www.gnu.org/software/emacs/emacs-paper.html") creates a local copy of `emacs-paper.html' inside ~/snarf/http/ and appends the URL to the file ~/.psne.log. The two lines in comments are hyperlinks to the local copy; The `find-fline' opens it as a file in the obvious way, and `find-w3m' opens it "as HTML", using a text-mode web browser called w3m that can be run either in standalone mode or inside Emacs; `find-w3m' uses w3m's Emacs interface, and it accepts extra arguments, which are treated as a pos-spec-list.

2. The old way: psne

A long time ago eev used to include a shell function called `psne' that ran all that with a single command. This: psne http://www.gnu.org/software/emacs/emacs-paper.html would run the `mkdir', the `cd', the `wget' and the `echo' above. If psne were just a shell script then it wouldn't be able to change the current directory for the calling shell, so it had to be defined as shell function instead of a script, and the user had to patch his ~/.bashrc (or ~/.zshrc, or whatever) to install the definition for psne and make it available. That was VERY clumsy. From now on we will use "psne" as a verb: to psne a URL means to download a local copy of it into the right place, change to its directory and save its name into the file "~/.psne.log".

3. The new way: M-x brep

Try to run this: (find-psne-links "http://www.gnu.org/software/emacs/emacs-paper.html") or, equivalently, put the point on the URL below and then run `M-x brep': http://www.gnu.org/software/emacs/emacs-paper.html You will get a temporary buffer for psne-ing the URL above. It will contain a `mkdir', a `cd', a `wget' and an `echo', plus an eepitch block and some elisp hyperlinks, and it can be executed with `F8's. Moral of the story: the "new" way to download a local copy of a url is to put the point on it, then run `M-x brep', then execute the resulting e-script. This does not require any patching of rcfiles, as the shell-function version of `psne' used to do.

4. The environment variable $S

If when eev is loaded by Emacs the environment variable $S is unset, it will be set to a default value - namely, to the expansion of "$HOME/snarf". Processes started from Emacs, such as shells created with `eepitch-shell' or `find-sh', or external terminals created by sexps like (find-bgprocess "xterm") (find-bgprocess "gnome-terminal") (find-bgprocess "eterm") will then inherit that value. Try it: (getenv "S") (find-sh0 "echo $S") * (eepitch-shell) * (eepitch-kill) * (eepitch-shell) echo $S Try also to create an external shell not from Emacs - for example, from your window manager's list of available applications, or from a text-mode login - and run "echo $S" there: you will notice that $S is unset. Old versions of eev used to require the user to run a script that would patch his rcfiles (i.e., ~/.bashrc, ~/.zshrc, etc) to set $S on startup. That turned out to be unreliable - it was better to teach people how to distinguish those processes that inherit $S from Emacs from those that don't, and let the experts patch their rcfiles by hand.

5. `browse-url' and friends

If you place the point on the URL below http://www.gnu.org/software/emacs/emacs-paper.html and run `M-x browse-url', Emacs will make an external browser visit the remote version of that URL. One (bad) way to visit the local copy of that URL is to modify the URL above by hand to adjust it to your value of $S, until you obtain something like this: file:///home/edrx/snarf/http/www.gnu.org/software/emacs/emacs-paper.html and then run `M-x browse-url' on it. One - rather primitive - way of visiting the local copy of that URL with find-file is to modify the URL by hand, replacing its "http://" with n "$S/http/", and then visit that file. For example: http://www.gnu.org/software/emacs/emacs-paper.html (find-fline "$S/http/www.gnu.org/software/emacs/emacs-paper.html") If you put the point on the URL and run `M-x brfl' on it you will visit the local copy "as a file", with `find-file' / `find-fline'. Visiting URLs - or their local copies - is something that we do so frequently that we need ways to do that with few keystrokes, which is why `brfl' has a short - and cryptic - name. The conventions are: "br" is the common prefix for all the browse-url-like functions in eev, "f" means to use `find-fline' (or, equivalently, `find-file'), "l" is an optional suffix meaning to use the local copy. The details on how to create these "brxxx functions" are here: (find-brxxx-intro)