mirror of
https://github.com/vale981/literate-programming-tutorials
synced 2025-03-04 17:31:39 -05:00
Revert "Origin/1 school notes tutorial"
This commit is contained in:
Brian Smith
GitHub
parent
c0b915d988
commit
173d49349a
5 changed files with 0 additions and 7716 deletions
3736
books/11-0.txt
3736
books/11-0.txt
File diff suppressed because it is too large
Load diff
3758
books/11-org.org
3758
books/11-org.org
File diff suppressed because it is too large
Load diff
BIN
books/11-pdf.pdf
BIN
books/11-pdf.pdf
Binary file not shown.
Binary file not shown.
|
|
@ -1,222 +0,0 @@
|
|||
|
||||
#+TITLE: School Notes Tutorial 1
|
||||
#+Title: Using Links to Make Interactive Notes
|
||||
#+author: Daniel Alexander Smith
|
||||
|
||||
#+HTML: <img src="https://avatars3.githubusercontent.com/u/24377654?s=200&v=4#.jpg" height=50px>
|
||||
|
||||
* Summary
|
||||
|
||||
Orgmode is a powerful note taking tool. And while the documentation on the package is very dense, there are some topics that the manual does not go over in great detail. One of these topics is the link function, and specifically the ability to define custom links using the command.
|
||||
|
||||
#+BEGIN_EXAMPLE
|
||||
,#+link:
|
||||
#+END_EXAMPLE
|
||||
|
||||
command. In this tutorial, I will show you how to set up orgmode, so that you can refer to specific pages of pdf, and how to use that to take notes.
|
||||
The real world exampes are from Project Gutenberg, specifically the alice of wonderland transcription produced by Arthur DiBianca and David Widger.[fn:1]
|
||||
The external link syntax is extremely powerful, especially when
|
||||
|
||||
* Concepts
|
||||
|
||||
** DONE Links
|
||||
|
||||
Orgmode features the ability to create links to both internal and external sources in the form of hyperlinks. These links can be used to jump between points in a file, or jump to point within an external file. Orgmode links consist of two major parts, the link and description.
|
||||
|
||||
#+name: link-example
|
||||
#+BEGIN_SRC org
|
||||
[[protocal:path::arguments][Descriptions]]
|
||||
#+END_SRC
|
||||
|
||||
** DONE Link Abbreviations
|
||||
|
||||
Some hyperlinks are quite long and difficult to type many times over, this is where the ability to define link abbreviations comes in handy.
|
||||
|
||||
#+name: link-abbreviation-example
|
||||
#+BEGIN_SRC org
|
||||
,#+link: name protocal:path::%s
|
||||
#+END_SRC
|
||||
|
||||
This allows for you to create new links using ~C-c C-l~ or entering a new link that looks like when the link is either clicked on, or you press ~C-c C-o~ you will be taken to the path using the protocal outlined above.
|
||||
|
||||
#+BEGIN_SRC org
|
||||
[[name::searching][Description]]
|
||||
#+END_SRC
|
||||
|
||||
If the specific link cannot be understood, orgmode will offer to create a new headline with the name of the link.
|
||||
|
||||
** DONE Inserting Links and Opening Links
|
||||
|
||||
Links can be inserted with the keybind ~C-c C-l~, ~M-x org-insert-link~, or by manually entering the link with the following syntax:
|
||||
=<<link-example>>=.
|
||||
|
||||
** DONE PDFs
|
||||
|
||||
PDFs are a common form of storing written text in a fixed format. This has the added benifit that a pdf will look the same on any device that can render in.
|
||||
However a consequence of this is that these documents can be difficultly to parse position with the link syntax.
|
||||
This is where emacs's docview comes in handy.
|
||||
|
||||
#+name: pdf-link-to-page
|
||||
#+BEGIN_SRC org
|
||||
,#+Link: book docview:pathtofile::%s
|
||||
#+END_SRC
|
||||
|
||||
By creating a link abreviation like the one above, you just need to create a link that will open a buffer at pagenum in the the pdf listed.
|
||||
|
||||
e.g.
|
||||
|
||||
#+BEGIN_SRC org
|
||||
[[book::pagenum][Description]]
|
||||
#+END_SRC
|
||||
|
||||
Whats neat is that as long as the buffer that the book was loaded in remains open. Clicking on other links to the same files will just change your position in that buffer.
|
||||
|
||||
There are limitations however. If you create a link abbreviation as shown, there will not be any auto complete when using org-insert-link.
|
||||
This can be implimented with a more [[Custom Link eLisp][Advance]] link function.
|
||||
|
||||
*** PDF-Tools
|
||||
If you use the PDF-Tools package, the docview links break. If you need to use pdf-tools get the package ~org-pdfview~.
|
||||
Org-pdfview when enabled in your init file creates a pdf-view link which supports page completion. To continue using book links,
|
||||
simply change the protocol from docview, to pdfview.
|
||||
|
||||
** DONE Epubs
|
||||
|
||||
Epubs are powerful way of storing and rendering books. Rather than prerendering all of the text and images like a pdf. Epubs are instead a collection
|
||||
of html pages, and a manifest xml document that have been zipped into a single file.
|
||||
While the exact page layout is no longer the same across devices, epubs will render to the demensions of the device they are on, and feature the ability to change font size and style on the fly.
|
||||
Emacs is incapible of rendering these documents out of the box, but there are some well known packages that add in this functionality.
|
||||
|
||||
*** TODO Nov.el
|
||||
While nov.el is my favorite package for reading epubs in emacs, it unfortunately falls short on the ability to link to specific sections of the book.
|
||||
This could be fixed by creating an [[elisp links][elisp function]].
|
||||
*** TODO Ereader
|
||||
Ereader is a package used to read epub documents in emacs, that includes orgmode support.
|
||||
Of note is the ebook link type.[fn:2] However to use the ebook link you will need to enable it in your init file by adding.
|
||||
#+BEGIN_SRC elisp
|
||||
(require 'org-ebook)
|
||||
#+END_SRC
|
||||
The ebook can link to the book in two ways. By chapter and by string.
|
||||
With the provided books chapter selection seems to be broken. However string selection still works.
|
||||
To search by chapter add
|
||||
#+BEGIN_SRC org
|
||||
::@YYY
|
||||
#+END_SRC
|
||||
where YYY is the start of a chapter. It also limits further string searches to that chapter.
|
||||
String searches are done by adding
|
||||
#+BEGIN_SRC org
|
||||
::$ZZZ
|
||||
#+END_SRC
|
||||
to a string where ZZZ is any combination of characters and white space.
|
||||
A full ebook link looks like this.
|
||||
#+BEGIN_SRC org
|
||||
|
||||
[[ebook:books/pg11-images.epub::@CHAPTER III. A Caucus-Race and a Long Tale::$They were indeed]]
|
||||
#+END_SRC
|
||||
|
||||
|
||||
|
||||
** DONE Text Files
|
||||
|
||||
Text files are the simplest way to store books that I've seen so far.
|
||||
And as a result are wonderfully easy to link to.
|
||||
|
||||
#+BEGIN_SRC org
|
||||
,#+link: book file:pathtotext::%s
|
||||
#+END_SRC
|
||||
|
||||
This link abbreviation will open the text in a buffer at the specific line listed.
|
||||
|
||||
<<<<<<< HEAD
|
||||
** DONE Org Files
|
||||
External Org files can be linked to in a few ways with the specific behavior depending
|
||||
on your org settings but by default you can link to headlines, or a line number.
|
||||
When linking to headlines you can either link to the exact headline[fn:3] or search for
|
||||
a head line[fn:4].
|
||||
#+BEGIN_SRC org
|
||||
,#+link: book file:pathtoorg::%s
|
||||
#+END_SRC
|
||||
|
||||
#+BEGIN_SRC org
|
||||
[[book::linenum][Org file at linenum]]
|
||||
[[book::*Exact Headline][Org file at exact headline]]
|
||||
[[book::text search][Org file that text searches]]
|
||||
#+END_SRC
|
||||
|
||||
** TODO Webpages
|
||||
Orgmode can link to webpages using a few different methods.
|
||||
The first method uses the http/https protocal to access the webpage using your default browser.
|
||||
#+BEGIN_SRC org
|
||||
[[https://en.wikipedia.org/wiki/Literate_programming][Open from browser]]
|
||||
#+END_SRC
|
||||
This sends a signal to your browser to open the requested page.
|
||||
|
||||
** DONE Custom Link eLisp
|
||||
Finally you can create more complicated link functions using elisp.
|
||||
The [[https://orgmode.org/manual/Adding-hyperlink-types.html#Adding-hyperlink-types][hacking]] page in the org manual demonstrates how the man links were created.
|
||||
In essence, what you are doing is creating a lisp program and binding it to one of the link abbreviations.
|
||||
By writing a function like this, you can make the link as interactive as you want, or overide behavior that is un-wanted.
|
||||
See the [[elisp links][Examples]] section for more examples on using this feature.
|
||||
|
||||
** TODO make a demonstration of a link plug in :noexport:
|
||||
|
||||
|
||||
* DONE Examples
|
||||
|
||||
** PDFs
|
||||
#+BEGIN_SRC org
|
||||
,#+link: pg-pdf docview:books/11-pdf.pdf::%s
|
||||
|
||||
[[pg-pdf::35][Chapter VIII]]
|
||||
|
||||
#+END_SRC
|
||||
|
||||
|
||||
** Text
|
||||
|
||||
#+BEGIN_SRC org
|
||||
,#+link: pg-text file:books/11-0.txt::%s
|
||||
|
||||
[[pg-text::1572][Chapter VII]]
|
||||
#+END_SRC
|
||||
|
||||
** Org
|
||||
#+BEGIN_SRC org
|
||||
,#+link: pg-org file:books/11-org.org::%s
|
||||
[[pg-org::*CHAPTER%20IV.%20The%20Rabbit%20Sends%20in%20a%20Little%20Bill][Chapter IV as headdline]]
|
||||
[[pg-org::708][Chapter IV as line number]]
|
||||
[[pg-org::CHAPTER IV. The Rabbit Sends in a Little Bill][Chapter IV as search]]
|
||||
|
||||
|
||||
#+END_SRC
|
||||
|
||||
** elisp links
|
||||
[[https://github.com/bddean/emacs-ereader/blob/f3bbd3f13195f8fba3e3c880aab0e4c60430dcf3/org-ebook.el][Ereader Example]]
|
||||
[[https://emacs.stackexchange.com/a/30345/11045][PDF Example]]
|
||||
[[https://orgmode.org/manual/Adding-hyperlink-types.html#Adding-hyperlink-types][Man Example]]
|
||||
* Further Study
|
||||
** [[https://orgmode.org/manual/Hyperlinks.html#Hyperlinks][Orgmode Hyperlinks]]
|
||||
* Common Export Settings :noexport:
|
||||
|
||||
#+OPTIONS: ':nil *:t -:t ::t <:t H:7 \n:nil ^:{} arch:headline
|
||||
#+OPTIONS: author:t broken-links:nil c:nil creator:nil
|
||||
#+OPTIONS: d:(not "LOGBOOK") date:t e:t email:nil f:t inline:t num:nil
|
||||
#+OPTIONS: p:nil pri:nil prop:nil stat:t tags:t tasks:t tex:t
|
||||
#+OPTIONS: timestamp:t title:t toc:nil todo:t |:t
|
||||
#+SELECT_TAGS: export
|
||||
#+EXCLUDE_TAGS: noexport
|
||||
|
||||
# For Display when file is exported with org-ruby
|
||||
|
||||
#+EXPORT_SELECT_TAGS: export
|
||||
#+EXPORT_EXCLUDE_TAGS: noexport
|
||||
|
||||
* Footnotes
|
||||
|
||||
[fn:4] As defined by these variables https://orgmode.org/org.html#FOOT32
|
||||
|
||||
[fn:3] As defined by these variables https://orgmode.org/org.html#FOOT31
|
||||
|
||||
[fn:2] Ereader's link parser https://github.com/bddean/emacs-ereader/blob/master/org-ebook.el
|
||||
|
||||
[fn:1] Book files can be obtained from [[http://www.gutenberg.org/ebooks/11]]
|
||||
|
||||
Loading…
Add table
Reference in a new issue