I am using Scribble to write assignments and would like to have the ability to include common text snippets somewhere in the document. For example:
#lang scribble/manual
#section{Some section}
#include-file["common-pretext.scrbl"] #; my imaginary command
Some additional text after the pretext
#section{Next section}
More text...
I would like #include-file to include the contents of common-pretext.scrbl just as if I had copy/pasted its contents at the specified position. That is, I would like its contents to be part of Some section and also properly handle Scribble commands occurring in common-pretext.scrbl.
I know that Scribble has #include-section, which is similar to what I want. However, #include-section always starts a new section and text following it until the next section is silently dropped (I am not sure why this happens, but presumably because of how the document is constructed). I also tried Racket's #include, but then the contents are not shown at all. Lastly, I tried building a macro that does what I want, but failed to make it work (if a macro is the way to go, then I am happy to share my attempts so far).
Is there such a command already and if not how can I build one?
This question is pretty old, but if you are still looking, this package does what you want:
https://docs.racket-lang.org/scribble-include-text/index.html
I've been using Org-mode a few months, and as I customize Emacs, I'm having a lot of difficulty finding documentation on how to specifically customize various variables.
Example: I've successfully set up archiving, but want to customize the org-archive-save-context-info variable to reduce the info that's archived along with the task. I do not want to do this per-file, but in my config file. Despite my best efforts, I don't see documentation on syntax and parameters for customizing this.
I do see some documentation when I customize the variable in the Emacs UI--but I'm looking for documentation so I can see syntax and parameters for customizing this myself via a config file. I can learn it backwards this way (via 'easy customization'): customize a variable, see what Emacs wrote to the config, try tweaking that, etc.
[EDIT] I'm talking about info below the task that appears after archiving, like this:
:PROPERTIES:
:ARCHIVE_TIME: 2018-09-10 Mon 11:24
:ARCHIVE_FILE: ~/Dropbox/logs/capture.org
:ARCHIVE_OLPATH: Tasks
:ARCHIVE_CATEGORY: capture
:ARCHIVE_TODO: DONE
:END:
Is this intentional? Do I just need to 'know ELisp' first? Is the intention that you use the Emacs point-and-click UI to customize things like this? Happy to RTFM if I could find the FM.
Is the intention that you use the Emacs point-and-click UI to customize things like this?
It's certainly intended that you would use the customize interface if you don't know elisp (and you might well choose to use it even if you do).
Do I just need to 'know ELisp' first?
Yes, you'll need at least some familiarity with elisp in order to understand the documentation and be able to write your own config changes. This is because elisp is the configuration language for Emacs, and so the documentation is written in that context. (It wouldn't make sense for basic lisp concepts to be explained and repeated in every piece of documentation which used them.)
That said, many people get by just copying and pasting from config examples -- and you're likely to pick up the basics this way, even if you don't fully understand them. If you're serious about Emacs, though, spending some time to learn about elisp will be hugely beneficial to you in future.
I can learn it backwards this way (via 'easy customization'): customize a variable, see what Emacs wrote to the config, try tweaking that, etc.
That's an entirely reasonable thing to do.
FWIW C-hv org-archive-save-context-info is actually very clear if you have the background understanding.
This variable can be a list of any of the following symbols:
time The time of archiving.
file The file where the entry originates.
ltags The local tags, in the headline of the subtree.
itags The tags the subtree inherits from further up the hierarchy.
todo The pre-archive TODO state.
category The category, taken from file name or #+CATEGORY lines.
olpath The outline path to the item. These are all headlines above
the current item, separated by /, like a file path.
That tells you that you might use the following in your config file:
(setq org-archive-save-context-info '(time file todo))
Happy to RTFM if I could find the FM.
You can start learning about elisp in the "Emacs Lisp Intro" manual, which you should find near the top of the Info directory, or jump to directly with C-hig (eintr) RET. Type h from there if you need to learn how to use the Info reader.
The documentation for scribble (the Racket documentation tool) says that “Cross references within […] documents rendered together are always resolved”, but the file a.scrbl below fails to reference the section in file b.scrbl
a.scrbl:
#lang scribble/base
#secref["sectag" #:doc "b.scrbl"]
b.scrbl:
#lang scribble/base
#section[#:tag "sectag"]{A section}
When compiling them with scribble --html a.scrbl b.scrbl, I get:
Warning: some cross references may be broken due to undefined tags:
(part ("/path/to/b.scrbl" "sectag"))
How do I reference a section in b.scrbl from a.scrbl?
It seems to work if you remove the #:doc argument.
#lang scribble/base
#secref["sectag"]
This might create an ambiguity though if you use the same tags in both documents, so you may have to change tag names or use your own tag prefixes.
I'm not sure why the relative path for #:doc doesn't work as you expect. Maybe it is only used for referring to collection-installed documents.
I am currently trying to wrap my head around packages, systems & co.
I now have read Packages, systems, modules, libraries - WTF? a few times, and I think I'm still having difficulties to get it right.
If I simply want to split a Lisp source file into two files, where one shall "use" the other - how do I do that? Do I need to build a system for this? Should I use a module? …? I'm coming from a Node.js background, and there you can simply say
var foo = require('./foo');
to get a reference to what's exported in file foo.js. What is the closest equivalent to this in Lisp?
I understand that ASDF is for systems, and that it is bundled as part of Quicklisp, at least according to its documentation:
ASDF comes bundled with all recent releases of active Common Lisp implementations as well as with quicklisp […]
Okay, Quicklisp is for libraries, but what is their relationship? Is Quicklisp something such as a "package manager" in other languages? And if so, then what exactly does ASDF provide?
Sorry for these many questions, but I think it just shows the trouble I have to understand how to structure Lisp applications. Any help would be greatly appreciated :-)
System
For structuring large system use a system management tool. A 'free' one is ASDF.
You would need a system declaration, which lists the parts of you library or application. Typically it goes into an own file. Then you load a system or compile a system. There should be tutorials how to do that.
A simple Lisp system might have the following files:
a system file describing the system, its parts and whatever other stuff is needed (other systems)
a package file which describes the namespaces used
a basic tools file (for examples functions used by the macro)
a macro file which lists the macros (used so that they get compiled/loaded before the rest of the software)
one or more other files with functionality.
Quicklisp is independent of that. It's a software distribution tool.
Quick hack to compile and load files
But you can also compile and load files the old fashioned way without a system tool:
(defparameter *files*
'("/yourdir/foo.lisp" "/yourdir/bar.lisp"))
(defun compile-foobar ()
(mapc #'compile-file *files*))
(defun load-foobar ()
(mapc #'load *files*))
(defun compile-and-load ()
(mapc (lambda (file)
(load (compile-file file)))
*files*))
In reality there might be more to it, but often it's enough. It should be easy to write your own building tool. A typical system tool will provide many more features for building more complex software in a structured way. Many of the ideas for these tools reach back at least 35 years. See for example the Lisp Machine manual, here the edition from 1984, chapter Maintaining Large Systems.
The role of files
Note that in plain Common Lisp the role of files and its semantics are not very complex.
A file is not a namespace, it is not associated with a class/subclass or an object, it is not a module. You mix Lisp constructs in a file like you want. Files can be arbitrary large (for example one complex library has a version where it is delivered as single source file with 30000 lines). The only real place in the standard semantics where a file plays a role is when compiling a file. What side effects has compiling a file? What optimizations can a compiler do?
Other than that it is assumed that the development environment provides services like load and compiling groups of files aka systems, provide overviews of compilation errors, record source locations of definitions, can locate definitions and more. A tool like ASDF handles the system part.
There is a require function in Common Lisp, but it deprecated. If you simply want to split your code in one or more pieces, to use it interactively in the REPL, you can put the code in different files and then load each of them. If instead you want to write a full lisp project, I have found very useful the quickproject package, that provides a simple starting point for the creation of new packages.
I've been using org-mode for a little while, I've kept it really simple for now, with only two files :
one to act as an inbox, with remember-mode
another where I stick just about anything that's been processed from the inbox
This is great for managing somewhat 'actionable' items, but I keep adding things of a more general nature, that I won't be needing on a day-to-day basis (how-tos, reading notes etc), so it's getting slow and hard to manage.
The material I'm concerning myself with doesn't fit the /projects/tasks/sub-tasks paradigms, they are more like little knowledge nuggets on selected topics, which are inherently more complex to classify and manage.
I've been wondering what kind of structure could be used to handle that kind of information (classification and retrieval), and if there are maybe other modes that could help with the job ?
I guess there is no pre-made answer to this question, since everyone may have different needs.
Noufal gave good conceptual tips that I'll keep in mind, but overall, the accepted answer provided more pragmatic views on this, the linked resource was a GREAT read.
I think this excellent document on how to use org-mode to it's fullest potential will be very helpful to you: "Org Mode: Organize Your Life In Plain Text". It is lengthy reading, but trust me, completely worth the effort.
UPDATE:
You can use the remember-mode section mentioned in the document for your use-case. (I use it for the same use-case) Remember-mode is extremely handy to make quick notes. I use it when I have to store random observations or information that won't go anywhere else. I use the following templates for remember:
(setq org-default-notes-file (concat org-directory "/remember-notes.org"))
(setq org-remember-templates
`(("Todo" ?t "* TODO %?\n %i\n" ,(concat org-directory "/remember-notes.org") bottom)
("Misc" ?m "* %?\n %i\n" ,(concat org-directory "/Notes.org") "Misc")
("iNfo" ?n "* %?\n %i\n" ,(concat org-directory "/Notes.org") "Information")
("Idea" ?i "* %?\n %i\n" ,(concat org-directory "/Notes.org") "Ideas")
("Journal" ?j "* %T %?\n\n %i\n" ,(concat org-directory "/journal.org") bottom)
("Blog" ?b "* %T %? :BLOG:\n\n %i\n" ,(concat org-directory "/journal.org") bottom)
))
As you can see, misc notes and other information goes in the notes.org file under the headings Misc and Information. If the note I'm making doesn't fall in any of the categories defined above, it gets filed in the default file (remember-notes.org) and I can always refile it to another location at a convenient time. This makes my note-taking, jotting down random ideas, and such things extremely simple, without taking away the focus from the job I'm currently doing.
[org-mode] is great for managing somewhat 'actionable' items, but I keep adding things of a more general nature, that I won't be needing on a day-to-day basis (how-tos, reading notes etc), so it's getting slow and hard to manage.
I'm a follower of David Allen and his Getting Things Done methodology. I'm using Emacs for three of the lists he recommends:
Next Actions
Project Resources
The Someday/Maybe list
The material I'm concerning myself with doesn't fit the /projects/tasks/sub-tasks paradigms, they are more like little knowledge nuggets on selected topics, which are inherently more complex to classify and manage.
I've been wondering what kind of structure could be used to handle that kind of information (classification and retrieval), and if there are maybe other modes that could help with the job ?
For this kind of information I've migrated away from emacs. Instead I keep a directory ~/etc/howto, and in that directory I put files that contain "little knowledge nuggets on selected topics", where the key criterion is that the information has long-term value.
I could search this directory with Emacs, but my Emacs Lisp is not so hot, so I wrote a howto shell script instead (some error checking omitted for clarity):
case $# in
1) ;;
*) echo "Usage: $0 <topic>" 1>&2; exit 2 ;;
esac
topic="$1"
# Note the ordering: first exact matches, then beginning matches, then any matches
set xxx `find $HOME/etc/howto/. -name "$topic" -not -type d -print` \
`find $HOME/etc/howto/. -name "${topic}?*" -not -type d -not -name '*~' -print` \
`find $HOME/etc/howto/. -name "?*$topic*" -not -type d -not -name '*~' -print`
shift
case $# in
0) echo "No file found matching *$topic*" 1>&2 ; exit 1 ;;
*) for i
do
less "$i"
done
;;
esac
Examples include:
howto football brings up three nuggets, in this order:
Instructions to give to my wife on how to record a football game on the computer
Instructions for me as exactly what to take and how to dress when I have tickets to a football game
Instructions for transcoding a football game so it can be transmitted over the net and viewed away from home
howto filesystem brings up instructions on how to copy a filesystem
howto batteries brings up a list of recommended rechargeable batteries
One reason I don't use Emacs is that my real script is a little more complicated than what you see above: it also handles PDF and djvu files, so for example howto razor brings up a djvu document of the manual which came with my electric razor.
I have over 500 items in the main directory or in subdirectories, and even at this scale the system works quite well for me. I hope you may find it helpful too.
I personally keep a list of project directories with somewhat similar structure. Each has a tasklist.org, a tracking subdirectory (where I do project estimates and time tracking and always maintain a diary which is the main thing for the project - it will have links to other files for the project), a docs subdirectory which usually consist of stuff I'm going to publish (docs for the project, proposals etc.). I get my agenda-files to the tasklist.org in each of the subdirectories so that my agenda works fine.
I think the organisation of the data would change a little in your case (perhaps topics like "functional programming" etc.). I'm sceptical of how much a hierarchical structure would help since that would confine you into one way of looking at things (tags vs. folders again). Here are some things that come to mind.
Keep a 'master' org file that has links to all the 'interesting' top level pieces of the other content (similar to the diary I mentioned above).
Tag all your material properly (you'll settle on a set of useful tags after a while) and then use the Tag search feature to search through the files quickly. This assumes that all the files are in your agenda-files though.
Finally, if your data is too exotic to put into a structure, you can consider using a full text indexer (like xapian) and integrate that into your Emacs. There was some discussion of this over here.
Update : 26/Nov/2019
I recently came across the hyperbole package which claims to be a information organiser. I haven't used it but I'm quite tempted to and will update this when I do.
I have tried several ways to manage a knowledge base in the past. I have a bunch of "knowledge nuggets" (btw, thanks, I like that term a lot) on all sorts of diverse topics ranging from how to set up apache tomcat ssl cert, to checklists for doing a monthly family budget, to keeping a list of weights and reps completed on workouts.
I've tried keeping these in a wordpress blog, on a personal wiki, using pen and paper, etc.
In the end, emacs and org-mode is the clear winner for me. I love to have the ability to start simple, and build more complex functionality as I need it. I've used a lot of the tips described by Sacha Chua.
In my case, I always end up with a bunch of notes (more formal and organized) mixed in with action items (less formal). In general I maintain one master "action item" list and then create a separate file for notes on each topic. So far, grep has worked well for me to quickly find the file containing notes. I'll often create a emacs bookmark C-x r m to quickly navigate to notes files as well.
Simple Blogs, CMS, and wikis (like Drupal and Wordpress) are good at classification and retrieval. Maybe you could export org files to html and publish them to a blog, cms or wiki? It might not be too difficult to hook into the blog/wiki/cms tagging capability.
At work, we use a wiki (actually, several - a global wiki plus a wiki per project) for this. It's ideal for non-hierarchical data, but can also be used for hierarchical data. It's formattable, hypertextual, linkable-to, searchable, shareable but also ownable, it maintains history, and other good stuff.
Personally, i used to also use a wiki for this. But these days, i generally just forget things instead. Far easier.
You can speed up org-mode by keeping your notes in a separate file (or one for each broad topic) which is not included in the usual list of agenda files. Customise org-agenda-files to see the list.
Use org-remember to enter notes quickly without interrupting your flow. Either tag them at the time, or save them somewhere to be refiled later. You can use a tag in the remember template (customise org-remember-templates) to mark notes for refiling, and use a custom agenda search (org-agenda-custom-commands) to list them.
Tag each note with relevant topics, and use the agenda view's search facilities to find them. You can define a custom search which knows to look in the right files, or you can visit the file and restrict the agenda search to just that file.
I keep a file of notes, and your question has just inspired me to go back and start tagging them all. Works a treat!
I hold tips in .rst (reStructuredText) files in single directory. Each file have own topic.
For search I use M-x occur, or M-x lgrep, or M-x ack.
Web hosted example: http://tips.defun.work/frame.html and it is easy to turn that pages into blog like solution.
Original sources with build script: http://hg.defun.work/tips/
Main advantage of reStructuredText format:
TOC support.
include syntax.
Ability to build JavaScript based full text offline search index in HTML site with TOC, index, reference by Sphinx!!
Remember Markdown suck at extensibility, RST have regular syntax for marking data by your tokens and include any plain text format as inline into your document. Thinks about graphs with dot, prog lang syntax highlighting, etc.
The material I'm concerning myself with doesn't fit the /projects/tasks/sub-tasks paradigms, they are more like little knowledge nuggets on selected topics, which are inherently more complex to classify and manage.
Use bookmarks and Bookmark+. You can create bookmarks for sets of files and directories, in addition to individual files, and you can tag bookmarks or files, a la delicious, for organization and search purposes.