Skip to content

Latest commit

 

History

History
108 lines (77 loc) · 10.4 KB

diff-spec.md

File metadata and controls

108 lines (77 loc) · 10.4 KB

本项目使用的 diff 规范

概述

这套 diff 规范名为 area-diff,基于 git-diff 修改而来,旨在尽可能精确描述新旧区划代码间的对应关系。这套规范的制定始终遵从以下三点原则:

  • 逻辑严密:以行政区域的相交来定义新旧区划代码间的对应关系。
  • 易于维护:语法简洁且符合直觉,使用区划名称表示对应关系,便于数据的录入和校对。
  • 利于分析:能以简单的算法分析出代码间的对应关系并清晰呈现。

背景

  1. data 目录下的每一个文件称为一个区划代码数据表,简称数据表。数据表的每一行称为一条区划代码记录,简称记录。一条记录由代码和名称组成,由一个空格隔开。每一条记录都与一定范围的行政区域相对应,称为该记录的区域。

  2. 存在一条唯一且不变的根记录,其代码为 000000,名称为 中华人民共和国,其区域为中华人民共和国全境,包括香港特别行政区、澳门特别行政区和台湾省。

  3. 除根记录以外,代码的后四位数字均为 0 的记录称为一级(省级)记录,非一级记录且代码的后两位数字均为 0 的记录称为二级(地级)记录,非一、二级记录的其余记录称为三级(县级)记录。两条记录同级,当且仅当其同时为一级、二级或三级记录。

  4. 在同一个数据表中,成立以下关系:代码的前四位数字与某条二级记录相同的三级记录称为这条二级记录的子记录,这条二级记录称为这些三级记录的父记录;二级记录和无二级父记录的三级记录,若其代码的前两位数字与某条一级记录相同,则称为这条一级记录的子记录,这条一级记录称为这些二级记录和三级记录的父记录。根记录为所有一级记录的父记录。

  5. 一条记录的无子记录覆盖区域存在,当且仅当其满足以下两种情况之一:

    • 其没有子记录,此时其区域即为其无子记录覆盖区域。
    • 其所有子记录的区域不能完全覆盖其区域,此时其区域中未被其子记录的区域覆盖的部分即为其无子记录覆盖区域。
  6. diff 目录下的每一个文件称为一个差异表,包含相应的两个数据表中记录的代码、名称或区域的差异,其中作为相对参考的数据表称为源表,与之相对的数据表称为目标表。差异表的原始内容是通过对相应的数据表执行 git diff -U0 --no-index 并去除无关或重复行后得到的。

规则

  1. 差异表的每一非空行分为四种类型,由其首字符决定,分别为删除行(-)、增加行(+)、转移行(=)及注释行(#)。其中,删除行、增加行和转移行统称为变更行。

  2. 对差异表的任何修改都应当遵守以下规则:

    • 当一条记录的代码或名称于两年间变更时,称源表中的旧记录变更为目标表中的新记录;此时,若差异表的原始内容未包含与旧记录的某条子记录对应的删除行或与新记录的某条子记录对应的增加行,应当向差异表中添加一条这样的删除行或增加行。例如:
      • 1981-1982 年间,410600 焦作市 变更为 410800 焦作市,但差异表的原始内容未包含与旧记录的子记录 410611 郊区 对应的删除行,于是添加一行 -410611 郊区>_(焦作市)。
      • 1981-1982 年间,410500 鹤壁市 变更为 410600 鹤壁市,但差异表的原始内容未包含与新记录的子记录 410611 郊区 对应的增加行,于是添加一行 +410611 郊区<_(鹤壁市)。
      • 1995-1996 年间,421000 荆沙市 变更为 421000 荆州市,但差异表的原始内容未包含与旧记录及新记录的子记录 421002 沙市区 等对应的删除行及增加行,于是添加 -421002 沙市区>. 及 +421002 沙市区<. 等行。
    • 除非上一条规则适用,或对相应的数据表已进行订正并记录在 errata.md 中,否则不得删除差异表中包含原始内容的行,修改其中的原始内容,或向其中添加删除行或增加行。
    • 修改差异表中包含原始内容的行时,必须将其中的原始内容始终保持在行首,只修改原始内容之后到行尾的内容。
    • 差异表中的所有行不区分先后,因此可以任意排序,但需注意保持一定的结构。
    • 差异表中的所有行的语法必须严格遵守随后的语法规范。
  3. 每一变更行在相应的数据表中都有其对应的记录,称为该行的记录。删除行的记录位于源表中。增加行的记录位于目标表中。转移行的记录同时位于源表和目标表中。

  4. 变更行由其首字符、其记录和其属性依序连接而成。变更行的属性用于说明该行的记录的区域与相关记录的区域的相交关系。变更行的属性为空,当且仅当该行为删除行或增加行且其记录有子记录。下文中讨论一行的属性时,均假定其非空。

  5. 删除行的属性以字符 > 起始,后接一个或多个以字符 , 分隔的记录选择器。增加行的属性以字符 < 起始,其后的语法与删除行相同。转移行的属性语法,要么与删除行相同,要么与增加行相同。

  6. 记录选择器有五种类型,分别为:指定名称、当前名称、当前代码、父代码和存疑。其中,前四种选择器统称为普通选择器。各选择器的定义如下:

    • 指定名称选择器的值为字符串,其选择步骤如下:
      1. 选择名称与其值相同的记录,若无则继续,若唯一则返回该记录,若多于一条则在其值前添加当前记录的父记录名称并继续。
      2. 对于其值的每个前缀,标记名称与该前缀相同的记录。
      3. 若标记的记录不唯一则终止,否则从其值中移除相应的前缀并继续。
      4. 选择名称与其值相同的,以标记的记录为父记录的记录。
    • 当前名称选择器的值为 _,等价于这样的指定名称选择器,其值与当前行的记录的名称相同。
    • 当前代码选择器的值为 .,选择与当前行的记录具有相同代码的记录。
    • 父代码选择器的值为 ..,选择与当前行的记录的父记录具有相同代码的记录。
    • 存疑选择器的值由一普通选择器的值后接一存疑标志组成。存疑标志的可用值为 ? 和 !,其中 ? 指示该选择器无效并将其禁用,一般用于相应记录不存在时;而 ! 指示该选择器有效,其选择的记录与内含的普通选择器相同,一般用于相应记录存在,变更无官方公告,但有充分的理由启用该选择器时。

    变更表中每一有效的记录选择器选择的记录必须唯一。遵守本规范的实现,在某一有效的选择器选择的记录不唯一时,应当终止运行并提醒用户通知变更表的维护者。

  7. 删除(增加)行的属性选择目标(源)表中所有无子记录覆盖区域与该行的记录的区域相交的记录。通过改变转移行的首字符,可得到与之对应的删除行或增加行。转移行的属性所选择的记录,是从其对应的删除行或增加行的属性所选择的记录中去除该行自身的记录后的结果。

  8. 差异表中一行或多行连续的注释行组成变更描述,描述紧接其后的一行或多行连续的变更行(若紧接其后的不是变更行则悬空,即作为普通注释,不描述变更行,此时需要提醒用户检查是否刻意为之)。变更行必须被描述。

    对于一条变更描述,将组成其的注释行行首的 # 与其后的空白字符去除后,以 \n 连接各行即得到其内容。变更描述的内容使用 Markdown 语法,可使用标题分级,一级标题隐含在其描述的变更中,二级标题由单个 # 起始,以此类推(与 Rust 的文档注释类似)。

    在变更描述的内容中,紧跟标题后的一行或多行连续的非空行是描述该章节的元数据,每行由键值对组成,格式为 {键}:{值}。一般应填写的键有 文号、日期 和 来源。

    变更描述应尽可能详细,填写来源时尽可能使用超链接。为防止链接失效,可手动或自动将对应的网页或文件存档。

注意事项

  1. 在将区划变更情况的文字描述录入差异表时,需要额外考虑转移的存在,这可以通过在来源中搜索关键词“划归”、“划入”和“并入”并手动筛选得到。每一年的转移行录入完毕后,应当按年份记录在 diff-notes.md 中,若没有则记录“无”。

例子

  • 撤销崇川区、港闸区,设立新的南通市崇川区,以原崇川区、港闸区的行政区域为新的崇川区的行政区域。

    -320602 崇川区>_
    -320611 港闸区>崇川区
    +320613 崇川区<_,港闸区
  • 邢台市桥西区更名为信都区。

    -130503 桥西区>.
    +130503 信都区<.
  • 将磁县高臾镇、光禄镇、辛庄营乡、花官营乡、台城乡划归邯郸市邯山区管辖,将磁县林坛镇、南城乡划归邯郸市复兴区管辖。

    将巴音郭楞蒙古自治州和静县、焉耆回族自治县、博湖县、和硕县、若羌县、且末县的部分区域划归铁门关市管辖。

    =130427 磁县>邯山区,复兴区
    =659006 铁门关市<和静县,焉耆回族自治县,博湖县,和硕县,若羌县,且末县
  • 带有完整变更描述的例子:

    ## 国务院关于同意甘肃省撤销武威县设立武威市给甘肃省人民政府的批复
    # 文号:(85)国函字53号
    # 日期:一九八五年四月十五日
    # 来源:《国务院公报》1985年第12号第32页
    #
    # 你省一九八五年三月九日《关于将武威县改设为武威市的报告》收悉。同意撤销武威县,设立武威市(县级),以原武威县的行政区域为武威市的行政区域。
    -622321 武威县>武威市
    +622301 武威市<武威县
  • 更多的例子:参见已完成的差异表(如 1984-1985.diff)和相应的文字描述。