Xulihang修改

2025-08-08 10:28:50

软件的技术文档会详细记录软件的使用方式，为我们使用软件提供指导。

根据用法，软件可以分成很多类：

• 命令行软件
• 图形界面软件
• 软件类库/SDK

不同软件的文档的内容基本都是接近的，主要是各种指南，介绍如何操作软件，只是图形界面的软件截图会多一点。然后，软件类库或者SDK，会提供API文档。

下面我们会介绍下如何编写软件的技术文档。

工具选择

传统的文档形式有CHM、PDF、Word文档等等，使用FrameMaker、Microsoft Office等软件制作。

现在一般都是在线网页，有一系列的站点生成器，比如Sphinx、mkDocs、Docusaurus、Jekyll、GitBook等等，使用markdown、restructuredText等标记语言编写。这些工具通常还支持生成DITA、LaTex等文件。

针对API文档，也有专门的工具，可以直接根据程序源码生成文档，比如Sphinx、JSDoc、JavaDoc、Swagger等。

更多工具介绍可以见这篇文章：技术传播领域的工具。

内容安排

文档站点主要由目录树和内容页面构成。内容可以根据软件特点进行分类，比如软件介绍、使用指南、API文档、常见问题、变更记录等等。

API文档的内容安排上，除了单独的接口页面，还要有能显示所有接口列表的页面，方便浏览。

格式规范

技术文档通常需要遵循一定的规范。这里以JavaScript语言的API文档举例。

首先，API可以进行一个分类，比如按命名空间、类、接口、定义、事件、枚举进行划分。

然后不同类别的内容，也会有编写的规范。

命名空间主要列出它包含哪些静态方法、对象、类。

类主要包含它的属性、方法和继承关系。TypeScript中的接口（interface）和类相近。

事件主要描述它包含哪些参数，要怎么绑定事件。

示例文档

命名空间

## Namespace XLH.OCR

### Methods

* getOCREngines()
* on()

### Properties

* error
* version

### Members

* Enum_OutputFormat
* Enum_SegmentationMode

### Classes

* BaseOCR
* OCRSpaceOCR
* GoogleOCR

类

## Class GoogleOCR

Extends `BaseOCR`

## Constructor

Creates a new Google OCR object.

Syntax:

\```ts
new GoogleOCR()
\```


## Methods

### detect()

Detect text in a image.

Syntax:

\```ts
detect(source:HTMLCanvasElement|HTMLImageElement):OCRResult
\```

Parameters:

source: the image to detect. It can be a canvas element or an image element.

## Properties

### apiKey

The API key for Google Cloud OCR API.

接口

## OCRResult

Syntax:

\```ts
interface OCRResult{
  textLines:TextLineResult[];
}
\```

事件

## OCRProgressEvent

Triggered when the OCR progress info is updated.

Syntax:

\```ts
XLH.OCR.on("OCRProgress",function(event:OCRProgressEvent) {
  console.log("progress: "+event.progress);
})
\```

Instance properties:

progress: progress of the OCR action. The value is between 0 and 1.

2025-08-03 17:55:50

生命不息，折腾不止。我打算开篇文章记录下我折腾过的手机。主要以时间顺序进行记录。

多普达818pro

我爸2007年炒股赚钱后，买了台多普达PPC，让我第一次接触到了智能手机。

接触了各种论坛，学会安装软件、刷机、制作ROM，折腾各种GPS软件。

经由Pocket DOS，我又开始折腾给电脑安装各种系统，封装启动光盘镜像、接触了AU3编程。

三星J708

我爸给我妈买的三星翻盖功能机。1700元，有拍照、FM、百宝箱等功能。

支持各种安装Java软件，不过屏幕分辨率只有128x160，而且性能有限，可以适配的软件不多。

我还跟着教程学习了J2ME开发，写了一个乘法软件。

HTC G1

安卓出来后，2010年上高中前，我让我爸给我买了台二手HTC G1，1100元。

当时安卓的热度很高，安卓网、机锋网的版块可能都有上万的新帖。我学习了安卓软件安装、刷机，了解了recovery、app2ext、root等等概念。

G1是全键盘手机，当时装了GBA模拟器玩光明之魂玩得挺爽。

12年家里买了汽车，我还在G1上安装了凯立德来做导航。

中兴U956

13年高考结束，我考虑买台自己的手机。当时江南大学给我发了移动的卡，我就打算买台支持移动网络的手机。

一开始我是想买HTC的，但看了下几款手机都比较贵。然后无意中刷到了中兴U956，搭载联发科MT6589四核CPU、1GB内存、5英寸OGS全贴合屏幕，还只要1000元，于是喜欢性价比的我直接就买了。

买了U956后不久，小米推出了红米，类似的配置，只要799。

当时5寸的屏幕已经是非常大了，拿出去别人都觉得有点夸张。

那个时候第三方ROM还是很多的，我自学ROM移植，移植了乐蛙OS、MIUI等系统。最后停留在乐蛙OS 5。

iPhone 5c

偶然逛论坛，了解了iPhone有锁机。这种iPhone价格很低，没用过iPhone的我也心动了，找了家TOMPDA的卖家，花1500元买了台16GB蓝色的iPhone 5c。

一开始用卡贴适配移动卡，但这种破解方式不完美，后来超雪出了适合电信的较完美的卡贴，我又买了张电信卡来用。

升级系统到iOS 8后，我直接越狱装Cydia，安装第三方输入法、各种插件、本地Python用来跑搜狗校园网代理等等。

为了体验iOS开发，我还在电脑上装了MacOS X Mountain Lion黑苹果系统。

iPhone 5c是我大学时候的主力机，从大二用到研一。

HTC 8X

Windows Phone作为当时三大手机操作系统之一，我也一直想体验一下。于是300多买了台二手的Verizon HTC 8X。

2015年，我跟着视频较系统地学习了Windows Phone开发，还上架了江南听雨BBS的客户端。

摩托罗拉G2

因为要去美国，有锁的iPhone不能用当地网络，我就又花700多元买了台国行的Moto G2 (XT1079)，移动联通双卡4G，8GB存储，1GB内存。

我给它刷了基于安卓6的CM系统，还有绿色守护，在当时使用起来还是比较流畅的。

这台机器的一个特点是使用了JDI的5寸 LCD屏幕，看起来有斜纹，但显示效果还是不错的。

Yota Phone 2

俄罗斯的手机品牌，推出了双屏手机，前面是OLED屏，后面是墨水屏，而且刷新率很高。

我花600多元买了台二手的来体验。看书效果还是很好的，我用它看完了哈利波特的前两部。

Yota的FM功能支持的频率范围比较广，还能收听FM85校园广播。

可惜，研一的寒假，被汽车碾碎了。

海信A2 Pro

Yota Phone坏了后，我还是想买台双屏手机。于是2018年花2500元买了台海信的A2 Pro，是我买的最贵的手机。

它也是前面OLED，后面墨水屏的设计。不过OLED屏的频闪比较明显，需要我把亮度开到最高，然后用护目镜调节屏幕颜色来调暗屏幕。当时安卓7上护目镜效果还比较不错。

夏普Aquos S2

2020疫情期间，A2 Pro的关机键失灵，我便又考虑换机了。

当时主要想买台轻便的LCD手机，于是看中了屏幕质量很好的夏普Aquos S2，正好有家店，700多能买到全新版本。这台5.5寸的全面屏手机，重量只有140克，搭载了骁龙630的CPU，比625性能还好一点。

不过这款2017年推出的手机，在2020年用，性能上还是略显捉襟见肘。

买S2前，我还尝试了小米CC9，但它的OLED屏看一会就眼睛疼，最后还是重新选择用LCD手机。我给我妈挑的两款手机，小米5x和华为nova 7 SE也都是LCD屏幕。

OPPO A72

2022年，夏普S2频繁重启，我就又打算换台轻便的LCD的手机。

因为已经流行OLED手机了，可选择的机器不多，我最后选择了重量175克的OPPO A72。它有1080P的全面屏，天玑720处理器，4040毫安时的电池，虽然是千元机，还是非常够用的。

其它二手手机

我还买了些便宜的二手手机，用来体验和收藏的：

PPC：HTC D810、P860、Diamond、CHT9000、818，当年几千元的PPC手机，只要几十元，我把有名的几个型号都买了。最近又49元买了台2013年出的Opticon H-21带激光扫码的PDA。

Windows Mobile 10：Windows 10出来后，我买了台诺基亚的Lumia 822来体验，学了点UWP编程。这台手机搭载了OLED屏幕，和Windows手机的黑色背景搭配还是很合适的。

安卓：小米1S青春版，它搭载了半反半透屏幕，我本来以为它有护眼效果，实际体验发现反射率很低，而且屏幕反光还比较严重。

2025-06-26 20:28:50

20岁时，我写了篇博客，没想到这么快，我已经在写30岁的博客了。

今天是我的生日，我妈生下我的日子。这个日子对其它人可能很普通，但对于我们一家人却是不一样的日子。不过，我也没做什么特别的事情，就像一个平凡的工作日那样度过，可能不同的就是我在写这篇文章。

30岁的我，日常是个什么状态呢？早上睡到8点15，出门骑6分钟的自行车到公司所在的写字楼，在食堂吃好早餐，然后上楼打卡上班。日常就是写文档、写博客、写sample级别的程序、分析市场、了解竞争对手、开会，闲了就忙点自己的事情。午饭晚饭也都在食堂解决。下班后先逛圈公园，然后回家刷刷手机。洗澡后洗下衣服，做10个引体向上，差不多11点就躺床上了。周末主要宅家，维护自己的软件，偶尔做饭，但大多数时候还是去外面吃。

刷手机主要还是看视频，看的内容很大程度受到它的推荐机制影响。不过还是看了挺多种类的东西：

• 香港电视剧：从小时候看过的金庸武侠、《寻秦记》、《西游记》，到没看过的《上海滩》、《妙手仁心1》、《先生贵性》、《郎心如铁》、《九五至尊》
• 内地电视剧：央视版《笑傲江湖》、《爱我就别想太多》、《狂飙》、《与凤行》、《莲花楼》、《庆余年2》、《奋斗》、《人生之路》、《我的阿勒泰》
• 外国电视剧：《宫》
• 综艺：《Running Man》、《X-Man》
• 游戏：Dota、《红色警戒》、《三国志曹操传》、《未定事件簿》
• 其它：云养宠物、心理、健康相关的视频

30岁了，家里也会介绍对象，但我比较看重一个人日常的文字表达，不喜欢聊天，加上好友后，看到朋友圈啥都没有，我也就懒得进一步联系。或者是朋友圈有很多内容，但我一看就觉得不合适。再就是日常接触到人。但日常接触人有很大的风险，容易自我感动，我这里再就情感和工作问题总结下。

其实情感和工作问题是相似的，你是什么样的人，找什么样的工作。但很多时候，我们对自己和他人认识不清，导致我们遇到不少坎坷。但人生也会因此变得丰富。

1. 关于预想。我们不可能自己去经历所有事情，所以需要预想，来少走弯路。但世界还是复杂的，我们预想的东西往往和实际不符，有时还是要直接做，少假想。
2. 不要怕难。在旅行的飞机上，一位91年已经做妈妈的女同事问我考不考虑结婚，我说我觉得我自己都照顾不好，然后生下孩子，孩子也要在人世间受苦。这个问题自古就有，晚婚的老舍在《婆婆话》里也提到，人生来为牛马。但这位同事很乐观，她说你都没做怎么知道难呢，你想的不一定你孩子也这么想。这么一说，我也乐观了很多。但刚刚聊完，我摸到包里的削皮器，把手划伤了。看到鲜血涌出，我不由得心慌，好在空姐和同事帮忙止住了血。我瞬间对自己更没有信心了。不过之后我回想，船到桥头自然直，有困难咱就解决困难不就行了。但如果这个困难真的很大，还是要学会避开。
3. 学会休息。中国翻译《莎士比亚全集》第一人是梁实秋，为什么呢，因为别的翻译家在翻译完前就挂了，只有他活了80几岁，有能力翻译完。所以我们工作生活，既要注重当下，也要有长远的考虑，身体是革命的本钱，要学会劳逸结合。
4. 学会找乐子。其实工作、学习，换个角度看，都是玩，而且是对社会能有点贡献的玩。只是玩得久了，没有玩的心态了。我们重新拾起这种玩的心态，工作学习也会欢快很多。

30岁，我会发现很多从前的想法并不是正确的，就像《大宋提刑官》里的宋慈，每破一个案子，就进一步认清这个世界。我还是希望能像《神探狄仁杰》那样，有自己崇高的目标，不断壮大自己，战胜敌人。

2025-06-21 15:38:50

上周随公司前往山西旅游，我这里对这次旅行做个记录。

如果小时候看过《神探狄仁杰》，可能会记得狄仁杰这样的一段自我介绍：在下姓狄，名仁杰，并州人士，官同凤阁鸾台平章事，加黜陟使，兼幽州大都督。

并州就是目前山西省的省会太原的古称，因为其位于吕梁山和太行山之间的盆地得名。而山西整体的地势就是“两山夹一川”。山西历史悠久，春秋时的晋国，南北朝时的北魏主要就位于山西。国家大一统时，也是经济、文化发达的地区，在明清时晋商十分活跃，在革命时期也是主要的革命根据地。

我们此去山西，主要便是感受山西的人文文化，走马观花了晋祠、五台山、恒山悬空寺、大同华严寺、云冈石窟、雁门关、平遥古城和乔家大院等景区（见下方地图）。下面我将按时间顺序记叙这次旅行。

第一天

乘MU5242次航班从杭州前往太原武宿机场，可能因为梅雨，晚点1个小时，晚上9点多才到达。入住酒店后就直接休息了。

第二天

早上7点30出发，前往太原西边的晋祠。晋祠有一汪泉水、很多的古建筑、几千年的参天大树，不过我对建筑、雕塑什么的实在是个外行，就像逛公园一样逛了一圈。

接着出发前往东北方向的五台山。五台山不是一座山，是由一系列大山和群峰组成，上面有大大小小很多的寺院。《华严经》提到五台山是文殊菩萨的道场，而后它的名气也越来越大。

我们到五台山后，先前往普化寺游览，然后登菩萨顶，逛了一系列寺庙，下来后又去了五爷庙。

我最喜欢的还是普化寺，还在那里上了香，可能是那里比较清静。

晚上，我们在五台山北面繁峙县砂河镇住宿。这个小镇楼房都不高，也比较清静。

第三天

上午8点出发，前往北岳恒山，参观恒山十八景之首的悬空寺。我们先到了一个游客中心，然后乘摆渡车前往景区。

进去后，我们在观光区远观悬空寺。悬空寺依托崖壁而建，看上去像悬空在悬崖之间。

悬空寺景区有广播一直在放同一首音乐，还挺好听的。我回去后查了下，是山西当地团队创作的歌曲《千山千缘》，表达了苦寻梦中奇缘而不得的惆怅。

离开悬空寺，我们前往大同市区，到了大同古城里的华严寺。这座寺庙的建筑主要是辽金时期的，里面有各种壁画和塑像。

之后，我们前往西北方向的云冈石窟。云冈石窟主要有20个石窟，全部由北魏建造。最西边的20窟，是最具代表的石窟，外面没有石壁，是露天的。而东边的许多窟则比较径深。

晚上在大同的龙聚祥吃了烧麦，没有嘉兴的肉烧麦好吃。

前往大同的路上的景观和在内蒙古赤峰看到的会比较像，是一座座山，山上是草原，零星有几棵树。

第四天

第四天山西下雨了，高速封路，我们只有走各种小路向南前往雁门关。沿途穿过朔州的村庄，还远远地看到了应县木塔。一直到中午才抵达雁门关。

明清前，我国统一多民族的疆域还没有形成，雁门关北面还属于少数名族的范围。这里东西山岩峭拔，中有路，所以便在这里建立关隘，来抵御外族入侵。叫雁门是因为大雁也过不了两边的山，只有从较低的雁门关的位置飞过。

来到实地后，的确有种荒凉的边境的感觉。不过现在的雁门关都是新建的，当做景区来运营，就少了点意思。

离开雁门关，我们就往南前往平遥古城。因为距离远，一直到傍晚才到。

平遥古城是一座保存完好的古代县城，有城墙、店铺、街道、寺庙、民居等各种组成成分。历史书中提到的日升昌票号也位于此。

主要的街道商业化严重，偏僻的小路又乌漆墨黑一片，我也没有多逛。看到有卖叫做推光漆器的店，是用漆涂在各种器物的表面上所制成的东西，主要都是首饰盒，算是当地特有的。

第五天

行程最后一天，我们前往祁县的乔家大院。本科的时候看过《乔家大院》电视剧，印象最深的有两个场景，一个是张译从城墙上下来，一个是摄像头放在院子门口，乔致庸缓缓走入宅子。

乔家大院有很多院组成，中间有一条甬道连接。我实地到访后，后一个场景应该是在中堂，进入院门，正面正房，两边偏房，中间一口水缸，有挂着大红灯笼。

这些房子有书房、客房、餐房、厨房等等功能分类，屋子里有各种家具，让我们了解了当时人们的生活场景。

八国联军侵华时，慈禧西逃经过乔家大院，乔致庸借了30万两白银给慈禧。后来慈禧送了九龙灯，至今能在乔家大院看到。晋商依附官府才得以繁荣，在清廷衰败后，晋商便也衰败了。

离开乔家大院，我们便回太原，等待返杭的飞机了。

其它

我再稍微讲下旅行中的人。

先说下和当地人的互动。时间短暂，交流最多的还是我们的导游阳阳和司机师傅。阳阳是94年的女生，山西文水人，也做了10年导游了，有北方女生的爽气。她去年结婚，和在北京工作的老公处于异地状态。司机师傅常年在外，老婆也是导游，三个月没见了，正好在云冈石窟停车的时候两个人碰见，打声招呼后就又继续行程了。原来大家都在努力生活。

都说旅行能反映人的品性，就说我自己吧，不太会整理东西，买了个削皮器放包里，结果翻包的时候划伤，然后血液涌出时还不太会止血，好在有空姐和我们大名同学照顾，创可贴、碘伏棉签样样都有。

感谢公司组织旅行，让我看到了我们大名同学不一样的一面，也向大名同学学习了很多。

2025-05-12 20:46:50

经常能看到楼里的人在上班时做别的事情，比如看股票、刷微博、聊微信、备考、逛不良网站，这种行为现在也叫摸鱼。

而我的话，则比较多的离开座位，去外面散步休息。

当代的工作，通常已经不再是血汗工厂的工作。我们其实不需要8小时一直埋头做事情。休息是正当的行为，而且能帮助提升工作效率，并延长工作寿命。我们需要有空闲的时间，来总结我们的工作，对未来有一定的规划。

最近有句话叫世界是个草台班子，规则本来就是人定的，存在缺陷的，我们不必完全照着规则来，需要灵活变通。

2025-05-12 20:30:50

浏览器URL参数中有一个用来跳转到并高亮第一个匹配到的文本的参数#:~:text。

例：https://blog.xulihang.me/the-essence-of-computer-programming/#:~:text=%E6%9D%A1%E7%A0%81

我们打开这样的一个链接后，浏览器会给出对应的效果，但我们直接刷新页面，则不会有这种效果。

在程序世界里，充满了这样的条件判断。我们日常写程序，其实不会涉及很复杂的算法，更多的是处理这样的细节。编程的确是个细致活。