文档开发指南

作者

霍华德巴特勒

联系

位于gmail.com的Hobu.inc

作者

杰夫麦克纳

联系

jmckenna在gatewaygeomatics.com

最后更新

2021-03-19

背景

MapServer文档流程的当前结构是让开发人员以reStruredText格式维护他们的文档,并通过 GitHub 请求;您首先需要创建一个 free personal account 在GitHub。这个 Sphinx 文档生成器被用来将reStrutiredText文件转换为html,然后根据每个合并的拉取请求自动更新实时网站。

备注

LIVE网站实际上是自动建立在Travis CI上的,由每一次对GitHub的承诺触发。请访问https://travis-ci.com/github/MapServer/MapServer-documentation查看构建历史

GitHub 笔记

  • 文档文件存储在GitHub上的/MapServer-Documentation子项目中,地址为:https://github.com/MapServer/MapServer-documentation

  • 始终将拉式请求提交到 main ,如果适用,您的更改将被回传到特定分支机构

  • 所有文件应仅具有 LF 作为换行符。在通过Git比较文件时,换行符(或换行符)的差异可能会导致问题(Windows在其文件中的换行符中同时使用回车符和换行符,而MacOS和Linux系统只使用换行符)。一种选择是让Git在提交时将CRLF转换为LF,方法是在命令行中设置:

    git config --global core.autocrlf input
    
  • 请参阅GitHub的 help guidelines 在本地安装Git

  • 有用的git命令:

    • 在本地克隆“Main”:

      git clone https://github.com/MapServer/MapServer-documentation.git MapServer-documentation-git-main
      
    • 更新本地文件:

      git pull
      
    • 将文件添加到存储库(在此之后需要提交):

      git add <file>
      
    • 将文件提交到存储库:

      git commit -m "my message" <files>
      

简单编辑的工作流

对于不一定需要编译文档的简单编辑(打字等),可以采用不需要任何本地工具的简单工作流来创建拉请求:

  • 如果尚未创建GitHub帐户,请创建该帐户

  • 请访问https://github.com/MapServer/MapServer-documentation

  • 点击“fork”按钮

  • 您现在在https://github.com/{your_account}/MapServer-documentation上

  • 单击“branch:…”列表(绿色“new pull request”按钮左侧)

  • 在文本框中,输入描述创建新分支所做更改的名称(例如“打字错误”)。

  • 您现在在https://github.com/您的_帐户/tree/分支_name

  • 浏览树并单击要编辑的文件。若要查找要编辑的文件,可以在页面顶部的搜索条目框中键入文本(例如“用于简单编辑的工作流”以查找此页面)。

  • 单击“编辑此文件”按钮(带笔图标)

  • 完成后,填写页面底部的“提交更改”部分(标题足以容纳大多数更改)

  • 单击页面底部的“提交更改”按钮

  • 如果需要,请使用其他文件重复此过程。

  • 完成后,返回https://github.com/your_account/tree/branch_name并单击“New Pull Request”按钮。

  • 如果需要,您可以查看更改并编辑请求摘要消息

  • 点击“创建拉请求”按钮确认

  • 你完了!(具有“推送”权限的人必须审阅并合并您的更改)

分支清理:

  • 合并后,您可以在转到分支页面时删除分支:https://github.com/{your_account}/MapServer-documentation/branches

  • 单击要删除的分支右侧的垃圾箱图标。

一般写作指南

  • map server而不是map server、map server、map server、map server或map server。

  • map script而不是map script、map script或map script。

  • Postgis而不是Postgis。

  • GitHub而不是Github或GitHub

  • 如何而不是如何或如何。

  • 应手动保护电子邮件地址的垃圾邮件:

    myname at gmail.com instead of myname@gmail.com
    

重构文本参考指南

重构文本格式

  • 与源代码一样,所有文本都应该在80列标记处或其周围进行硬断。

  • 不是的 .. sectnum:: 在内容指令中

  • 始终在文档顶部包含:last updated:行,例如:

    :Last Updated: 2021-02-16
    
  • 指令 versionaddeddeprecatedversionremoved 应放在参数名称的正下方,例如:

    PARAMETER
      .. deprecated:: 8.0
         Use a :ref:`xxx` block instead.
    

安装并使用sphinx生成RST HTML

备注

截至2021-03-19,MapServer站点至少需要Sphinx 3.5.0、雪花石膏0.7.12和 sphinx-removed-in extension - You can check the exact versions that the live website uses in the file requirements.txt ,(或者您也可以浏览Sphinx包的最新版本 here ),然后在本地安装,如:

pip install -r requirements.txt

On Windows:

  1. 安装 Python 3.X

  2. 确保“c:/python3x/scripts”目录是您的路径

  3. 安装 pip

  1. 在命令行中执行以下命令:

pip help
  1. 如果未找到该命令,则下载该文件 get-pip.py 本地的。

  2. 在命令行中执行以下命令:

python get-pip.py
  1. 在/MapServer-Documentation目录中,执行:

    python -m pip install -r requirements.txt
    

    …您应该看到消息:“已完成处理Sphinx的依赖项”

  2. 在/MapServer-Documentation目录中,执行:

    make html
    

    make latex
    

    HTML输出将写入u build/html子目录。

  3. 如果您想构建pdf,请从https://miktex.org/download安装MiKTeX

On Linux:

  1. 大多数口味都安装了Python(请查看 python --version ),有关具体步骤,请咨询您的发行商。示例命令可能是:

    sudo apt-get install python3.9
    
  2. 安装管道

    curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
    python get-pip.py
    
  3. 安装Sphinx。在/MapServer-Documentation目录中,执行:

    python -m pip install -r requirements.txt
    
  4. 要处理文档,请从/MapServer-Documentation目录运行:

    make html
    make html BUILD_LANGUAGES=
    

    make latex
    

    HTML输出将写入build/html子目录。

备注

如果有多个翻译,上面的命令将自动生成所有翻译,除非您在make参数中添加“build_languages=”。

On OS X:

  1. 使用pip安装狮身人面像。在/MapServer-Documentation目录中,执行:

    python -m pip install -r requirements.txt
    
  2. 如果您想构建pdf,请从http://www.tug.org/mactex/安装Mactex

  3. 要处理文档,请从MapServer/MapServer-Documentation目录运行:

    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有两个共存的系统来管理翻译过程。两者都依赖Sphinx软件。

第一个问题是解决Sphinx软件最初几天缺乏国际化支持的问题。第二个使用新的系统 internationalization 目前仅用于法语翻译。

翻译的“老”方法

虽然我们认为现在的新系统更好,但我们不想强制每个语言社区改变他们的习惯。

  • 所有翻译都组织在MapServer的/MapServer-Documentation目录下的子目录中

  • 这些目录使用以下名称命名 ISO3166-1 alpha-2 country codes ,它还将引用相应的旗帜图标

  • 翻译以英文文档为基础

  • 必须保留目录结构和文件名,它们用于在不同的翻译之间生成链接。

备注

要开始新的转换,请将目录图像和包含从MapServer-Documentation/en复制到MapServer-Documentation/<lang>,其中<lang>是国家代码之一。您还应该将MapServer-Documentation/en/Documentation.txt和MapServer-Documentation/en/index.txt文件复制到您的<lang>目录中(构建过程需要这些文件...您可以根据自己的语言自由编辑它们)。

  • 只有翻译的文件保存在<lang>目录和存储库中。

  • 构建脚本(makefile和make.bat)有一个选项(init)来预处理<lang>目录。这意味着每个未翻译的英文文件都被复制到目标<lang>目录中。您不必这样做就可以在本地构建HTML文件。如果你这样做,你必须清理你的目录之后。

  • 为了使翻译与英文文档保持同步,翻译人员可以监控对存储库的提交。

备注

监控更改的一种方法是通过giHub订阅RSS提要:在MapServer-Documentation存储库中,单击“Commit”选项卡并查找这些提交更改的订阅链接,例如:请参阅https://github.com/MapServer/MapServer-documentation/commits/main上的“Commit History”

  • 您必须通过在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
    
  • 为语言生成文档

Makefile

TRANSLATIONI18N=fr

您还需要更改scripts/build_docs.sh脚本以将您的语言添加到文件顶部:

LANGUAGES= fr

请为这两个参数保留字母顺序以保持它们的可读性。

Structure of the i18n files in the MapServer-documentation root directory

你需要做的所有运输过程的结构如下(摘录给你所需的主要结构)

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代码。FAMFAMAM旗帜图标使用的是ISO国家代码,而TRANSFEX使用的是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/
      

参考标签

:ref :参考标签

标签

书名

关于

About

Agg公司

AGG Rendering Specifics

反别名

AntiAliasing with MapServer

软件工程师

ArcInfo

空间数据引擎

ArcSDE

自动测试

Regression Testing

背景

Tutorial Timeframe

batch_utilities

Batch Scripting

漏洞

Bug Submission

CGI

CGI

cgi_controls

MapServer CGI Controls

cgi_introduction

MapServer CGI Introduction

CLASS

社区

Community Activities

开发

Development

二甘醇

DGN

文档

MapServer 5.2.2 Documentation

documentation_development

Documentation Development Guide

dotnet_compile

.NET MapScript Compilation

下载

Download

dynamic_charting

Dynamic Charting

编辑

Mapfile Editing

错误

Errors

1-1例

Example 1.1

实例1-1-MAP

Example1-1.map

example1-2

Example 1.2

实例1-2-MAP

Example1-2.map

1-3

Example 1.3

1-3图

Example1-3.map

1-4

Example 1.4

1-4图

Example1-4.map

示例1-5

Example 1.5

示例1-5-MAP

Example1-5.map

1-6

Example 1.6

1-6图

Example1-6.map

1-7

Example 1.7

example1-7-map

Example1-7.map

1-8

Example 1.8

1-8图

Example1-8.map

表达

Expressions

常见问题

FAQ

FASTCGI

FastCGI

特征

FEATURE

filter_encoding

WFS Filter Encoding

闪光

Flash Output

字体集

FONTSET

format_types

Data Format Types

基因索引

索引

吉特

GitHub

光泽

Glossary

GML

GML

平均分

GPS Exchange Format (GPX)

网格

GRID

html_legend

HTML Legends with MapServer

iis

IIS Setup for MapServer

图像映射

HTML Imagemaps

包括

INCLUDE

内联的

Inline

输入

Data Input

input_postgis

PostGIS/PostgreSQL

安装

Installation

介绍

An Introduction to MapServer

IRC

IRC

参加

JOIN

KML

KML - Keyhole Markup Language

标签

LABEL

图层

LAYER

传奇

LEGEND

legend_utility

legend

许可

License

Linux

Linux

列表

Mailing Lists

管理

File Management

地图

MAP

map_context

Map Context

mapcache_formats

MapCache Image Formats

mapcache_jpeg_format

MapCache JPEG Format

mapcache_png_format

MapCache PNG Format

mapcache_mixed_format

MapCache Mixed PNG+JPEG Format

mapcache_caches

MapCache Cache Backends

mapcache_grids

MapCache Tile Grids

mapcache_cache_sqlite

MapCache Sqlite Caches

mapcache_cache_disk

MapCache Disk Caches

mapcache_cache_memcache

MapCache Memcache Caches

mapcache_cache_tiff

MapCache TIFF Caches

mapcache_services

MapCache Tile Services

mapcache_ve

MapCache VirtualEarth Quadkey Tile Service

mapcache_tms

MapCache Tile Map Service

mapcache_kml

MapCache Super-Overlay KML Services

mapcache_wmts

MapCache OGC WMTS Service

mapcache_wms

MapCache OGC WMS Service

mapcache_gmaps

MapCache GoogleMaps Tile Service

mapcache_proxying

MapCache Proxying Support

mapcache_dimensions

MapCache Tileset Dimensions

mapcache_featureinfo

MapCache FeatureInfo Requests

mapcache_tile_assembling

MapCache Tile Assembling

mapcache_sources

MapCache Input Sources

mapcache_source_wms

MapCache WMS Source

mapcache_source_mapfile

MapCache Native MapServer Sources

mapcache_http

MapCache HTTP Request

mapcontext_cgi

Map Context Files

映射文件

Mapfile

mapfile_tuning

Mapfile

地理信息系统

MapInfo

MapScript

MapScript

mapscript_ows

MapScript Wrappers for WxS Services

mapscript_tests

MapScript Unit Testing

MAPSERV公司

mapserv

模式索引

模块索引

MSN

msencrypt

MySQL

MySQL

NTF

NTF

OCI

Oracle Spatial

oci_install

Oracle Installation

OGC

OGC Support and Configuration

ogc_support

OGC Support

奥格尔

OGR

online_resource_wms

More About the Online Resource URL

优化

Optimization

OSX公司

Mac OS X

输出

Output Generation

输出格式

OUTPUTFORMAT

PDF

PDF Output

PGEO

ESRI Personal Geodatabase (MDB)

PHP

PHP MapScript

php_example

By Example

php_install

PHP MapScript Installation

php_install_example_steps

Example Steps of a Full Windows Installation

投影

PROJECTION

PSC

Project Steering Committee

Python

Python MapScript Appendix

查询

Querying

查询程序

QUERYMAP

栅格

Raster Data

raster_optimization

Raster

参考

REFERENCE

射频芯片1

MS RFC 1: Technical Steering Committee Guidelines

射频C10

MS RFC 10: Joining the Open Source Geospatial Foundation

射频C11

MS RFC 11: Support for Curved Labels

射频芯片12

MS RFC 12: C code Unit tests

射频芯片13

MS RFC 13: Support of Sensor Observation Service in MapServer

射频芯片14

MS RFC 14: Relative Coordinates for INLINE features

RCF15

MS RFC 15: Support for thread neutral operation of MapServer/MapScript

射频芯片16

MS RFC 16: MapScript WxS Services

重组腺病毒17

MS RFC 17: Dynamic Allocation of layers, styles, classes and symbols

射频C18

MS RFC 18: Encryption of passwords in mapfiles

重组腺病毒19

MS RFC 19: Style & Label attribute binding

射频电容器2

MS RFC 2: Creating line features and/or shapes using WKT

射频芯片21

MS RFC 21: MapServer Raster Color Correction

射频芯片22A

MS RFC 22a: Feature cache for long running processes and query processing

射频芯片23

MS RFC 23: Technical Steering Committee Guidelines

射频芯片24

MS RFC 24: Mapscript memory management

RFC241

MS RFC 24: Mapscript memory management

RCF25

MS RFC 25: Align MapServer pixel and extent models with OGC models

RFC26

MS RFC 26: Version 5 Terminology Cleanup

重组蛋白C27

MS RFC 27: Label Priority

RCF28

MS RFC 28: Redesign of LOG/DEBUG output mechanisms

射频C29

MS RFC 29: Dynamic Charting Capability

射频电容器3

MS RFC 3: Feature Layer Plug-in Architecture

射频芯片30

MS RFC 30: Support for WMS 1.3.0

射频芯片31

MS RFC 31: Loading MapServer Objects from Strings

RFC32型

MS RFC 32: Support for Anti-Grain Geometry (AGG) Rendering Engine

射频芯片33

MS RFC 33: Removing msLayerWhichItems() from maplayer.c

射频芯片39

MS RFC 39: Support of WMS/SLD Named Styles

射频电容器4

MS RFC 4: MapServer Raster Resampling

射频电容器40

MS RFC 40: Support Label Text Transformations

RFC41型

MS RFC 41: Support of WCS 1.1.x Protocol

射频芯片42

MS RFC 42: Support of Cookies Forwarding

射频芯片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

MS RFC 46: Migrate Website to OSGeo

射频芯片47

MS RFC 47: Move IGNORE_MISSING_DATA to run-time configuration

RCF48

MS RFC 48: GEOTRANSFORM Geometry operations

RFC49

MS RFC 49: Symbology, Labeling, and Cartography Improvements

RCF5

MS RFC 5: MapServer Horizon Reprojection Improvements

射频消减

MS RFC 50: OpenGL Rendering Support

射频芯片51

MS RFC 51: XML Mapfile Format

射频芯片53

MS RFC 53: Guidelines for MapScript method return values

RFC54

MS RFC 54: Rendering Interface API

射频卡55

MS RFC 55: Improve control of output resolution

射频芯片56

MS RFC 56: Tighten control of access to mapfiles and templates

rfc6

MS RFC 6: Color Range Mapping of Continuous Feature Values

射频C7

MS RFC 7: MapServer CVS Commit Management

rfc7.1

MS RFC 7.1: MapServer SVN Commit Management

射频C8

MS RFC 8: Pluggable External Feature Layer Providers

RFC9型

MS RFC 9: Item tag for query templates

RFCS

Request for Comments

运行子

Run-time Substitution

S57

S57

标尺

SCALEBAR

scalebar_utility

scalebar

SDTS

SDTS

搜索

搜索页面

第一节

Section 1: Static Maps and the MapFile

第二节

Section 2: CGI variables and the User Interface

形状文件

ESRI Shapefiles (SHP)

Sp2IMG

shp2img

希普特里

shptree

希普雷特维斯

shptreevis

SLD

SLD

SORTHHP

sortshp

sos_server

SOS Server

来源

Source

赞助商

Sponsors

风格

STYLE

样式项自动标签样式

Accessing OGR STYLEITEMAUTO Label Styles Through MapScript

svg

SVG

svn

Subversion

斯威格

SWIG MapScript API Reference

Sim2img

sym2img

sym_construction

Cartographic Symbol Construction with MapServer

sym_examples

Symbology Examples

符号

SYMBOL

模板

Templating

测试

Testing

老虎

USGS TIGER

Ti4Ms

tile4ms

tile_mode

Tile Mode

倾斜指数

Tile Indexes

教程

MapServer Tutorial

UNIX

Compiling on Unix

公用事业

Utilities

variable_sub

Variable Substitution

矢量

Vector Data

vector_optimization

Vector

vim

VIM Syntax

virtual_vector

Virtual Spatial Data

wcs_format

WCS Use Cases

wcs_server

WCS Server

网状物

WEB

WFS

WFS

wfs_client

WFS Client

wfs_server

WFS Server

Win32

Compiling on Win32

windows

Windows

wms_capabilities

Validate the Capabilities Metadata

wms_client

WMS Client

wms_server

WMS Server

wms_time

WMS Time

包装器

A Simple CGI Wrapper Script

重新生成参考标签

可以通过发出以下命令重新生成引用标签:

make labels

在MapServer-Documentation目录中,与构建html或LaTeX版本时类似