Fix external broken links in documentation broken

[jasonpott]

What would you like to do?

Report an issue on quarto.org

Description

The hyperlink to hypothesis documentation is broken.
https://quarto.org/docs/reference/projects/websites.html#hypothesis

[cderv]

Thanks for the report.

Hypothesis changed their website it seems. This is now at https://h.readthedocs.io/projects/client/en/latest/publishers/config.html

[mcanouil]

See on a related subject (internal links):

• refactor: harmonise and fix broken internal links quarto-web#1031

[mcanouil]

Getting links from: https://quarto.org/docs/dashboards/examples/index.html
https://github.com/jjallaire/ojs-penguins-dashboard/blob/main/penguins.qmd
-> Very likely a "private repository" => Awaiting feedback about visibility change of the repository.

Getting links from: https://quarto.org/docs/reference/formats/epub.html
https://www.w3.org/publishing/epub3/epub-packages.html#bib-typesregistry
-> outdated with Epub 3.3 => No obvious replacement found.

Getting links from: https://quarto.org/docs/reference/formats/icml.html
https://wwwimages.adobe.com/content/dam/acom/en/devnet/indesign/sdk/cs6/idml/idml-specification.pdf
-> very hidden link initially found on a forum => No replacement found.

For the last two, I have no idea on how or with what to fix the links.

[cderv]

Getting links from: https://quarto.org/docs/reference/formats/epub.html
https://www.w3.org/publishing/epub3/epub-packages.html#bib-typesregistry
-> outdated with Epub 3.3 => No obvious replacement found.

The new link is this one: https://www.w3.org/publishing/epub32/epub-packages.html#bib-typesregistry
This points to Registry link : https://idpf.github.io/epub-registries/types/ that we could also use

However, the question to update the description could be dealt with. I don't know if we (through Pandoc) are producing Epub 3.3 compatible output (or still 3.2). Equivalent for 3.3 is https://www.w3.org/TR/epub/#sec-opf-dctype and it says

The dc:type element [dcterms] is used to indicate that the EPUB publication is of a specialized type (e.g., annotations or a dictionary packaged in EPUB format).

EPUB creators MAY use any text string as a value.
NOTE
The former IDPF EPUB 3 Working Group maintained a non-normative registry of specialized EPUB publication types for use with this element. This Working Group no longer maintains the registry and does not anticipate developing new specialized publication types.

So if 3.3 is what we output, we could just adapt the description to this new one (but there is probably others - so it would be its own update issue I guess).

For now, you can probably put the new link: https://www.w3.org/publishing/epub32/epub-packages.html#bib-typesregistry

[cderv]

Getting links from: https://quarto.org/docs/reference/formats/icml.html
https://wwwimages.adobe.com/content/dam/acom/en/devnet/indesign/sdk/cs6/idml/idml-specification.pdf
-> very hidden link initially found on a forum => No replacement found.

Those pages can be created based on Pandoc information. So usually, you can try find information there too. So for replacement see

• InDesign ICML: Dead link jgm/pandoc#9563 (jgm/pandoc@7e4569d)

New link would be https://manualzz.com/doc/9627253/adobe-indesign-cs6-idml-cookbook but honestly it is not the best - probably legit, but not official. It has been removed from the web I think.

This comes from https://community.adobe.com/t5/indesign-discussions/where-is-the-idml-specification/m-p/13172633

We could also not provide link - I don't think this will be quite often read.

[mcanouil]

Regarding Epub, that's the "outdated" link I've found but don't know if it makes sense as you pointed out (#9005 (comment)).
Anyhow, the link is in Quarto CLI side: https://github.com/quarto-dev/quarto-web/blob/main/docs/reference/formats/epub.json#L120

For Adobe InDesign, there are no official or reliable source, the issue of the link being broken will be a continuous concern while I don't see what the link brings in Quarto.
I would be in favour of removing it.

Possible links:

• https://helpx.adobe.com/indesign/automation.html
• https://www.idml.dev/en.html

[cderv]

• EPUB:

This is the current equivalent link: https://www.w3.org/publishing/epub32/epub-packages.html#bib-typesregistry (epub3 replaced by epub32). This would mean no other change for now - just fixing the broken link.

• ICML

the issue of the link being broken will be a continuous concern

We could do like Pandoc and use the other one, or just remove the link. The latter is probably fine.

Possible links:

Is IDML equivalent to ICML ?

[mcanouil]

I believe ICML is a typo (made several times by the authors of Pandoc and issues) as IDML stands for InDesign Markup Language (file extension is .idml amongst others).

ICML is the file type/extension for InCopy (Markup Language).

Content can be migrated between InDesign and InCopy. Here it is very ambiguous on Pandoc side.

[cderv]

ICML is the file type/extension for InCopy (Markup Language).

Oh so it makes sense that --to icml is used but they should talk about InDesign IDML. Did not know that.

Anyhow, no need to spend more time on that. Just remove the link as you are suggesting.

Thanks a lot for the explanation !

[mcanouil]

• fix: broken external links quarto-web#1053
• fix: epub reference link #9148

The only remaining issue is:

Getting links from: https://quarto.org/docs/dashboards/examples/index.html
https://github.com/jjallaire/ojs-penguins-dashboard/blob/main/penguins.qmd
-> Very likely a "private repository" => Awaiting feedback about visibility change of the repository.