Skip to content

关于文件

Jump to bottom
cppHusky edited this page Nov 18, 2024 · 4 revisions

文件 URL

你上传的文件将按照其 md5sum 来重命名，并存储为 https://byrdocs.org/files/${md5}.${ext}，例如：

  • https://byrdocs.org/files/dd6388976e48a6ce2f8a30355acfcba0.pdf
  • https://byrdocs.org/files/62b43f8fbed2bb3087f2afc96fd89b0f.zip

文件 URL 的结构就是这样简单。所以，如果你预先知道了某个文件的 md5sum（及其后缀名），你就可以直接通过 URL 来下载它。

Note

我们仍然推荐你通过 BYR Docs 下载文件，因为通过 BYR Docs 下载的文件会自动重命名；而通过 URL 直接下载的文件不会重命名，仍使用 md5sum 作为文件名，不便于使用。

你上传的文件也是如此。通过 byrdocs-cli 上传的文件会重命名，然后其他人可以通过 URL 直接下载它。但是注意，如果不通过审核，这些文件是无法搜索到的。

文件收录规则

我们人为地将文件区分成三个类别（type）：书籍（book）、试题（test）、资料（doc）。

  • 书籍 必须满足以下条件
    • 是书籍（课件、笔记等形式不符合书籍这一定义）
    • 是PDF格式的电子书（若为EPUB等其它格式，请考虑转换为PDF）
    • 是正式出版物（以个人/团体名义公开发表，但未经出版的书籍不属于此类）
    • 是教育资源（小说、散文、漫画不属于此类，除非有足够充分的证据证明它是教育资源）
  • 试题 必须满足以下条件
    • 是PDF格式的电子资料（若为纸质资料，可自行扫描、交由本团队扫描，或通过 考题补完计划 制作电子版
    • 来自北京邮电大学（不可以是外校试题）
    • 是期中/期末考试题（不可以是月考、随堂作业等阶段性试题）
    • 必须是一套实际考过的真题，正常考或缓考均可（不可以是题库、模拟卷等。即使其中的大多数题目真的出现在真题中也不行）
  • 资料 可以认为是以上两类的补集，不符合以上两类要求的文件可以算作此类，但是仍需满足以下条件
    • 是PDF或ZIP格式（如不是，可考虑自行制作ZIP格式再提交）
    • 是教育资源（学校的培养方案、规章通知等不属于此类）
    • 必须能够对应到至少一门课程（否则就是无关资料）
    • 必须与课程学习、考试复习相关（竞赛资料，例如大学生数学竞赛、大学生英语竞赛的相关资料不应收录）

一个文件即便符合以上条件，也有可能因为质量不过关而遭拒。

  • 文件模糊不清晰，影响正常阅读。请自行想办法解决。
  • 文件有明显的缺页、重页、页面乱序问题，影响正常阅读。请自行收集缺页，删除重页或调整页面顺序。
  • 文件杂糅（比如，多套题目合并到了同一个PDF文件中）。请自行拆分为多个PDF，再分别提交。
  • 缺失封面（说来话长，见文件封面）

文件元信息

为了方便检索，我们必须为每个文件录入一些元信息，比如名称、学科、版本等。

每种类别的资料都有各自的特征，所以不同类别的信息都有不同的元信息格式。你必须按照规定的格式来填写文件元信息。本项目的元信息使用 .yml 文件保存。

在编写元信息时，推荐使用 yaml 相关的语法支持（Eclipse Desktop IDE, Eclipse Che, VS Code, IntelliJ, Emacs, vim），并在文件开头根据文件类型加入不同的 schema 注释。

# yaml-language-server: $schema=https://byrdocs.org/schema/book.yaml
# yaml-language-server: $schema=https://byrdocs.org/schema/doc.yaml
# yaml-language-server: $schema=https://byrdocs.org/schema/test.yaml

下面的三个例子详细解释了不同类别的信息格式：

书籍

# yaml-language-server: $schema=https://byrdocs.org/schema/book.yaml

# 文件的 MD5 值
id: 06fa27d50ba4a4baae1b665ea48fd677

# 通过 byrdocs-cli 上传文件后得到的 URL
url: https://byrdocs.org/files/06fa27d50ba4a4baae1b665ea48fd677.pdf

# 必须是 book/test/doc 三者之一。
# 一旦确定下来，后续的内容必须按照以下格式填写
type: book

data:
  # title 需与原书保持一致。部分书藉的封面标题与信息页标题不完全一致，填写哪一个都可行
  # 中文书（包括外文书的中译本）使用中文书名，如「操作系统概念（原书第9版）」
  # 外文书（包括中文书的外文译本）使用外文书名，如「Calculus」），但有如下例外
  # 1. 语言类课程使用的外语教科书，仍用中文书名，如「全新版大学英语综合教程学生用书2」
  # 2. 由中方编著的国际学院外文教科书，使用双语书名，如「线性代数/Linear Algebra」
  # 3. 繁体中文书名的处理方法视同外文书
  title: 理论物理学教程 第10卷 物理动理学 第2版
  
  # 填写为数组，必填
  # 尽量使用原名而非中译名。若作者原名不是英文名，可酌情考虑标注一个中译名
  authors:
    - Лифшиц, Евгений Михайлович(粟弗席兹)
    - Питаевский, Лев Петрович(皮塔耶夫斯基)
    
  # 如没有/未知译者，可省略此字段
  translators:
    - 徐锡申
    - 徐春华
    - 黄京民

  # 对于译著而言，其原著的版本一般不等于译著的版本
  # 比如本书是原著第2版，译著第1版。这时，edition 中应填译著的版本。
  # 至于原著版本，可以填入 title 中
  # 如未知版次，省略此字段
  edition: '1'

  # 如未知出版社，省略此字段
  # 如果是译著，必须填写译著的出版社
  # 出版社原名为英文的，使用英文名；其他语言的，使用中译名或英译名
  publisher: 高等教育出版社

  # 如未知出版年份，省略此字段
  # 如果是译著，必须填译著的出版年份
  publish_year: '2008'

  # 必填
  # 如果是译著，必须填译著的ISBN
  # 必须填写为 ISBN13 格式，不接受 ISBN10。
  # 如有多个 ISBN，可以全部填写
  isbn:
    - 978-7-04-023069-7
    
  # 原则上只能是 pdf 格式
  filetype: pdf

试题

# yaml-language-server: $schema=https://byrdocs.org/schema/test.yaml

# 文件的 MD5 值
id: 154a930358251fe7bf774dd194bd9a00

# 通过 byrdocs-cli 上传文件后得到的 URL
url: https://byrdocs.org/files/154a930358251fe7bf774dd194bd9a00.pdf

# 必须是 book/test/doc 三者之一。
# 一旦确定下来，后续的内容必须按照以下格式填写
type: test

data:
  # 如未知学院，可省略此字段
  # 只有当你确认「此学院在当时实际考过这份考卷」时，才可以填写这个学院。如无法确认，应当不填
  college:
    - 人工智能学院
    - 自动化学院
    - 信息与通信工程学院

  # 试题相关的课程，必填
  course:
    # 「本科」或「研究生」，如未知请省略此字段
    type: 本科
    # 对应课程的全称，必填。需要包括字母和括号中的内容，比如「高等数学A（上）」
    # 即便是外文考试，也应当填写中文课程名
    name: 概率论与数理统计

  # 必填，至少需要填写 start 和 end
  # 时间信息应精确到某学年的某学期，比如这里就是 2023-2024 学年第二学期。
  # 如果文件中的信息不全，就只能做到尽量精确
  time:
    # 如果只能精确到某一年，但不知学期起止年，可以为 start 和 end 填写同一个值，比如都是 2024
    # 完全不知道年份的试题是不应该收录的
    start: '2023'
    end: '2024'
    
    # 只能填写「First」「Second」中的一个，如果无法精确到某个学期，可省略此字段
    semester: Second
    # 只能填写「期中」「期末」中的一个。如果无法精确到某个阶段，可省略此字段
    stage: 期末
  
  # 原则上只能是 pdf 格式
  filetype: pdf

  # 必填，只能填写「原题」「答案」中的一个或多个
  # 如果只有答案而没有题面，不能算作「原题」
  # 如果答案不能涵盖绝大多数题目（如，只有选择题答案，没有简答题答案），不能算作「答案」
  # 如果题目显著不全，答案也显著不全，这样的文件不应当被收录
  content:
    - 原题

资料

# yaml-language-server: $schema=https://byrdocs.org/schema/doc.yaml

# 文件的 MD5 值
id: 3d6fa4f7305fb91e9c014e468037310c

# 通过 byrdocs-cli 上传文件后得到的 URL
url: https://byrdocs.org/files/3d6fa4f7305fb91e9c014e468037310c.pdf

# 必须是 book/test/doc 三者之一。
# 一旦确定下来，后续的内容必须按照以下格式填写
type: doc

data:
  # 请自行总结一个合适的 title
  title: 工程制图习题解答

   # 原则上只能是 pdf 或 zip 格式
  filetype: pdf

  # 资料的 course 字段不可以留空，需填写为数组
  course:
    - type: 本科 # 只能填写为「本科」或「研究生」，如未知请省略此字段

      # 对应课程的全称，必填
      # 课程名称不应省略字母和括号中的内容，比如「高等数学A（上）」
      name: 工程图学

  # 不可以留空。只能填写「思维导图」「题库」「答案」「知识点」「课件」中的一个或多个
  # 「思维导图」顾名思义
  # 「题库」是指不能归入 book/test 两类中的题库、题集，比如「军事理论题库」「线代绿书2018版」（一个非正式出版的线代题集）
  # 「答案」包括课后习题答案、作业答案、题集答案等。如果它是一个有答案的题库，那么它同时属于「题库」和「答案」
  # 「知识点」指的是各种辅助学习资料或考试复习资料
  # 「课件」包括讲义、（非正式出版的）辅导书、教学手册等与教学息息相关的资料
  content:
    - 题库
    - 答案

文件去重与比较

狭义上的去重就是按 md5sum 来去重，在通过 byrdocs-cli 上传时，相同的文件无法上传。

真正麻烦的在于广义上的去重：同一本书有若干不同的PDF，每个文件的质量都不同；同样是一份试题，有一版只有原题，有一版既有原题又有答案；同样的两份资料，领域相同，但内容又各有异同，只有部分重复……

这些情况实在太复杂，这里只列举一些常见的情况：

书籍的重复问题

在两本书均没有质量问题（比如缺页漏页，或者很糟糕的清晰度）的前提下，我们有以下取舍指标：

  • 若某本书的清晰度高于另一本，那么我们更倾向于选择前者。（这里也需要澄清一个误区，PDF的大小与它的清晰度没有必然关联）
  • 若某本书有封面而另一本书没有，那么我们更倾向于选择前者（可以减少自行添加封面的麻烦）。
  • 若某本书有完善的书签（bookmark）而另一本书没有，那么我们更倾向于选择前者。

试题的重复问题

若二者没有内容上的冲突，最多只有包含关系，那么当然以保留全部内容为佳。

  • 若一份是原题，一份是答案，虽然不重复，也建议将其合并成同一个文件，这样方便用户一次性下载原题和答案。
  • 若其中一份仅有原题，而另一份既有原题又有答案，那么最好把两者合并，原题在前，答案在后。（因为很多用户可能希望先做一遍再对答案）
  • 若其中一份仅有答案，而另一份既有原题又有答案，那么前者无需保留，直接删除即可。

还有一些情况是：试题所指示的年份和科目都完全相同，但是内容基本不一致。这种重复在某些情形下是合理的——

  • 正常考和补考的题目不相同；
  • 不同学院的考卷不相同；
  • 为避免作弊，使用了多份考卷进行考试（貌似只有疫情时期存在过这种情况）；

总之，试题的去重需要考虑的东西比较多，恐怕不能给出一个确定的标准。

资料的重复问题

便宜行事

文件封面

为了方便用户查找文件，BYR Docs 为每个PDF文件都制作了一份封面。这样一来，读者找书时，只需看一眼封面图就可以从众多同名书籍中找到自己想要的那本。

简而言之，我们提取封面的规则是：提取PDF文件的第一页，并通过一些必要的处理，将其转换成符合要求的JPG和WEBP文件。这一系列操作将在文件上传之后由服务器完成，所以你无需担心。

但是有一个问题：有些电子书没有封面页！

这时你需要上网找到这本电子书对应的封面页，并将其添加到这本书的第一页。

如果你使用 Linux 或 MacOS，可以通过 BYR Docs 的脚本来进行添加封面的操作。

再次提醒，BYR Docs 不接受缺少封面的文件。

Clone this wiki locally