mindoc – 张三太爷

mindoc 的一个 bug

张三太爷 — Fri, 27 Nov 2020 02:15:09 +0000

老夫维护的 mindoc 的分支版本，里面有个功能是可以把某个项目 pin 到起始页的前部，类似于快捷启动。

前两天突然发现有的项目上不会出现我添加上的 pin/unpin 的开关按钮。昨晚跟了一下，发现原来是由于项目多了以后分页导致的。分页获取到的项目，组合前端 HTML 时没有把 pin 相关的代码加上。分页返回的模板文件是 /views/items/home_list.tpl，抽个时间想法补上应该就可以了。比较奇怪原来为什么没有在起始页中复用这一段模板代码。

具体解决方案是：
1. 把 /views/home/index.tpl 中 $(".pin-tag").each 的那一段脚本包装成函数 updatePinStatus()，页面加载时执行一次调用；getItemBook() 内也需要调用；
2. 在 /views/home/index.tpl 中修订 pin() 函数，将 pinListItemHtml 字符串中的 div 元素的 class 属性，除 list-item 外增加 pin-tag（因为 updatePinStatus() 隐藏 pin 图标的依据就是遍历带有 pin-tag 的元素）；
3. 在 /views/items/home_list.tpl 中的 dt 元素里加入

4. 在 /views/items/home_list.tpl 中的 dt 和 dd 元素里，给封面图的 img 元素和超链接 a 元素加上 id（前缀分别为 item_img_ 和 img_a_）；
5. /views/items/list.tpl 中的内容，是否跟 home_list.tpl 同步处理需要再看一下。

mindoc 文档下载二三事

张三太爷 — Wed, 18 Mar 2020 10:27:39 +0000

mindoc 的文档，是可以下载的。

mindoc 的作者一直坚持把整个项目作为导出/下载的最小单位，而不是单篇文档，这是我很难接受的状况，事实上，我觉得很反人性。于是在他转换器改变的前后，我都对代码进行了增订，加入可以单篇导出的能力。后一次的修改起手是由一个已经离开团队的兄弟主刀的，里面的代码被我后来 review 的时候改了不少，因为实在是看不下去那种复制粘贴的路子。

下载支持若干种格式，例如 PDF、Word、ePub 甚至 mobi。从 markdown 转换到这些其他的格式，所用的转换器经历过一次大替换，现在的后端转换程序是 Calibre，之前应该是 pandoc 吧，记不清了。当然，首要支持的，必须是 markdown 本身。我修订代码时主要关注于逻辑本身，没想到在一个小地方遗漏了原来代码一直存在的一个 bug。由于 markdown 可能会引用到图片，因此下载时就要把图片和文档 zip 到一起。生成的 zip 文件所处的路径，原代码里设定的访问权限为 0644，然而，这会导致 beego 框架里 BeegoOutput 的 Download 方法失败，看信息是访问被拒绝，改成 0755 就好了。

在上面的调试过程中，还发现当 beego 返回给客户端浏览器的下载文件名里如果有空格的话，会导致 Firefox 只采用第一个空格前的那部分，而 Chrome 浏览器无此问题（均在 Ubuntu 18.04 下操作的）。找了一下资料，原来此问题由来已久。根本原因在于，当服务器组装 HTTP 头中的 Content-Disposition 值的时候，没有在文件名前后添加双引号所致。在 beego 项目的 context/output.go 里的 Download 方法中可以找到代码。鉴于此项目是个框架，我忍住没上手修补。

说回到文件格式转换。新一代使用了 Calibre 的 convertor 的作者是另一位代码贡献者，他从 mindoc 分叉出了叫 bookstack 的项目以及同名站点。Calibre 看上去支持很多种格式转换，但是转换的结果却非常勉强，把一个不是很大的项目生成为 PDF 要花好长时间，最郁闷的是，生成的文件极大，可能是把字体全部嵌进去了，字体的体积占用接近 50MB。这简直是噩梦，即使是在内网。我寻找了一下解决方案，自动化的还没有眉目，需要手工操作的步骤见下，但需要 Adobe Acrobat 的协助。

用 Acrobat 把 PDF 打开，然后在文件菜单里选择导出内嵌式 PostScript，这样的话，这个 PDF 会被分拆为单页的 eps 格式。打开 Acrobat 自带的 Distiller，在界面里把“默认设置”选择设为“最小文件大小”，从文件菜单把刚才生成的所有 eps 文件添加进来，它们都会被自动转换为对应的单页 PDF 文件。最后再用 Acrobat 把这些单页 PDF 合并为一个 PDF。如何才能自动化地做到这些事，依然需要探索。

我注意到 Acrobat 的“优化 PDF”功能有一个“高级优化”，从界面上看是有对嵌入字体的专门处理的，但是操作中发现，此处不会列出文档内实际内嵌的哪怕一种字体。理论上产品不应该存在如此巨大的缺陷，我只能推测 Calibre 生成的 PDF 可能在某些地方对 Acrobat 造成了判断上的干扰，尽管后者的文件成分分析功能能够准确显示出字体部分占据了整个文件体积的 99%+。

另外，尽管我在编译 mindoc 时已经制定了 -w -s 的 ldflags，但是当用十六进制编辑器打开生成的最终可执行文件时，仍然能看到其“密实”程度是非常差的。

mindoc 历史文档比较功能相关的几个备忘

张三太爷 — Thu, 05 Mar 2020 03:21:49 +0000

1. mindoc 的历史文档比较，使用了 mergely 这个前端控件，但并非直接使用，而是使用了名为 mergely-editor 的插件，链接在 https://cnpmjs.org/package/mergely-editor；

2. 插件里面为工具栏按钮提供了 icon 的图片，但是说实话，美观度并不好；更好的方法是使用 awesome font，字元我都找好了，但是 mergely-editor 是自包容的，除非必要我也没准备对其动手术，为它引入对惊奇字体的依赖，不过为了不至于让寻找合适字元的工作完全湮没，把所对应的代码放上来，也说不定哪天就用上了。

compare.tpl：



    {{if eq $.Mode "edit"}}
     保存合并
    
    {{end}}
     上一处差异
     下一处差异
    {{if eq $.Mode "edit"}}
    
     合并到左侧
     合并到右侧
    {{end}}
     左右切换

3. 另外，发现了一个新的开源文档平台，叫 mm-wiki，看上去挺不错，但是如果迁移或者直接采用的话，老夫就没有练手的项目了。在 https://github.com/phachon/mm-wiki。

mindoc 支持查看文档历史的实现思路

张三太爷 — Wed, 05 Feb 2020 09:22:05 +0000

在 mindoc 中查阅文档时，有时候会有与历史版本进行比对的需求。mindoc 对文档的编辑历史是有支持的，但是把它放在了编辑模式里，查看模式中并没有放开。这使得通过简单的改进就能够满足需求成为可能。

经过简单探寻，得到其处理历史文档的 URL 为 /history/get?identify=mindoc&doc_id=184 这样的。访问此 URL 可以得到该文档的历史记录列表，每一项都有“删除”、“恢复”和“合并”三个选项。由于要做的是查看模式下的历史调阅，所以显然，这三个操作应该被一个“查看”取代，从实现上，可以是在原“合并”的基础上进行，因为该功能本身就有一个左右对比的浏览视图。

直接访问历史列表获取的 URL，其返回内容如果直接显示于浏览器完整客户区在美观度上并不太好，也可以直接采用像编辑模式中弹出模态对话框的方式。

涉及到的后端源文件主要是 DocumentController.go，其中的 History() 和 Compare() 是重点。

附。昨天解决了置顶功能的一些小体验瑕疵。原来的图标是个图钉，意为 pin/unpin，但是没有 unpin 的对应图，都使用同一个图看上去有点奇怪。在网络上找图钉的钉住和取下的免费图片，花了不短的时间，没有满意的。后来退而求其次，找五角星的实心和空心透明背景图，在 pngtree.com 这个网站，还用微微魔宝的 GMail 账户注册登录后才下载到。结果再一看源代码，原来的图钉并不是图片，而是 Font Awesome 里的一个字符。顺着既有思路，也去其中再找合适的，最开始找到了旗帜（flag）的实心和空心图，后来又找到了书签（bookmark）的实心和空心图，都不满意，最后还是用上了心（heart）的实心以及空心图，效果还不错。顺手还改正了一两处原来代码有的微小问题。