使用Html5的编写技术文档

kipway@kipway.com

2017.5.26

目录(样例)

编写大的文档一般常用的使用office软件,这里介绍的是使用html5来编写图文并茂的一般技术文档,需要使用到一点点html知识。只需要几个html标签即可:p,a,h1,h2,h3,ul,li,div,svg这几个就足够了。

1.工具准备

一个文本编辑器,一个svg绘图软件,一个可选的代码高亮js包。

注:本文使用notepad++编写,高亮语法采用prism.js,svg例子使用pvedit,Google chrome作为预览浏览器。

2.CSS样式

定义几个div和几个字体就行了,直接放到html文档的head段内,便于文档的分发。你可以使用本文的CSS样式,使用浏览器显示本文源码,复制保存下来即可。

3.插入SVG矢量图

SVG是html5包含的内容之一,现在的主流浏览器都直接内置了对SVG矢量图的支持。运行pvedit组态软件,随便建立一个工程,在左边工程树的画面节点鼠标右键菜单出现新建画面, 画面大小以px为单位,设置为你需要绘制的图形的大小,然后就像使用一般的绘图软件一样绘制图形,保存后会在view子目录里生成一个同名的html文件,复制出里面的SVG标签粘贴到文档中即可。如下例子:

TCP协议 SUDP(超级用户数据报协议),支持压缩、加密,由eclib实现 MDPP(混合数据集代理协议),参见《异构数据集代理服务.odt》 KDP(K线数据服务器协议),参见《K线数据传输协议.odt》 跨平台客户端API接口,windows/linux C接口,python接口 传输层 会话层 表示层 应用层 kdserver网络模型图

SVG代码如下:

<svg id="svg_netmode" width="760px" height="400px" viewBox="0, 0, 760, 400" style="background-color:#FFFFFF" xmlns="http://www.w3.org/2000/svg">
	<rect stroke="#000000" stroke-width="1" fill="#D4D0C8" x="120.0" y="272.0" width="456.0" height="48.0"></rect>
	<text font-size="14px" fill="#000000" x="312.0" y="288.0" dy="1em" font-weight="400">TCP协议</text>
	<rect stroke="#000000" stroke-width="1" fill="#D4D0C8" x="120.0" y="224.0" width="456.0" height="48.0"></rect>
	<text font-size="14px" fill="#000000" x="160.0" y="240.0" dy="1em" font-weight="400">SUDP(超级用户数据报协议),支持压缩、加密,由eclib实现</text>
	<rect stroke="#000000" stroke-width="1" fill="#FFFFFF" x="120.0" y="176.0" width="456.0" height="48.0"></rect>
	<text font-size="14px" fill="#000000" x="160.0" y="192.0" dy="1em" font-weight="400">MDPP(混合数据集代理协议),参见《异构数据集代理服务.odt》</text>
	<rect stroke="#000000" stroke-width="1" fill="#D2B48C" x="120.0" y="128.0" width="456.0" height="48.0"></rect>
	<text font-size="14px" fill="#000000" x="160.0" y="144.0" dy="1em" font-weight="400">KDP(K线数据服务器协议),参见《K线数据传输协议.odt》</text>
	<rect stroke="#000000" stroke-width="1" fill="#FFFFE0" x="120.0" y="80.0" width="456.0" height="48.0"></rect>
	<text font-size="14px" fill="#000000" x="160.0" y="96.0" dy="1em" font-weight="400">跨平台客户端API接口,windows/linux C接口,python接口</text>
	<line x1="608.0" y1="56.0" x2="576.0" y2="80.0" stroke="#000000" stroke-width="1"></line>
	<line x1="608.0" y1="56.0" x2="608.0" y2="296.0" stroke="#000000" stroke-width="1"></line>
	<polygon stroke="#000000" stroke-width="1" fill="#D4D0C8" points="576.0 320.0,576.0 224.0,608.0 200.0,608.0 296.0"></polygon>
	<polygon stroke="#000000" stroke-width="1" fill="#FFFFFF" points="576.0 224.0,576.0 176.0,608.0 152.0,608.0 200.0"></polygon>
	<polygon stroke="#000000" stroke-width="1" fill="#D2B48C" points="576.0 176.0,576.0 128.0,608.0 104.0,608.0 152.0"></polygon>
	<polygon stroke="#000000" stroke-width="1" fill="#FFFFE0" points="576.0 128.0,576.0 80.0,608.0 56.0,608.0 104.0"></polygon>
	<polygon stroke="#000000" stroke-width="1" fill="#FFFFE0" points="120.0 80.0,144.7 56.0,608.0 56.0,576.0 80.0"></polygon>
	<text font-size="14px" fill="#000000" x="616.0" y="240.0" dy="1em" font-weight="400">传输层</text>
	<text font-size="14px" fill="#000000" x="616.0" y="168.0" dy="1em" font-weight="400">会话层</text>
	<text font-size="14px" fill="#000000" x="616.0" y="120.0" dy="1em" font-weight="400">表示层</text>
	<text font-size="14px" fill="#000000" x="616.0" y="72.0" dy="1em" font-weight="400">应用层</text>
	<text font-size="14px" fill="#000000" x="280.0" y="344.0" dy="1em" font-weight="400">kdserver网络模型图</text>
</svg>

4.代码高亮着色

使用最轻量的prism即可,但是有一个唯一的不足,代码中的 '<' 需要使用转码。在head段中最后加入css连接,在body第一行加入prism.js的引用.如下:

...
	<link href="js/prism.css" rel="stylesheet" />
</head>
<body>
    <script src="js/prism.js">
...			
然后将代码放在
<pre><code class="language-cpp"> you code block </code></pre>

之间即可。这样html文件就不独立了,需要一个js目录存放prism的CSS文件和js文件,如果没有这些文件,代码块也会正常显示,只是没有高亮颜色而已。

5.编写目录

如果文章比较长,编写已个目录是不错的选择,将目录放在前面。使用a标签的name属性来标记章节位置,如下:

<a name="sub_title3"></a>

在目录取使用a标签的href属性来连接到章节位置

<a href="#sub_title3">3.插入svg矢量图</a>

具体目录例子如下:

<ul>
	<li><a href="#sub_title1">1.工具准备</a></li>
	<li><a href="#sub_title2">2.CSS样式</a></li>
	<li><a href="#sub_title3">3.插入svg矢量图</a></li>
	<li><a href="#sub_title4">4.代码高亮着色</a></li>
	<li><a href="#sub_title4">5.编写目录</a></li>
</ul>