From fa42ef504b284b282b6ec3273ef2bb9cfdac57ed Mon Sep 17 00:00:00 2001 From: Michael Goerz Date: Thu, 2 Nov 2023 07:06:32 -0400 Subject: [PATCH] Add a fallback for `Pages` to behave as in pre-1.3 --- NEWS.md | 21 +++++++++++++++++++ Project.toml | 2 +- src/expand_bibliography.jl | 20 ++++++++++++++---- test/test_bibliography_block_pages.jl | 6 ++++-- .../src/part3/section2/invalidpages.md | 4 ++-- 5 files changed, 44 insertions(+), 9 deletions(-) diff --git a/NEWS.md b/NEWS.md index f28a0f2..4f33ed0 100644 --- a/NEWS.md +++ b/NEWS.md @@ -3,6 +3,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [Unreleased][] + +### Fixed + +* Added a fallback for the `Pages` attribute in a `@bibliography` block to behave as in pre-`1.3.0`: If `Pages` references a file with a path relative to the `docs/src` directory (which was the unintentional requirement pre-`1.3.0`), this now works again, but shows a warning that the name should be updated to be relative to the folder containing the file that contains the `@bibliography` block. + + This fixes the `v1.3.0` release arguably having been "breaking" [[#59][]] in that anybody who was using `Pages` pre-1.3.0 would have had to use paths relative to `docs/src`, even though that was a workaround for a known bug [[#22][]]. Note that whenever `Pages` references the current file, `@__FILE__` should be used. + ## [Version 1.3.0][1.3.0] - 2023-11-01 @@ -42,6 +50,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 * Any `@bibliography` block is now internally expanded into an internal `BibliographyNode` instead of a raw HTML node. This `BibliographyNode` can then be translated into the desired output format by `Documenter.HTMLWriter` or `Documenter.LaTeXWriter`. This is how support for bibliographies with `format=Documenter.LaTeX()` can be achieved. * The routine `format_bibliography_reference` must now return a markdown string instead of an HTML string. +**Upgrade guidelines**: + +For anyone who was using custom styles, which rely on the [Internals](https://juliadocs.org/DocumenterCitations.jl/stable/internals/) of `DocumenterCitations`, this release will almost certainly break the customization. See the above list of internal changes. + +There were some subtle changes in how DOI and URL fields are linked in the rendered documentation, which may require adjustments. In particular, in version `1.3.0`, non-`@article` entries that do not have both a `title` and a `booktitle` can only have a DOI *or* a URL, but not both. This most likely occurs for `@book` entries. For `@book` entries that have both a DOI and a URL, the URL should be placed in the `note` field (using `\url`/`\href`, as appropriate). + +There were several bugs and limitations in version `1.2.x` for which some existing documentations may have been using workarounds. These workarounds may cause some breakage in the new version `1.3.0`. In particular: + +* The `Pages` attribute in a `@bibliography` block in version `1.2.x` required any names to be relative to the `docs/src` directory [[#22][]]. This was both unintentional and undocumented. These names must now be updated to be relative to to the folder containing the file which contains the `@bibliography` block. This is consistent with how `Pages` is used, e.g., in `@contents` or `@index` blocks. For the common usage where `Pages` was referring to the current file, `@__FILE__` should be used. + +* Pre-`1.3.0`, strings in entries in the `.bib` file were extremely limited. There was no official support for any kind of `tex` macros: only plain-text (unicode) was fully supported. As a workaround, some users exploited an (undocumented/buggy) implementation detail that would cause html or markdown strings inside the `.bib` file to "work", e.g. for adding links in a `note` field. These workarounds may break in `v1.3.0`. While unicode is still very much supported (`รถ` over `\"{o}`), `.bib` files should otherwise be written to be fully compatible with `bibtex`. For links in particular, the LaTeX `\href` macro should be used. Any `tex` commands that are not supported (`Error: Unsupported command`) should be reported. Some `tex` characters (`$%@{}&`) that may have worked directly pre-`1.3.0` will have to be escaped in version `1.3.0`. + ## [Version 1.2.1][1.2.1] - 2023-09-22 @@ -119,6 +139,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 [1.2.0]: https://github.com/JuliaDocs/DocumenterCitations.jl/compare/v1.1.0...v1.2.0 [1.1.0]: https://github.com/JuliaDocs/DocumenterCitations.jl/compare/v1.0.0...v1.1.0 [1.0.0]: https://github.com/JuliaDocs/DocumenterCitations.jl/compare/v0.2.12...v1.0.0 +[#59]: https://github.com/JuliaDocs/DocumenterCitations.jl/issues/59 [#56]: https://github.com/JuliaDocs/DocumenterCitations.jl/pull/56 [#53]: https://github.com/JuliaDocs/DocumenterCitations.jl/issues/53 [#42]: https://github.com/JuliaDocs/DocumenterCitations.jl/pull/42 diff --git a/Project.toml b/Project.toml index 8d83945..c44c9bd 100644 --- a/Project.toml +++ b/Project.toml @@ -1,7 +1,7 @@ name = "DocumenterCitations" uuid = "daee34ce-89f3-4625-b898-19384cb65244" authors = ["Michael Goerz "] -version = "1.3.0" +version = "1.3.1-dev" [deps] AbstractTrees = "1520ce14-60c1-5f80-bbc7-55ef81b5835c" diff --git a/src/expand_bibliography.jl b/src/expand_bibliography.jl index 75a27b4..c7eb77b 100644 --- a/src/expand_bibliography.jl +++ b/src/expand_bibliography.jl @@ -1,3 +1,5 @@ +_ALLOW_PRE_13_FALLBACK = true + """Pipeline step to expand all `@bibliography` blocks. Runs after [`CollectCitations`](@ref) but before [`ExpandCitations`](@ref). @@ -273,12 +275,22 @@ function expand_bibliography(node::MarkdownAST.Node, meta, page, doc) expected_file = normpath(doc.user.source, page_folder, name) if isfile(expected_file) @error "Invalid $(repr(name)) in Pages attribute of @bibliography block on page $(page.source): File $(repr(expected_file)) exists but no references were collected." + push!(doc.internal.errors, :bibliography_block) else - # Files that don't contain any citations don't show up in - # `page_citations`. - @error "Invalid $(repr(name)) in Pages attribute of @bibliography block on page $(page.source): No such file $(repr(expected_file))." + # try falling back to pre-1.3 behavior + exists_in_src = isfile(joinpath(doc.user.source, name)) + valid_pre_13 = exists_in_src && haskey(page_citations, name) + if _ALLOW_PRE_13_FALLBACK && valid_pre_13 + @warn "The entry $(repr(name)) in the Pages attribute of the @bibliography block on page $(page.source) appears to be relative to $(repr(doc.user.source)). Starting with DocumenterCitations 1.3, names in `Pages` must be relative to the folder containing the file which contains the `@bibliography` block." + @debug "Add keys cited in $(abspath(normpath(doc.user.source, name))) to keys_to_show (pre-1.3 fallback)" + push!(keys_in_pages, page_citations[name]...) + else + # Files that don't contain any citations don't show up in + # `page_citations`. + @error "Invalid $(repr(name)) in Pages attribute of @bibliography block on page $(page.source): No such file $(repr(expected_file))." + push!(doc.internal.errors, :bibliography_block) + end end - push!(doc.internal.errors, :bibliography_block) continue end end diff --git a/test/test_bibliography_block_pages.jl b/test/test_bibliography_block_pages.jl index 1914a64..e5c4db2 100644 --- a/test/test_bibliography_block_pages.jl +++ b/test/test_bibliography_block_pages.jl @@ -47,7 +47,8 @@ end @test success #! format: off - @test contains(output, prx("Error: Invalid \"index.md\" in Pages attribute of @bibliography block on page src/part3/section2/invalidpages.md: No such file \"src/part3/section2/index.md\".")) + @test_broken contains(output, prx("Error: Invalid \"index.md\" in Pages attribute of @bibliography block on page src/part3/section2/invalidpages.md: No such file \"src/part3/section2/index.md\".")) + @test contains(output, prx("Warning: The entry \"index.md\" in the Pages attribute of the @bibliography block on page src/part3/section2/invalidpages.md appears to be relative to \"src\".")) @test contains(output, prx("Error: Invalid \"p3_s1_page.md\" in Pages attribute of @bibliography block on page src/part3/section2/invalidpages.md: No such file \"src/part3/section2/p3_s1_page.md\".")) @test contains(output, prx("Error: Invalid \"noexist.md\" in Pages attribute of @bibliography block on page src/part3/section2/invalidpages.md: No such file \"src/part3/section2/noexist.md\".")) @test contains(output, "Warning: No cited keys remaining after filtering to Pages") @@ -174,7 +175,8 @@ end @test !success #! format: off - @test contains(output, prx("Error: Invalid \"index.md\" in Pages attribute of @bibliography block on page src/part3/section2/invalidpages.md: No such file \"src/part3/section2/index.md\".")) + @test_broken contains(output, prx("Error: Invalid \"index.md\" in Pages attribute of @bibliography block on page src/part3/section2/invalidpages.md: No such file \"src/part3/section2/index.md\".")) + @test contains(output, prx("Warning: The entry \"index.md\" in the Pages attribute of the @bibliography block on page src/part3/section2/invalidpages.md appears to be relative to \"src\".")) @test contains(output, prx("Error: Invalid \"p3_s1_page.md\" in Pages attribute of @bibliography block on page src/part3/section2/invalidpages.md: No such file \"src/part3/section2/p3_s1_page.md\".")) @test contains(output, prx("Error: Invalid \"noexist.md\" in Pages attribute of @bibliography block on page src/part3/section2/invalidpages.md: No such file \"src/part3/section2/noexist.md\".")) @test contains(output, "Warning: No cited keys remaining after filtering to Pages") diff --git a/test/test_bibliography_block_pages/src/part3/section2/invalidpages.md b/test/test_bibliography_block_pages/src/part3/section2/invalidpages.md index 8ff61bd..9196081 100644 --- a/test/test_bibliography_block_pages/src/part3/section2/invalidpages.md +++ b/test/test_bibliography_block_pages/src/part3/section2/invalidpages.md @@ -2,12 +2,12 @@ ## References from Nonexisting Pages -Nothing should render here +Nothing should render here (except for the fallback introduced in version 1.3.1) ```@bibliography Canonical = false Pages = [ - "index.md", + "index.md", # not valid in 1.3, valid in 1.3.1 (fallback) "p3_s1_page.md", "noexist.md", ]