文档开发指南¶
- 作者
Howard Butler
- 联系方式
可在gmail.com上可查询相关信息
- 作者
Jeff McKenna
- 联系方式
jmckenna在gatewaygeomatics.com
- 最后更新
2019-07-17
目录
背景¶
MapServer文档流程的当前结构是让开发人员以restructuredText格式维护文档，并通过 GitHub 拉取请求；首先需要创建 free personal account 在吉图布。这个 Sphinx 文档生成器用于将重构的文本文件转换为HTML，然后每2小时自动更新一次实时网站。
注解
实时网站实际上是在Travis CI上自动构建的，每次提交Github都会触发它。请参阅https://travis-ci.org/mapserver/docs上的构建历史记录
GitHub 笔记¶
文档文件存储在github上的/docs子项目中，网址为：https://github.com/mapserver/docs
总是在最新的分支（如branch-7-4）上提交拉取请求，而不是在master上
见吉图布 help guidelines 本地安装Git
有用的git命令：
本地克隆分支：
git clone -b branch-7-4 git@github.com:mapserver/docs.git mapserver-docs-git-branch-7-4
更新本地文件：
git pull
将文件添加到存储库（在此之后需要提交）：
git add <file>
将文件提交到存储库：
git commit -m "my message" <files>
简单编辑的工作流¶
对于不一定需要编译文档的简单编辑（打字等），可以采用不需要任何本地工具的简单工作流来创建拉请求：
如果尚未创建GitHub帐户，请创建该帐户
转到https://github.com/mapserver/docs
点击“fork”按钮
您现在在https://github.com/您的帐户/docs上
单击“branch:…”列表（绿色“new pull request”按钮左侧）
在文本框中，输入描述创建新分支所做更改的名称（例如“打字错误”）。
您现在在https://github.com/您的_帐户/tree/分支_name
浏览树并单击要编辑的文件。若要查找要编辑的文件，可以在页面顶部的搜索条目框中键入文本（例如“用于简单编辑的工作流”以查找此页面）。
单击“编辑此文件”按钮（带笔图标）
完成后，填写页面底部的“提交更改”部分（标题足以容纳大多数更改）
单击页面底部的“提交更改”按钮
如果需要，请使用其他文件重复此过程。
完成后，返回https://github.com/your_account/tree/branch_name并单击“New Pull Request”按钮
如果需要，您可以查看更改并编辑请求摘要消息
点击“创建拉请求”按钮确认
你完了！（具有“推送”权限的人必须审阅并合并您的更改）
分支清理：
合并后，可以在转到分支页面时删除分支：https://github.com/your/docs/branches
单击要删除的分支右侧的垃圾箱图标。
一般写作指南¶
map server而不是map server、map server、map server、map server或map server。
map script而不是map script、map script或map script。
Postgis而不是Postgis。
如何而不是如何或如何。
应手动保护电子邮件地址的垃圾邮件：
hobu.inc at gmail.com instead of hobu.inc@gmail.com
重构文本格式¶
与源代码一样，所有文本都应该在80列标记处或其周围进行硬断。
不
.. sectnum::在目录指令中所有外部链接都应位于文档的底部，标题为：
.. #### rST Link Section ####
始终在文档顶部包含：last updated:行，例如：
:Last Updated: 2018-07-31
安装并使用sphinx生成RST HTML¶
注解
截至2018年7月31日，mapserver网站要求sphinx 1.7.6和sphinx_rtd_theme 0.2.0-您可以浏览sphinx软件包的版本 here ，然后安装准确的版本，如：
easy_install Sphinx==1.7.6
easy_install sphinx_rtd_theme==0.2.0
On Windows:
安装 Python 3.X
下载 setuptools
确保“c:/python3x/scripts”目录是您的路径
在命令行执行以下操作：
easy_install Sphinx
…您应该看到消息：“已完成处理斯芬克斯的依赖项”
注解
确保安装的是Sphinx 1.7.6或更高版本。见上面的注释。
在/docs目录中，执行：
make html
或
make latex
HTML输出将写入u build/html子目录。
如果要构建pdfs，请从http://miktex.org/download安装miktex
On Linux:
确保安装了python dev和setuptools包。关于Ubuntu：
sudo apt-get install python-dev sudo apt-get install python-setuptools
使用“轻松安装”安装Sphinx：
sudo easy_install Sphinx
注解
确保安装的是Sphinx 1.7.6或更高版本。见上面的注释。
要处理这些文档，请从mapserver/docs目录运行：
make html make html BUILD_LANGUAGES=
或
make latex
HTML输出将写入build/html子目录。
注解
如果有多个翻译，上面的命令将自动生成所有翻译，除非您在make参数中添加“build_languages=”
On OS X:
使用“轻松安装”安装Sphinx：
sudo easy_install Sphinx
注解
确保安装的是Sphinx 1.7.6或更高版本。见上面的注释。
#如果要构建PDF，请从http://www.tug.org/MacTex/安装MacTex
要处理这些文档，请从mapserver/docs目录运行：
make compile_messages make html
或
make compile_messages make latex
HTML输出将写入build/html子目录。
注解
如果有多个翻译，上述命令将自动生成所有翻译。
（英文）打字稿¶
（在Linux上测试。也可能在Macosx上运行。Windows用户可能需要安装cygwin、python 3、git、curl、sed、grep、awk）
scripts/fix_typos.sh中的脚本是一个交互式脚本，用于检测和更正英语文档（en/directory）中常见的拼写问题。
它需要运行python3（python3可执行文件）。第一次运行时，它还使用“git”和“curl”二进制文件下载codespell引擎、它自己的字典以及debian lintian和qgis字典。它们被下载到“修复”输入法/子目录中。可以随时安全地删除此目录（以便获取字典或codespell引擎的新版本）。
启动脚本时使用：
./scripts/fix_typos.sh
每当检测到打字错误时，它会询问是否必须使用建议的替换（Y/N）来修复，或者如果有几个选项，则询问是否要选择选项（0、1等）。
它包含一个被标记为非打字错误的单词白名单（在单词_white_list变量中）。也可以编辑excluded_files变量以添加完全忽略的文件。可以编辑scripts/typos_whitelist.txt文件以添加应忽略的完整行（对起始和尾随空格/表格敏感，并且仅对以lf结尾的文件有效，因此可能需要事先从crlf转换为lf）。只有当某个词在给定上下文中不是拼写错误，但在另一个上下文中可能是拼写错误时，才应使用scripts/typos_white list.txt而不是words_white_list。
如何处理翻译¶
现在，MapServer有两个共存的系统来管理翻译过程。两者都依赖斯芬克斯软件。
第一个问题是解决斯芬克斯软件最初几天缺乏国际化支持的问题。第二次使用新的系统 internationalization 目前仅用于法语翻译。
翻译的“老”方法¶
虽然我们认为现在的新系统更好，但我们不想强制每个语言社区改变他们的习惯。
所有翻译都组织在mapserver/docs目录的子目录中。
目录的命名使用 ISO3166-1 alpha-2 country codes ，也将引用相应的标志图标
翻译基于英文文档
必须保留目录结构和文件名，它们用于在不同的翻译之间生成链接。
注解
要开始新的翻译，请将目录图像复制到docs/en到docs/<lang>，其中<lang>是国家代码之一。您还应该将docs/en/documentation.txt和docs/en/index.txt文件复制到您的<lang>目录中（构建过程需要这些文件…您可以根据自己的语言自由编辑它们）。
只有翻译的文件保存在<lang>目录和存储库中。
构建脚本（makefile和make.bat）有一个选项（init）来预处理<lang>目录。这意味着每个未翻译的英文文件都被复制到目标<lang>目录中。您不必这样做就可以在本地构建HTML文件。如果你这样做，你必须清理你的目录之后。
为了使翻译与英文文档保持同步，翻译人员可以监视对存储库的提交。
注解
监视更改的一种方法是通过Github订阅RSS提要：在文档存储库中，单击“提交”选项卡并查找这些提交更改的订阅链接，例如：请参见https://Github.com/mapserver/docs/Commits/branch-7-4上的“提交历史记录”
您必须通过在makefile或make.bat中设置翻译来定义哪些语言可用：
TRANSLATIONS = en de
然后生成脚本将处理子目录 en 和 de. 如果无法访问，将返回错误消息。
翻译标准国际化系统（I18N）¶
新语言的初始翻译过程¶
其步骤如下：
使用sphinx从原始英文文档生成pot文件（除非已经在这里）
make gettext
将新版本的*.pot文件从u build/gettex/en复制到translated/pot
make gettext_copy
copy *.pot file=>*.po文件（a *.po文件与*.pot文件相同，只更改扩展名，如果您翻译三种语言，您将得到三个*.po文件，每个文件都将成为一个语言目录）
make generate_po_from_tmpl -e TRANSLATIONI18N=fr
翻译*.po文件
您可以使用Poedit这样的软件来完成这项工作，但我们可以切换到Transifex，这是一个托管的翻译服务，以使您的贡献更加容易，遵循翻译的前进方向，并对翻译进行审查。
将*.po编译为*.mo（sphinx需要*.mo文件才能从原始版本替换为翻译后的语言）
make compile_messages -e TRANSLATIONI18N=fr
为语言生成文档
在构建文档之前，您只需要在文件'make file'或make.bat中根据您的操作系统设置以下参数：
TRANSLATIONI18N=fr
您还需要更改scripts/build_docs.sh脚本以将您的语言添加到文件顶部：
LANGUAGES= fr
请为这两个参数保留字母顺序以保持它们的可读性。
docs根目录中i18n文件的结构
你需要做的所有运输过程的结构如下（摘录给你所需的主要结构）
translated/ ├── fr │ ├── about.po │ ├── announcements_all.po │ ├── cgi.po │ ├── community.po │ ├── copyright.po │ ├── development.po │ ├── documentation.po │ └── LC_MESSAGES │ ├── about.mo │ ├── announcements_all.mo │ ├── cgi.mo │ ├── community.mo │ ├── copyright.mo │ ├── development.mo │ └── documentation.mo └── pot ├── about.pot ├── announcements_all.pot ├── cgi.pot ├── community.pot ├── copyright.pot ├── development.pot └── documentation.pot
此外，您只需要提交*.pot和*.po文件。注意，您必须有一个lc_messages目录才能接收*.mo文件。要将这个目录保存在git中，建议创建一个空文件并将其清空。
注解
添加新语言时，请注意使用的ISO代码。FamFamFam标志图标使用的是ISO国家代码，Transifex使用的是可能不同的ISO语言代码。见 ISO country code page 更多信息。
现有翻译的常规工作流程¶
我们解释的前一个过程仅用于语言创建。之后，工作流包括：
通过翻译您的语言的采购订单文件 transifex ，
从Transfex中提取采购订单文件并提交它们
生成.mo文件
再建
以下是命令行：
从Transifex获取采购订单文件（可以使用-l标志筛选语言）：：
tx pull -a
从采购订单文件生成生产任务文件：：
make compile_messages -e TRANSLATIONI18N=fr
生成HTML页：：
make clean html
请参阅下面如何设置Transfex帐户以使用Transfex客户端推送、拉入翻译的文件并构建HTML文件。
有时，当主英文文档发生更改时，您需要再次生成pot文件。然后，您必须使用下面的命令行实用程序（来自gettex）将翻译的文件与新的pot文件合并：
make gettext
make gettext_copy
-U表示用po t文件更新po文件，-N表示不使用模糊但精确匹配。然后将po文件推送到transfex（可以使用-l标志来过滤语言）：：
tx push -s
提交更新时，添加[build_pdf]或[build_translations]以生成PDF和/或转换到Web服务器。
Knonw问题：
将采购订单文件下载到本地目录时，如果该文件存在，则不会更新。此时，我们应该在下载之前删除所有采购订单文件。
当构建HTML文档缓存系统时，不允许更新具有最新翻译的页面。我们应该把干净的目标和make一起使用。
此命令行引发错误：：
tx push -s -t
如何使用Transifex客户端管理翻译过程¶
注解
文件中对Transifex进行了更深入的描述： 如何帮助翻译文档
安装Transifex客户端：：
sudo apt-get install transifex-client
编辑~/.transifexrc并在其中添加适当的信息：
vim ~/.transifexrc
内容如下：
[https://www.transifex.com/] username = yjacolin token = password = passw0rd! hostname = https://www.transifex.com/
参考标签¶
标签 |
书名 |
|---|---|
关于 |
|
Agg公司 |
|
反别名 |
|
软件工程师 |
|
空间数据引擎 |
|
自动测试 |
|
背景 |
|
batch_utilities |
|
漏洞 |
|
CGI |
|
cgi_controls |
|
cgi_introduction |
|
类 |
|
社区 |
|
开发 |
|
二甘醇 |
|
文档 |
|
documentation_development |
|
dotnet_compile |
|
下载 |
|
dynamic_charting |
|
编辑 |
|
错误 |
|
1-1例 |
|
实例1-1-MAP |
|
example1-2 |
|
实例1-2-MAP |
|
1-3 |
|
1-3图 |
|
1-4 |
|
1-4图 |
|
示例1-5 |
|
示例1-5-MAP |
|
1-6 |
|
1-6图 |
|
1-7 |
|
example1-7-map |
|
1-8 |
|
1-8图 |
|
表达 |
|
常见问题 |
|
FASTCGI |
|
特征 |
|
filter_encoding |
|
闪光 |
|
字体集 |
|
format_types |
|
基因索引 |
|
吉特 |
|
光泽 |
|
GML |
|
平均分 |
|
网格 |
|
html_legend |
|
iis |
|
图像映射 |
|
包括 |
|
内联的 |
|
输入 |
|
input_postgis |
|
安装 |
|
介绍 |
|
IRC |
|
参加 |
|
KML |
|
标签 |
|
图层 |
|
传奇 |
|
legend_utility |
|
许可 |
|
Linux |
|
列表 |
|
管理 |
|
地图 |
|
map_context |
|
mapcache_formats |
|
mapcache_jpeg_format |
|
mapcache_png_format |
|
mapcache_mixed_format |
|
mapcache_caches |
|
mapcache_grids |
|
mapcache_cache_sqlite |
|
mapcache_cache_disk |
|
mapcache_cache_memcache |
|
mapcache_cache_tiff |
|
mapcache_services |
|
mapcache_ve |
|
mapcache_tms |
|
mapcache_kml |
|
mapcache_wmts |
|
mapcache_wms |
|
mapcache_gmaps |
|
mapcache_proxying |
|
mapcache_dimensions |
|
mapcache_featureinfo |
|
mapcache_tile_assembling |
|
mapcache_sources |
|
mapcache_source_wms |
|
mapcache_source_mapfile |
|
mapcache_http |
|
mapcontext_cgi |
|
Mapfile |
|
mapfile_tuning |
|
地理信息系统 |
|
MapScript |
|
mapscript_introduction |
|
mapscript_ows |
|
mapscript_tests |
|
MAPSERV公司 |
|
模式索引 |
|
MSN |
|
MySQL |
|
NTF |
|
OCI |
|
oci_install |
|
OGC |
|
ogc_support |
|
奥格尔 |
|
online_resource_wms |
|
优化 |
|
OSX公司 |
|
输出 |
|
输出格式 |
|
PGEO |
|
PHP |
|
php_example |
|
php_install |
|
php_install_example_steps |
|
投影 |
|
PSC |
|
Python |
|
查询 |
|
查询程序 |
|
栅格 |
|
raster_optimization |
|
参考 |
|
射频芯片1 |
|
射频C10 |
|
射频C11 |
|
射频芯片12 |
|
射频芯片13 |
MS RFC 13: Support of Sensor Observation Service in MapServer |
射频芯片14 |
|
RCF15 |
MS RFC 15: Support for thread neutral operation of MapServer/MapScript |
射频芯片16 |
|
重组腺病毒17 |
MS RFC 17: Dynamic Allocation of layers, styles, classes and symbols |
射频C18 |
|
重组腺病毒19 |
|
射频电容器2 |
|
射频芯片21 |
|
射频芯片22A |
MS RFC 22a: Feature cache for long running processes and query processing |
射频芯片23 |
|
射频芯片24 |
|
RFC241 |
|
RCF25 |
MS RFC 25: Align MapServer pixel and extent models with OGC models |
RFC26 |
|
重组蛋白C27 |
|
RCF28 |
|
射频C29 |
|
射频电容器3 |
|
射频芯片30 |
|
射频芯片31 |
|
RFC32型 |
MS RFC 32: Support for Anti-Grain Geometry (AGG) Rendering Engine |
射频芯片33 |
|
射频芯片39 |
|
射频电容器4 |
|
射频电容器40 |
|
RFC41型 |
|
射频芯片42 |
|
射频芯片43 |
MS RFC 43: Direct tile generation for Google Maps and Virtual Earth API |
RCF44 |
MS RFC 44: Restore URL modification of mapfiles to pre-5.0 levels |
rfc45 |
MS RFC 45: Symbology, Labeling, and Cartography Improvements |
RCF46 |
|
射频芯片47 |
MS RFC 47: Move IGNORE_MISSING_DATA to run-time configuration |
RCF48 |
|
RFC49 |
MS RFC 49: Symbology, Labeling, and Cartography Improvements |
RCF5 |
|
射频消减 |
|
射频芯片51 |
|
射频芯片53 |
|
RFC54 |
|
射频卡55 |
|
射频芯片56 |
MS RFC 56: Tighten control of access to mapfiles and templates |
rfc6 |
|
射频C7 |
|
rfc7.1 |
|
射频C8 |
|
RFC9型 |
|
RFCS |
|
运行子 |
|
S57 |
|
标尺 |
|
scalebar_utility |
|
SDTS |
|
搜索 |
|
第一节 |
|
第二节 |
|
形状文件 |
|
Sp2IMG |
|
希普特里 |
|
希普雷特维斯 |
|
SLD |
|
SORTHHP |
|
sos_server |
|
来源 |
|
赞助商 |
|
风格 |
|
样式项自动标签样式 |
|
svg |
|
svn |
|
斯威格 |
|
Sim2img |
|
sym_construction |
|
sym_examples |
|
符号 |
|
模板 |
|
测试 |
|
老虎 |
|
Ti4Ms |
|
tile_mode |
|
倾斜指数 |
|
教程 |
|
UNIX |
|
公用事业 |
|
variable_sub |
|
矢量 |
|
vector_optimization |
|
vim |
|
virtual_vector |
|
wcs_format |
|
wcs_server |
|
网状物 |
|
WFS |
|
wfs_client |
|
wfs_server |
|
Win32 |
|
windows |
|
wms_capabilities |
|
wms_client |
|
wms_server |
|
wms_time |
|
包装器 |