Module talk:Citation/CS1/Utilities

message: 已通過已通过--Antigng（留言） 2022年4月26日 (二) 16:16 (UTC)
replies: text: 下列討論已經關閉，請勿修改。如有任何意見，請至合適的討論頁進行，並不要再次編輯本討論。
----
本站CS1系列模板先后历经四轮小规模更新，目前英文站模板较常用而本站模板过去没有的参数，如url-access，url-status，name-list-style，各种文献标识符及对应的-access参数均在这四轮更新中逐步引进。:Category:含有未知参数的引用的页面中页面的数量也从去年的四千余个降低至目前的约1500个 ，足见更新之成效。本轮CS1模板更新，表面上主要涉及以下三方面：
*一是启用chapter-url-access（section-url-access为其别名）和map-url-access参数，分别用于填写chapter-url（section-url）和map-url的访问状态（有限度免费访问/需要注册/订阅等）。效果如下：
**例1：
**更新前：Glut, Donald F. -{Appendix: Dinosaur Tracks and Eggs}-. -{Dinosaurs: The Encyclopedia. 3rd Supplement}-. Jefferson, North Carolina: McFarland & Company, Inc. 2003: 613–652. ISBN 0-7864-1166-X.  含有內容需登入查看的頁面 (link)Category:含有內容需登入查看的頁面
**更新后：Glut, Donald F. -{Appendix: Dinosaur Tracks and Eggs}-. -{Dinosaurs: The Encyclopedia. 3rd Supplement}-. Jefferson, North Carolina: McFarland & Company, Inc. 2003: 613–652. ISBN 0-7864-1166-X.  含有內容需登入查看的頁面 (link)Category:含有內容需登入查看的頁面
*二是临时在本地修复了由于mediawiki内部代码缺乏更新而引起的语言参数不正常显示的问题。见上方讨论。
*三是调整完善了模板的一些显示方式，特别是错误信息的显示，较为明显的改动有：
**a. 本轮更新后，模板未填写作者（author系列参数）或贡献者（contributor系列参数），但填写编者（editor系列参数）时，模板将依所填写的编者参数生成元数据（COinS）作者栏位的信息。考虑到部分性质的来源（如百科全书），编者等同于实质上的作者，这一处理应当是合理的。
**b. CS1系列模板中各模板支持的参数略有不同。例如，模板填写卷（volume参数）是没有意义的，模板填写邮件列表（mailing-list）参数是没有意义的。现在模板的处理方式是直接丢弃这些参数而不告知使用者。本轮更新后，遇到相应的情况模板会红字报错，并将页面纳入追踪分类:Category:引文格式1错误：已知参数被忽略。这有助于编者及时发现参数使用方面的错误（其中有一些还很隐蔽，例如bookTitle参数很容易被“望文生义”成“书名”，但实际上仅有模板支持，模板反而不支持）。以下是一些例子：
***例2b1： 注：bookTitle参数仅模板支持
***更新前：Herbst, T. M.; Rix, H.-W. Guenther, Eike; Stecklum, Bringfried; Klose, Sylvio , 编. -{Star Formation and Extrasolar Planet Studies with Near-Infrared Interferometry on the LBT}-. San Francisco, Calif.: Astronomical Society of the Pacific. 1999: 341–350. Bibcode:1999ASPC..188..341H. ISBN 1-58381-014-5.  |book-title=被忽略 (帮助)Category:引文格式1错误：已知参数被忽略
***更新后：Herbst, T. M.; Rix, H.-W. Guenther, Eike; Stecklum, Bringfried; Klose, Sylvio , 编. -{Star Formation and Extrasolar Planet Studies with Near-Infrared Interferometry on the LBT}-. San Francisco, Calif.: Astronomical Society of the Pacific. 1999: 341–350. Bibcode:1999ASPC..188..341H. ISBN 1-58381-014-5.  |book-title=被忽略 (帮助)Category:引文格式1错误：已知参数被忽略
***例2b2：注：不支持volume与issue
***更新前：Vijverberg;  等. -{Similar mode of action of pyrethroids and DDT on sodium channel gating in myelinated nerves}-. Nature. 1982  [2012-04-28].  参数|journal=与模板不匹配（建议改用或|website=） (帮助); |volume=被忽略 (帮助); |issue=被忽略 (帮助) 引文格式1维护：显式使用等标签 (link)Category:引文格式1错误：periodical系列参数与模板类型不匹配Category:引文格式1错误：已知参数被忽略Category:引文格式1维护：显式使用等标签
***更新后：Vijverberg;  等. -{Similar mode of action of pyrethroids and DDT on sodium channel gating in myelinated nerves}-. Nature. 1982  [2012-04-28].  参数|journal=与模板不匹配（建议改用或|website=） (帮助); |volume=被忽略 (帮助); |issue=被忽略 (帮助) 引文格式1维护：显式使用等标签 (link)Category:引文格式1错误：periodical系列参数与模板类型不匹配Category:引文格式1错误：已知参数被忽略Category:引文格式1维护：显式使用等标签
***例2b3：注：仅支持degree参数
***更新前：許宗傑. -{《清代澎湖方志研究》}-: 15–16. 2011-01.  |degree=被忽略 (帮助) 含有內容需登入查看的頁面 (link)Category:引文格式1错误：已知参数被忽略Category:含有內容需登入查看的頁面
***更新后：許宗傑. -{《清代澎湖方志研究》}-: 15–16. 2011-01.  |degree=被忽略 (帮助) 含有內容需登入查看的頁面 (link)Category:引文格式1错误：已知参数被忽略Category:含有內容需登入查看的頁面
**c. 此外，引用模板内部的参数之间存在较为复杂的关系，可能出现“某个参数填写以后另一个参数的值被丢弃”的情况。当前模板的做法是直接丢弃有关参数。本轮更新后，将尽可能地以红字报告“只需其一”错误，方便编者查错。如下例所示：
***例2c：注：quote参数填写后，post-script参数会被丢弃
***更新前：-{Title}-. this is a test  |quote=和|postscript=只需其一 (帮助)Category:含有冗余参数的引用的页面
***更新后：-{Title}-. this is a test  |quote=和|postscript=只需其一 (帮助)Category:含有冗余参数的引用的页面
**d. 特别地，当日期与年份同时填写，两者的参数值都有效，但彼此不兼容的情况下，将红字报错：
***例2d：
***更新前：-{Title}-. 2020-01-01.  |year=与|date=不匹配 (帮助)Category:引文格式1错误：日期与年不匹配
***更新后：-{Title}-. 2020-01-01.  |year=与|date=不匹配 (帮助)Category:引文格式1错误：日期与年不匹配
**e. 最后，完善了部分界面文字的显示方式：
***例2e1：
***更新前：-{xxx研究}- (学位论文). xx大学学报. 2022. 
***更新后：-{xxx研究}- (学位论文). xx大学学报. 2022. 
***例2e2：
***更新前：Eskew, Mike. -{Economic Isolationism Isn't an Option}- (演讲). Executive Speeches. Washington, D.C. December 30, 2004. 
***更新后：Eskew, Mike. -{Economic Isolationism Isn't an Option}- (演讲). Executive Speeches. Washington, D.C. December 30, 2004. 
***例2e3：
***更新前：-{Title}-. （原始内容存档于2020-07-29）.  无效|url-status=bot: unknown (帮助)Category:引文格式1错误：无效参数值
***更新后：-{Title}-. （原始内容存档于2020-07-29）.  无效|url-status=bot: unknown (帮助)Category:引文格式1错误：无效参数值
***例2e4：注：当前模板显示实际上没有填写的|url=参数有问题，是因为模板的内部逻辑将输入的|publisher=参数当成url的一部分处理，更新后已正确反映这一点
***更新前：-{Title}-. Newsgroup: Publisher 请检查|publisher=值 (帮助).  |newsgroup=和|publisher=只需其一 (帮助)Category:含有冗余参数的引用的页面Category:含有网址格式错误的引用的页面
***更新后：-{Title}-. Newsgroup: Publisher 请检查|publisher=值 (帮助).  |newsgroup=和|publisher=只需其一 (帮助)Category:含有冗余参数的引用的页面Category:含有网址格式错误的引用的页面
对技术问题不感兴趣可以跳过这一段
但实际上，本轮更新中最主要的更改是针对模板内部。当前CS1模块调用的主模块Module:Citation/CS1过于冗长（接近15万字节），长到页面都不显示语法高亮。该模块做的事情，简单来说是先初始化，然后检查一下输入的参数是否在白名单之中，再调用一个一千多行的函数citation0（现已更名do_citation）输出引文。与do_citation函数相配套，整个主模块设置了大量的辅助函数——小到字符串处理大到人名列表，错误信息的分类维护都有涉及。虽然英文站尝试将主模块中一部分高使用量的函数拆分出来，另立模块Module:Citation/CS1/Utilities加以收纳，但主模块又长又杂的状况几无改善（英文站相应模块的问题更为严重，而且越来越严重）。
为解决这一问题，本轮更新将通过三种手段缩减主模块乃至其中关键函数do_citation的长度：
*一是新设/启用/调整子模块。
**本轮更新将启用：
***Module:Citation/CS1/COinS模块，拆分出原先主模块中处理引用元数据的逻辑。
**同时新设以下四个子模块：
***Module:Citation/CS1/Error模块，集中处理错误/维护分类和信息。旧系列模块中到处乱跑的全局变量z也将封装入该模块，不再导出。同时，还修复了旧模块中“引文格式1错误”分类重复加入的问题。
***Module:Citation/CS1/People模块，拆分出既有主模块中涉及人名及其列表的逻辑。目前仅仅只是将垃圾代码转移了地方，有待后续清理。
***Module:Citation/CS1/Links模块，集中处理和维基内链/外链相关的操作。
***Module:Citation/CS1/Languages模块，拆分出主模块中与语言相关的代码。上节所述问题二的修复也是通过在该模块中引入本地翻译表local_table实现的。
**并将既有Module:Citation/CS1/Utilities调整为收录无副作用且简单的纯函数，主要涉及字串处理以及格式转换。
*二是尽可能抽象出各处代码的共同逻辑并将之函数化，同时清理主模块中硬编码的界面文字（甚至还有译文）并将之转移至配置模块Module:Citation/CS1/Configuration中。该轮更新后，配置模块新增args_support表，存放实现上节所述第三项(b)部分功能所需使用的信息；新增extra_text_pattern表，转移主模块中检查|page=，|edition=等参数中冗余文字所使用的正则表达式。其余转移的界面文字则放入message，presentation，keywords，error_conditions等既有表中。
*三是删除/修复了部分死代码，例如永远不成立的条件表达式等。
通过上述措施，主模块Module:Citation/CS1大小减半，do_citation行数减至约700行（虽然还是很长），也能正常显示语法高亮。Module:Citation/CS1/Identifiers模块、Module:Citation/CS1/Whitelist模块作相应配套性修改。
*测试见：Module_talk:Citation/CS1/testcases/urlaccess/Antigng、Module_talk:Citation/CS1/testcases/Antigng、Module_talk:Citation/CS1/testcases2/Antigng、Module_talk:Citation/CS1/testcases/errors/Antigng、Module_talk:Citation/CS1/testcases/identifiers/Antigng。与过往几轮更新不同，本轮更新因涉及模块的大规模拆分，可能有下列潜在负面影响：
**一是模板的开销变大，以至于大页面更容易超出模板限制。
**二是本轮更新后将与英文站相应模板彻底不兼容，未来英文站的更新将难以简单移植入本站。
最后，欢迎大家用沙盒版本的CS1模板（例如：，）进行测试。--Antigng（留言） 2022年4月12日 (二) 17:34 (UTC)

text: @Antigng 请问，里面的 id=，这个参数id的选项是否可以多加几个，比如说几十年前没有ISBN、且没有录入OCLC的书籍，用类似NDL 12345677. NLC 12345677去定位。--Kethyga（留言） 2022年4月13日 (三) 02:48 (UTC)
replies: text: :@-{Kethyga}-：目前引文模板中|id=参数起到的就是后备用途，也就是所有模板本身没有支持的文献标识符参数都可以填写在|id=参数中；该参数没有任何格式上的限制，想填什么填什么。当然如果您的需求是像|doi=，|pmid=一样另设文献标识符参数并统一格式，可以在后续更新中予以考虑。由于本人对之不甚熟悉，可能需要麻烦您提供相关参数的定义，以及合法的范围等信息。--Antigng（留言） 2022年4月13日 (三) 03:22 (UTC)
replies: text: ::重新测试了下，Special:diff/71124395，可以用形如|id=. 的方式添加多个。之前想法固定在只能添加一个模板上了。--Kethyga（留言） 2022年4月13日 (三) 06:35 (UTC)

text: (！)意見：目前沙盒版本“chapter-url-access=free”会出现“可免费查阅”的绿锁，但根据英文版的解释，一般而言这类网址是被假定为可免费访问，所以兼容free参数值是没有必要的。应该是：

text: *url-access/article-url-access/chapter-url-access/contribution-url-access/entry-url-access/map-url-access/section-url-access = registration / limited / subscription

text: *bibcode-access / doi-access / hdl-access / jstor-access / ol-access / osti-access / s2cid-access = free--BlackShadowG Pray for Ukraine 2022年4月14日 (四) 13:25 (UTC)
replies: text: :简单来说，编者提供的链接（如：url、chapter-url）默认是能免费查阅的，只需要标记需要付费或注册的即可；文献标识符自动生成的链接（如：doi、jstor）默认是不能免费查阅的，只需要标记免费的即可。--BlackShadowG Pray for Ukraine 2022年4月14日 (四) 13:31 (UTC)
replies: text: ::已修正，请复查。--Antigng（留言） 2022年4月14日 (四) 14:38 (UTC)

text: 公示七日。--Antigng（留言） 2022年4月20日 (三) 15:31 (UTC)
----

text: 本討論已經關閉，請勿修改。如有任何意見，請至合適的討論頁進行，並不要再次編輯本討論。
thread_title:  修改[[Module:Citation/CS1|CS1系列引文格式模板]]（第五阶段）：新增chapter-url-access、map-url-access参数；临时修复语言代码显示问题；改善模板信息的显示方式；模板内部逻辑大规模拆分整理