阅读 1260

双语版php7.1文档 for Dash

作为一名死coder,每天最常见的动作就是查看各种API文档,你一定也有过同时打开N个窗口(HTML、PDF、CHM),不停的在编辑器与文档之间切换的感受吧?怎么说呢,其实我很讨厌这种枯燥无味的动作,那么如何才能提高效率,减少无用功呢?下面就给大家介绍一款非常好用的Mac小工具:Dash。

官方用一句话就概括了它的用途:Dash是一个API文档浏览器( API Documentation Browser),以及代码片段管理工具(Code Snippet Manager)。你没看错,它就只有这两个功能,但确实是程序员(至少对于我来说)最为关心的特性,自己之前也用过了不少类似的工具,可以毫不夸张地说,Dash是它们之中做的最好的一个!

  1. 下载 关于下载我还是推介官网下载吧(kapeli.com/dash)

  2. 强悍的API文档浏览、搜索功能 想必这个功能是大家最常用的了吧,每天要反复查看、搜索那么多的API细节,没有一个好工具,单靠自己的双手如何应付得来?窗口不停的切来切去,很烦啊!Dash采用集成单一窗口的方式,很好的解决了这个问题。看下面的截图:

上图便是Dash的API浏览器主界面:左侧边栏是各种编程语言以及框架(取决于你下载安装了多少文档集合)的导航大纲,点击某个节点,右边的内容区域就是文档的详细信息啦,非常直观。也可以在左上方的搜索框内通过输入关键字,查找相关的API文档,非常类似全文检索的实现方式,Dash的响应速度非常快!关键是可以同时查询不同的语言、框架内容,实在是太方便了。看到这里你也许要问了,这跟我们平常切换到特定的文档窗口(比如一个PDF或者一个CHM文件),再ctrl + f查找有什么区别,不是多此一举吗?其实你错了,Dash可以通过快捷键来显示、隐藏文档窗口,它提供了配置界面以便用户自行设置(我比较习惯alt+space,因为其他软件很少用到这个组合键):

Dash自带了丰富的API文档,涉及各种主流的编程语言和框架,全列出来很吓人的: ActionScript, Android, C++, Cappuccino, Cocos2D, Cocos3D, Corona, CSS, Django, Groovy, HTML, Java, JavaFX, JavaScript, jQuery, Kobold2D, Lua, MySQL, Node.js, Man Pages, Perl, PHP, Python, Ruby, Ruby on Rails, Scala, Sparrow, SQLite, Unity 3D, WordPress, XSLT, XUL

而且它的文档库采用了docset格式,高级用户基于网站提供的教程,很容易就能自行添加其他的扩充文档,其实Dash在最初发布的时候,只支持很少的几个文档浏览,好像只有Java、HTML、CSS这些,是后来通过用户不断贡献,以及作者及时的反馈,逐步壮大,才具备了如此广泛的语言、框架支持。要添加API文档,打开软件配置界面,切换到Docset选项卡即可看到所有内置的文档列表,按需要自行下载即可(如果是自己制作的docset,双击即可导入Dash):

笔者刚接触php没多久,在dash中下载了一个php的文档,只有英文版的,php作为比较流行的脚本语言,文档官网提供了多种语言版本,本来自己想在网上下载别人制作好的php中文文档for dash,可下载下来的几个,看了一下都不太满意,本人有点完美主义,于是萌发了自己动手制作一个双语版的。

刚开始,参考了dash的官网关于制作docset的教程,还是找不着思路。后来在网上继续搜索教程,找到了一个日本网友的方法。

docset文件本质上就是一个文件夹,选中下载好的英文PHP.docset,右键显示包内容,打开文件夹

继续解压tarix.tgz,又得到一个PHP.docset,这难道是俄罗斯套娃吗,继续显示包内容,上图看一下目录层次的结构

目录的层次还真够深的,dash本质上说就是一个离线的api文档浏览器,内部就是一个safari浏览器,文档本质上就是html,下图是一个php的函数abs的页面,右键可以 inspect element(审查元素),

也可以在浏览器中打开页面:http://127.0.0.1:50154/Dash/atuxkowm/php.net/manual/en/function.abs.html

dash的原理就是给离线的html文件建立索引

我们能不能保持原有的索引不变,仅仅只是替换目录中的英文html为中文html呢,经过测试是可行的。

思路可行,但工作量着实不小,最新版的英文文档下有14888个html文件,怎么样才能弄到对应的中文html文件呢,其实php文档官网已经提供了,

上图中左边的红框是不包含用户笔记版的多html文件,右边红框是包含用户笔记的chm文件(可以解压成多个html文件)。细想一下都不太符合我的要求,我要的中文版必须要有用户笔记,排版也要和英文版的一致,chm文件中的排版缺了面包屑导航,而且解压chm文件也很麻烦。

无意间查看了一下英文版的html源码文件,发现了每个html都有下面的注释

<!-- Mirrored from php.net/manual/en/about.formats.php by HTTrack Website Copier/3.x [XR&CO'2014], Tue, 02 Oct 2018 07:42:58 GMT -->

搜索 HTTrack Website Copier 之后,才知道这是一个专门下载网页离线到本地的一个工具,原来官方的php dash文档是这么搞出来的,我又兴冲冲的研究这个离线下载的玩意,最后搞了很久,还是放弃了,我原本只想下载中文的文档,也许是我没配置好,下载的中文目录中居然还下载了别的语言的版本,下载的时间遥遥无期,等不及。

后来自己琢磨了一下,根据html的文件名称很容易推导出中文文档的在线名称,比如:function.abs.html的 地址就是:php.net/manual/zh/f…

我想到了一个idea,那就是遍历英文文档的目录,得到文件的名称,然后根据推导的名称下载文档。 具体的下载方法就是写一个php的脚本,用curl下载网页。

经历了一番调试、再调试的折腾后,也花了很长的时间,终于把中文文档下载下来了。又遇到了新的问题,中文文档里面的链接很多都是指向php的,离线之后的是html文件,不匹配,还有样式的链接还是指向线上的,于是又花了一番功夫对中文文档做了一些正则的匹配替换,改写离线的样式文件,最后对中英文的文档都加上了相互的链接,制作成了双语版的php dash文档。

追求完美的我,其实最后还是被打败了,因为有极少数的英文文档没有对应的中文文档,那这个其实是php官方的事情了,我也没辙,那就这样呗。

最后附上,我制作的 最新php7.1的双语版dash 文档的下载地址

关注下面的标签,发现更多相似文章
评论