Broken links in the pages section of the documentation

[milmazz]

Elixir and Erlang/OTP versions

main

Operating system

N/A

Current behavior

While I was reporting elixir-lang/ex_doc#1851 I noticed that the generated EPUB file for Elixir has some broken links.

After analyzing the EPUB file with epubcheck and using jq to trim the output:

$ jq '.messages[] | select(.severity=="ERROR") | {id: .ID, message: .message, locations: .locations | map({path, line, column})} | select(.message | endswith("could not be found in the EPUB."))'  elixir_docs.json

We have the following result:

{
  "id": "RSC-007",
  "message": "Referenced resource \"OEBPS/Enumerable.List.xhtml\" could not be found in the EPUB.",
  "locations": [
    {
      "path": "OEBPS/Protocol.xhtml",
      "line": 158,
      "column": 33
    }
  ]
}
{
  "id": "RSC-007",
  "message": "Referenced resource \"OEBPS/Inspect.MapSet.xhtml\" could not be found in the EPUB.",
  "locations": [
    {
      "path": "OEBPS/Inspect.xhtml",
      "line": 109,
      "column": 32
    }
  ]
}
{
  "id": "RSC-007",
  "message": "Referenced resource \"OEBPS/Kernel.html\" could not be found in the EPUB.",
  "locations": [
    {
      "path": "OEBPS/patterns-and-guards.xhtml",
      "line": 157,
      "column": 74
    }
  ]
}
{
  "id": "RSC-007",
  "message": "Referenced resource \"OEBPS/Module.html\" could not be found in the EPUB.",
  "locations": [
    {
      "path": "OEBPS/typespecs.xhtml",
      "line": 215,
      "column": 100
    }
  ]
}
{
  "id": "RSC-007",
  "message": "Referenced resource \"OEBPS/enum-cheat.html\" could not be found in the EPUB.",
  "locations": [
    {
      "path": "OEBPS/Enum.xhtml",
      "line": 41,
      "column": 27
    },
    {
      "path": "OEBPS/enumerable-and-streams.xhtml",
      "line": 28,
      "column": 620
    }
  ]
}
{
  "id": "RSC-007",
  "message": "Referenced resource \"OEBPS/images/kv-observer.png\" could not be found in the EPUB.",
  "locations": [
    {
      "path": "OEBPS/dynamic-supervisor.xhtml",
      "line": 96,
      "column": 1326
    }
  ]
}
{
  "id": "RSC-007",
  "message": "Referenced resource \"OEBPS/naming-conventions.html\" could not be found in the EPUB.",
  "locations": [
    {
      "path": "OEBPS/design-anti-patterns.xhtml",
      "line": 106,
      "column": 535
    }
  ]
}
{
  "id": "RSC-007",
  "message": "Referenced resource \"OEBPS/quote-and-unquote.html\" could not be found in the EPUB.",
  "locations": [
    {
      "path": "OEBPS/macros.xhtml",
      "line": 35,
      "column": 263
    }
  ]
}
{
  "id": "RSC-007",
  "message": "Referenced resource \"OEBPS/syntax-reference.html\" could not be found in the EPUB.",
  "locations": [
    {
      "path": "OEBPS/unicode-syntax.xhtml",
      "line": 49,
      "column": 3271
    }
  ]
}

Initially I thought it was a problem in the epub formatter from ex_doc, but after inspecting the source files, the extension .html is explicit, so, that also means that when you go for example to https://github.com/elixir-lang/elixir/blob/main/lib/elixir/pages/meta-programming/macros.md and you hit the "previous guide" link you will get a 404.

So, the question is, should we fix those links in the source and then let ex_doc to change the extensions (.html for the html formatter, and .xhtml for the epub formatter)?

Expected behavior

No broken links on GitHub, and the result from ex_doc (HTML and EPUB).

[josevalim]

I have fixed most except the first two, pointing to protocol implementations. Those are ExDoc bugs. I also wonder if we should always add @moduledoc false by default to implementations, removing special logic from ExDoc, and simplifying other parts. I will sync with @wojtekmach.