vnote 笔记插件引导教程

February 20, 2017 · View on GitHub

vnote doc

这里通过一个简明的引导教程来说明该工具提供的主要功能（及玩法）。

生成测试示例日记库

为了快速开发，我用自己熟悉的 perl 语言写了几个（非关键的）脚本，用于辅助测试。 运行以下命令：

$ cd ~/.vim/bundle/vnote/gen
$ ./genbox.pl ~/notebook-test

将生成 ~/notebook-test 目录，作为一个笔记本。如果不提供目录参数，./genbox.pl 命令将在当前目录下生成一个 _box 目录作为笔记本。

该脚本会生成从 2000 年至 2010 年之间，每天生成 10 个日记文件，按年月日的目录层 次组织。可以用 shell 命令 cd 与 ls 进入相应目录进行查看。

刚生成的 ~/notebook-test 日记本目录下，只有一个名为 d/ 的子目录（按 date 组织的意思），其下才是 yyyy/mm/dd 的目录结构，在每天目录下，每个日记文件的命 名格式为 yyyymmdd_n.md，其中 _n 是从 1 开始的递增的数字，表示在当天建立的 第几条日记/笔记。例如，运行如下命令：

$ cd ~/notebook-test
$ cd d/2000/01/01
$ ls

将列出十个文件名：

20000101_10.md  20000101_1.md  20000101_2.md  20000101_3.md ...

纯数字的文件名虽然有规律易管理，但从文件名中可得知的信息太少。所以在仓库中 gen/ 下另提供了一个简单脚本 notelist.pl，在列出日记文件名的同时，还将列出 文件内容的第一行视为日记标题。例如运行以下命令：

$ alias nls=`~/.vim/bundle/vnote/gen/notelist.pl`
$ nls
$ cd ~/notebook-test
$ nls d/2000/01/01

可见每个文件名将输出一行，左侧是日记文件名，右侧是日记标题。不过 genbox.pl 生成的日记，只是一些无意义随机字符串。然而也可打开任一日记文件，查看日记文件格 式的约定规范：

$ cd d/2000/01/01
$ cat 20000101_1.md

输出内容大致类似如下：

# 日记标题xxxxxx
`标签1` `标签2`
`父标签/子标签`

日记正文 blabla xxxx

可见日记文件就是遵循 markdown 语法的纯文本文件。不过将第一行视为日记标题，其后 可有几行标签行，每个标签用反引号括起，标签支持层次结构。这篇 readme 文档也采用 这个约定，可观测显示效果。

总结一下，本插件工具将要支持的日记本规范要点：

  • 日记本就是在文件系统中的一个目录；
  • 所有日记文件在日记本主目录下的 d/ 子目录下按年月日（yyyy/mm/dd）组织；
  • 日记文件再按 yyyymmdd_n.md 格式命名；
  • 日记文件内容第一行视为日记标题；
  • 文件前几行以反引号括起的字符串视为日记标签。

建立日记本的标签系统

由于日记采用纯文本格式，理论上可以借用任何 grep 搜索工具来查找日记。不过全文搜 索是比较无序、随机的，所以这里引入一套日记标签系统（类似许多其他笔记软件的标签）， 基于标签就可比较有目的性、定向地搜索（或浏览）日记了。

个人手写的日记/笔记本库或许规模不会很大，但为了尽可能有效地支持较大规则的日记 本库，我选择了使用 C++ 写这个工具。

假设 vnote 可执行程序已安装至 ~/bin 中，且该目录已被添加至环境变量 PATH 中。 运行如下命令：

$ vnote -d ~/notebook-test -ctQ

命令行工具 vnote 支持诸多选项参数，在不带参数直接运行时会显示简要说明。在上个 命令中，-d 选项用于指定日记本根目录，-t 选项要求生成标签文件，-Q 表示立 即退出，否则会进入命令行交互模式进行日记查询（用 Ctrl-D 结束）。

上述命令成功执行后，会在 ~/notebook-test/t 目录下生成大量标签文件。凡是在 d/ 子目录下的任一日记中出现过的标签，都会生成一个相应的标签文件，以 .tag 作为后缀名；多层次标签则在 t/ 目录下再生成子目录。例如：foo/bar 标签将生成 t/foo/bar.tag 文件，bar 标签将生成 t/bar.tag 文件，如果还有个 foo 标签 ，则也会相应 t/foo.tag 文件（即在 t/ 目录将同时存在 foo.tag 文件与 foo/ 目录）。

标签文件 *.tag 也是纯文本文件，每一行记录一个包含该标签的日记文件名及其首行 标题，与上节介绍的 gen/notelist.pl 输出类似，不过为了节省紧凑节省点存储空间 ，日记文件名不包含 .md 后缀。

在 Vim 中使用日记本

(1) 打开日记本 :NoteBook

前两节主要介绍的是日记及相关的概念模型。日常使用时却基本只需在 vim 环境中。 假设本插件已顺利安装，打开 vim 后，在命令行中输入：

:NoteBook

本插件提供的命令都以 Note 开头，在输入 Note 之后就可以按 Tab 键补全，若不能补 全，则可能是插件没安装成功。不带参数的 :NoteBook 命令将回显当前日记本的根目 录，默认是 ~/notebook 。由于刚才用 genbox.pl 脚本生成的测试库是 ~/notebook-test，也可用该命令切换至这个日记本目录：

:NoteBook ~/notebook-test

(2) 打开日记列表 :NoteList

然后输入日记列表命令：

:NoteList

这时 vim 将打开一个 buff 窗口，其文件类型 &filetype 被设为 notelist。

不带参数的 :NoteList 命令将列出当天的日记。由于生成的测试日记本介于 2000-2010 年间，故今天的日记列表是空的。只有三个固定的抬头文本，类似：

$ note-book <当前日记本目录全路径>
$ note-list -d <今天的日期 yyyy/mm/dd>
==============================================================================
<日记列表或空>

第一行显示当前日记本，第二行显示此时日记列表的参数，第三行是分隔线，其后是正文 日记列表。

(3) 按日期浏览日记目录 D

当光标处于 notelist buff 窗口时，按下 D 快捷键，则第二行的列表参数变成 note-list -D，然后列表中展示日记本 'd/' 目录实际含有日记的所有年份子目录。用 jk 移动光标选定某年后按回车 <CR> 将进入该年份子目录，再列出其下所有月份子 目录。如此向下直到进入具体某一天的子目录时，就列出该天子目录下的所有日记列表， 同时第二行 note-list 选项参数也从 -D 改回 -d 了。

(4) 从列表中打开日记 Enter

日记列表的第一行代表一个日记文件，显示其文件名与首行标题。文件名不包含后缀，标 题会移除前导的 # markdown 语法标记。

移动光标选定某个日记，按回车 <CR> 就能打开该日记。日记文件的 buff 窗口，其文 件类型应该变成了 markdown。此时就能将其当作正常的 markdown 文件进行编辑，如 果所用的 vim 之前安装了其他支持 markdown 的插件，一般也能正常利用。

(5) 从日记中回到列表 Ctrl-]

在打开 markdown 格式的日记文件时，普通模式下使用快捷键 <C-]> 就能回到日记列表 窗口。根据按键的上下文，将进入不同的列表模式：

  • 在绝大部分情况下，<C-]> 将使用 '-d' 选项列出当天的所有日记；
  • 如果光标定位于某个 标签 下，将使用 '-t' 选项列出属于该标签的所有日记。

请尝试用快捷键反复在日记列表与日记文件中跳转切换。

(6) 按标签系统浏览日记 T

按标签的日记列表需要日记本目录下 t/ 子目录的标签文件支持，其实日记列表直接从 相应的 *.tag 文件读取。

当光标处于 notelist buff 窗口时，按下 D 快捷键，则第二行的列表参数变成 note-list -T，下面的列表则表出所有用到的标签，选定某个具体的标签（可能需要进 入子目录）后回车，再回归 note-list -t 模式，列出该标签下的所有日记文件。

(7) 日记列表的更多快捷键

日记列表 note-list 有四种选项参数，-d -t -D -T。可以用命令 :NoteList 直接带参数打开。

  • :NoteList [yyyy/mm/dd] 列出指定那天的日记，无参数时默认今天；
  • :NoteList tag 列出包含某个标签的所有日记；
  • :NoteList -D [yyyy/mm] 浏览 <notebook>/d 子目录，可指定部分目录；
  • :NoteList -T [tagpath/] 浏览 <notebook>/t 子目录。

注意，命令 :NoteList 需明确输入 -D 或 -T 选项，但不用输入 -d -t 选项 ，自动根据参数是否像日期来选择按日期列出日记还是按标签列出日记。

当按日期列出日记时(-d 选项)，还另外提供快捷键来列出前一天/后一天的日记：

  • <C-a> 增加一天，列出后一天，<C-x> 减少一天，列出前一天；
  • <Left> <Right> 左右方向键分别列出前一天与后一天的日记；
  • <Down> <Up> 向下向上方向分别列出前一月与后一天的日记。

日记列表默认只列出日记标题信息。但在某条日记上按下空格键 <Space> 则会展开一 行，将该日记的标签也列出来。当光标移到某个标签下时，按 t 键将列出该标签下的 日记。光标在文件名时按 t 键，则列出该条日记所在那天的所有日记 （只在原来按 -t 列表时有意义，否则 -d 时必然是同一天的列表，切换无意义）。

  • <Space> 切换展示标签行
  • D 浏览日期
  • T 浏览标签
  • t 按光标上下文切换日记列表

(8) 多窗口支持

从日记列表中打开某个日记文件时，如果当时有多个窗口，则将在另一个窗口中打开日记 ，保留日记列表窗口可视。否则若仅有唯一的窗口，则打开日记后将覆盖原来的列表窗口 。

当存在一个日记列表窗口时（文件类型为 notelist），再通过任何命令或快捷键打开日 记列表时，将复用那个日记列表窗口，并可能用新参数更新日记列表。否则在当前窗口载 入日记列表。

当决定要用多窗口时，用内置命令 :split 或 :vsplit 分裂窗口。

建立自己的日记本

(1) 为日记本创建一个根目录

当在测试日记本 ~/notebook-test 玩转稍熟后，就可以建立自己的日记本了，随手记 录自己真正想记录的东西，并在以后能方便地找回记录的文字。

因为 vnote 插件加载时默认打开 ~/notebook 这个日记本，那就先建立这个目录：

cd
mkdir notebook

尽管虽然或许该插件保存日记时可能会自动建立这个目录，但如此标志性的一步，还是手 动创建个目录吧。

原来那个生成的测试日记本，确定不用后可用 rm -rf notebook-test 删除。但也可先 保留，本节介绍的新建、编辑日记等功能也仍可在该测试库中练习。

重新启动 vim 让 vnote 插件默认打开 ~/notebook 日记本， 或直接原 vim 会话中输入以下命令打开：

:NoteBook ~/notebook

如果喜欢将日记本创建在其他不同的目录中，也须用 :NoteBook 带相应的目录参数打 开。

(2) 新建日记 :NoteNew

在 vim 命令行中输入以下命令：

:NoteNew

该命令没有其他参数，将在今天的目录下新建一个日记文件，文件名类似 <today>_1.md。 在打开的这个文件中编辑一些内容，用 vim 内置的保存命令 :w 将写入 <notebook>/d<today>/<today>_1.md 路径文件。

继续用 :NoteNew 命令，将新建 <today>_2.md 日记文件。

(3) 保存日记及更新标签 :NoteSave

在编辑日记文件时，最好略加思索，添加几个关键字作为日记标签。用反引号（~符号 那个键）括起每个标签，输入标签的几个规定：

  • 标签行必须以反引号开头，即标签前不能有其他无关内容，但之后有无关内容不管；
  • 一行可以输入多个标签，每个标签分别括起；
  • 标签可以分几行输入，但必须连续的几行，且须在文件的前十行之间；
  • 为避免不必要的管理麻烦，在反引号内的标签不要包含空白及其他特殊字符；
  • 经测试，utf-8 编码时，中文标签及中英文混合标签支持无问题。

当光标停留在标签行，一般是在编辑标签后刚从 vim 插入模式回归普通模式时：

:NoteSave

命令将保存日记文件的同时，更新标签文件。也可以在普通模式下直接使用快捷键 ;w （是分号w，而冒号w是内置的写入命令）。

当光标不在标签行时，例如在其他地方修改过文件后，按 ;w 键或 :NoteSave 时， 则只保存日记文件本身，不更新标签文件，认为标签没有改动过（事实大部分情况也如此）。

(4) 打开日记 :NoteEdit

当在 vim 中关闭了日记文件，用 vim 去干些其他之后又想回来继续编辑日记时，命令：

:NoteEdit

将打开当天的最后一个日记文件（日记编号最大那个，或最近新建那个，而非最近编辑过的那个）。

该命令其实支持最多两个参数 :NoteEdit [yyyy/mm/dd] [number] ，指定打开某天的 第几个日记文件。日期参数的默认值是今天，编号参数的默认值是最大编号。

(5) 重建标签索引

在写日记、记笔记过程中，命令 :NoteSave 将自动（或半自动）更新标签文件。但是 ，如果删除或修改了某个标签，该插件是没法更新标签文件的，另外，若用外部命令删除 了日记文件，也无法同步更新。

一般情况下，当真想要认真做笔记时，最好先规划一下自己的标签体系。在逐步添加日记 过程中，若标签只增不删的话，则这个纯 VimL 插件也能良好地维护日记本的标签系统。 当日记数量增大后，出于任何原因，都可用那个编译的 C++ 外部工具重建索引：

$ vnote -d ~/notebook -ctQ