1 Note-taking

Refer to module 0355 for reasons to take and matintain notes.

2 Note environment

There are many alternative note environments to take, store, maintain, organize and review notes. Some are proprietary, some are web/cloud based, and some are free. This article proposes a note environment that is based on Linux/Unix command line tools. Although this approach is Linux-tested, it probably applies to any environment that provides the same set of basic command-line tools, including Cygwin. Cygwin provides a Unix-like command-line environment in Windows without the use of any virtual machines or large foot-print software.

3 Note-taking

Using command-line tools to take notes can be done, but it requires a great deal of proficiency to the extent that the mechanics of note-taking can easily interfere with the flow of ideas being captured. As such, it is best to take notes, especially in a real-time lecture, using a free-form approach. Free-form note-taking can be done using paper and pencils! For the technophiles, a tablet that supports a stylus for handwriting can also be used.

After the real-time lecture, however, the free-form notes can be entered in a digital form. There are many advantages to digital notes. Digital notes can be backed up easily, it is searchable, and it can be organized in a non-linear fashion.

3.1 Digital note format

One of the best formats to record notes digitally is Markdown. “Markdown” is actually a mark-up language, meaning that it is used to encode formatting in plain-text. It is called “Markdown” as a play of the term “mark-up language” because Markdown is relatively simplistic compared to other mark-up language.

For example, to use headers and bulleted lists, the following is an example in \(\LaTeX\):

\section{top-level section}

A paragraph in the top-level section.

\subsection{second-level section}

The following is a bullet list:

\begin{itemize}
  \item first item
  \item second item
\end{itemize}

HyperText Markup Language (HTML) is not much better:

<h1>top-level section</h1>

<p>A paragraph in the top-level section.</p>

<h2>second-level section</h2>

<p>The following is a bullet list:</p>

<ul>
  <item>first item</item>
  <item>second item</item>
</ul>

In Markdown, however, it is relatively simplistic:

# top-level section

A paragraph in the top-level section

## second-level section

The following is a bullet list:

* first item
* second item

3.2 What about word processors?

Word processors, such as Microsoft Word, LibreOffice Write, Google Doc, etc., seem easy to use due to their WYSIWYG nature. However, this apparent ease of use has a price: flexibility. A Word processor does not store the content in plain text format (that can be opened in a plain text editor like Notepad in Windows). As a result, word processors are closed-end tools. A user is locked in after creating a good amount of documents.

By comparison, Markdown is not a tool, it is a language to express content. It is also an open-standard. This means the content creator (you) can choose the editor. The editor can be Notepad in Windows, vi in Linux, or any plain text editor that works in any operating system.

Furthermore, because the content is plain text that is human readable, Markdown content can be tracked using revision management tools like git. Most word processors offer some form of revision tracking mechanism, but such mechanism is proprietary to the software.

3.3 Training wheels

Although Markdown is relatively easy to learn, there is a perceivable learning curve. There are many tools that serve as training wheels to learn Markdown. For example, Joplin provides alternatives to learn Markdown. One can use the WYSIWYG interface to create content, then switch to Markdown view to see the formatting. Or, one can create content directly in Markdown, and use the instant-preview to see the formatted outcome.

For brave souls who choose to start with vi, neovim (Neo (new) vi Improved) has plugins that provide live-view of the formatted content in a browser.

4 Notes organization

Taking notes can help maintain focus and concentration, especially during a live lecture. Notes can also help build, maintain, and even visualize relationship between concepts. This relating is the core of how concepts are “understood.” Complex concepts have a high fan-out ratio, meaning that each concept is connected many other concepts.

Physical and written notes are difficult to organize because they are not electronically searchable, and hyperlinks do not exist. Notes that are in digital form, such as Markdown, can be searched, indexed, and cross-referenced.

4.0.1 Defining and referencing definitions

Once a definition is recognized, it is useful to “label” it so that it can be referenced. Some note-taking tools can recognize words being defined. However, this can also be done manually and yet systematic way.

The naming of a label should be structured to have a consistent naming method. For example, “r function for base-10” may have a corresponding label of definition:function:r:base10. Note how the label name is structured like a file path, or a path of members in object-oriented programming.

The mechanism to define a label translates to anchors. In \(\LaTeX\), this can be done using the following code:

\hypertarget{definition:function:r:base10}{$r(x,y)=(x+y) \mod 10$}

Markdown does not have a native method to define anchors, but you can use HTML anchors in Markdown documents:

<a name="definition:function:r:base10>$r(x,y)=(x+y) \mod 10$</a>

To reference an anchor in \(\LaTeX\), there are two ways. For anchors of the same document, it is simpler to use \hyperlink{definition:function:r:base10}. However, to reference anchors of a different document, \href{../0283/module.html#definition:function:r:base10} is a more general method.

Markdown has built-in support to create hyperlinks. For targets of the same document, [Refer to function r](#definition:function:r:baseB) is sufficient. The format to reference an anchor of a different document is not much different: [Refer to function r](../0283/module.html#definition:function:r:baseB).

4.0.2 Finding definitions

find ${MODULE_PATH} \( -name "moduleContent.latex" -or -name "mdModule.md" \) -exec /usr/bin/grep -H "definition:$1" '{}' \;

This command is a little complex:

• ${MODULE_PATH} uses the environment variable MODULE_PATH to specify where to look for the definitions.
  • The environment variable can be set up using export MODULE_PATH='/path/to/the/folder', typically in ~/.bashrc.
• \( and \): because ( and ) have special meaning in BASH, they are escaped to be used as regular parentheses to specify the condition to look for with find.
• -name "blah" specifies a match requires a name of "blah".
• -or is a disjunction so that more than one match can be specified, if at least one match works, then the operator returns true.
• -exec' specifies a command to run. Because it is after the parenthesized-or, this counts as a match that is anded with the result of the-or`.
• /usr/bin/grep is the command to run. If the command has an exit code of 0, then the -exec condition is considered true.
• -H specifies that grep prints the name of the file.
• definition: is the string that we are looking for. Note that this will find both definitions and references.
• $1 refers to the first argument on the command line, this can help further refine which definition to search for.
• '{}' specifies the name of the file that find is working on. The single quotes are needed because braces {} have special meanings in BASH.
• \; is also escaped because a semicolon (;) has special meaning in BASH, but it is also used to terminate the -exec match. In this case, we need to make sure the semicolon is seen by find, and not processed by BASH.