Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Dead link in "data-files:" documentation. #7469

Closed
danidiaz opened this issue Jun 29, 2021 · 5 comments · Fixed by #7586
Closed

Dead link in "data-files:" documentation. #7469

danidiaz opened this issue Jun 29, 2021 · 5 comments · Fixed by #7586
Assignees
@andreasabel
Labels
documentation

Comments

@danidiaz
Copy link
Collaborator

The Accessing data files from package code section of the user guide has a dead link to a non-existent section about "prefix independence":

(see prefix independence)

Googling for it, it seems that section formerly belonged to the GHC User Guide—but it isn't present in the current GHC User Guide.
@andreasabel
Copy link
Member

No, the section "prefix independence" is still present in the Cabal docs: https://github.com/haskell/cabal/blob/7d4ce4787cb3d4fe30d08953ad64d19456a77690/doc/setup-commands.rst#prefix-independence

Only the link broke, maybe by 3752c3e which moved the text from installing-packages.rst to setup-commands.rst
bb16112 fixed some links, but must have missed this one.

andreasabel added a commit to andreasabel/cabal that referenced this issue Aug 28, 2021
@andreasabel
Fix haskell#7469: broken link to "prefix independence" in docs
b412e12
@andreasabel andreasabel mentioned this issue Aug 28, 2021
Merged
3 tasks
@andreasabel
Copy link
Member

Fix in PR #7586.

@mergify mergify bot closed this as completed in #7586 Aug 29, 2021
mergify bot pushed a commit that referenced this issue Aug 29, 2021
@andreasabel
Fix #7469: broken link to "prefix independence" in docs (#7586)
b921271
mergify bot pushed a commit that referenced this issue Aug 29, 2021
@andreasabel
Fix #7469: broken link to "prefix independence" in docs (#7586)
c0067e3 
(cherry picked from commit b921271)
@andreasabel andreasabel self-assigned this Aug 29, 2021
@andreasabel
Copy link
Member

andreasabel commented Aug 29, 2021 •
edited
Loading

I took away the "wierd bug award", as broken references are easy to creep in.
Broken refs can maybe be avoided by passing -n ("nitpick") to sphinx-build, see https://www.sphinx-doc.org/en/master/man/sphinx-build.html#cmdoption-sphinx-build-n. E.g., when I run with -n, this sleeping bug surfaces:

doc/cabal-project.rst:644: WARNING: 'envvar' reference target not found: PATH

I'll prepare a new PR that fixes this.

P.S.: For the Agda user-manual, we treat warnings as errors (-W --keep-going) and rebuild from scratch (-E, annoys me): https://github.com/agda/agda/blob/3a4df95062c9484953b0505e73f74453c09fa714/doc/user-manual/Makefile#L5

mergify bot added a commit that referenced this issue Aug 30, 2021
@mergify @andreasabel
Fix #7469: broken link to "prefix independence" in docs (#7586) (#7595)
5b303f5 
(cherry picked from commit b921271)

Co-authored-by: Andreas Abel <[email protected]>
andreasabel added a commit to andreasabel/cabal that referenced this issue Aug 31, 2021
@andreasabel
Re haskell#7469: doc: unified references to PATH environment variable
f931e4f 
Found four variants, picked the first:

  1. ``PATH``
  2. `PATH`
  3. ``$PATH``
  4. :envvar:`PATH`

The last (4) produced an error with sphinx:
```
doc/cabal-project.rst:644: WARNING: 'envvar' reference target not found: PATH
```
andreasabel added a commit to andreasabel/cabal that referenced this issue Aug 31, 2021
@andreasabel
Re haskell#7469: doc: typo found by deciphering sphinx warning
ac9baa1 
Wasn't immediate to get to the error from the warning
```
doc/cabal-project.rst:2: WARNING: Duplicate ID: "cfg-field-type".
```
(wrong line number, "cfg-field-type" is not greppable).
andreasabel added a commit to andreasabel/cabal that referenced this issue Aug 31, 2021
@andreasabel
Re haskell#7469: sphinx-build with flag -n (nitpick)
2720a89
andreasabel added a commit to andreasabel/cabal that referenced this issue Aug 31, 2021
@andreasabel
Re haskell#7469: sphinx-build with flag -W -E --keep-going
d690d9b 
Strict regime: turn warnings to errors (-W), rebuild from scratch (-E).
@andreasabel andreasabel mentioned this issue Aug 31, 2021
Merged
@andreasabel
Copy link
Member

I'll prepare a new PR that fixes this.

PR #7603.

@Mikolaj
Copy link
Member

Mikolaj commented Aug 31, 2021

Good call, thank you. Broken links are indeed not that weird, as opposed to linking away to an imaginary section.

Mikolaj pushed a commit that referenced this issue Sep 2, 2021
@andreasabel @Mikolaj
Re #7469: doc: unified references to PATH environment variable
b31bc0b 
Found four variants, picked the first:

  1. ``PATH``
  2. `PATH`
  3. ``$PATH``
  4. :envvar:`PATH`

The last (4) produced an error with sphinx:
```
doc/cabal-project.rst:644: WARNING: 'envvar' reference target not found: PATH
```
Mikolaj pushed a commit that referenced this issue Sep 2, 2021
@andreasabel @Mikolaj
Re #7469: doc: typo found by deciphering sphinx warning
0cee02f 
Wasn't immediate to get to the error from the warning
```
doc/cabal-project.rst:2: WARNING: Duplicate ID: "cfg-field-type".
```
(wrong line number, "cfg-field-type" is not greppable).
Mikolaj pushed a commit that referenced this issue Sep 2, 2021
@andreasabel @Mikolaj
Re #7469: sphinx-build with flag -n (nitpick)
9f8b6d1
Mikolaj pushed a commit that referenced this issue Sep 2, 2021
@andreasabel @Mikolaj
Re #7469: sphinx-build with flag -W -E --keep-going
067bb43 
Strict regime: turn warnings to errors (-W), rebuild from scratch (-E).
mergify bot pushed a commit that referenced this issue Sep 2, 2021
@andreasabel
Re #7469: doc: unified references to PATH environment variable
892e6e6 
Found four variants, picked the first:

  1. ``PATH``
  2. `PATH`
  3. ``$PATH``
  4. :envvar:`PATH`

The last (4) produced an error with sphinx:
```
doc/cabal-project.rst:644: WARNING: 'envvar' reference target not found: PATH
```

(cherry picked from commit b31bc0b)
mergify bot pushed a commit that referenced this issue Sep 2, 2021
@andreasabel
Re #7469: doc: typo found by deciphering sphinx warning
3a397d5 
Wasn't immediate to get to the error from the warning
```
doc/cabal-project.rst:2: WARNING: Duplicate ID: "cfg-field-type".
```
(wrong line number, "cfg-field-type" is not greppable).

(cherry picked from commit 0cee02f)
mergify bot pushed a commit that referenced this issue Sep 2, 2021
@andreasabel
Re #7469: sphinx-build with flag -n (nitpick)
64cd115 
(cherry picked from commit 9f8b6d1)
mergify bot pushed a commit that referenced this issue Sep 2, 2021
@andreasabel
Re #7469: sphinx-build with flag -W -E --keep-going
c182c8d 
Strict regime: turn warnings to errors (-W), rebuild from scratch (-E).

(cherry picked from commit 067bb43)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@andreasabel andreasabel

Labels
documentation
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Fix #7469: broken link to "prefix independence" in docs andreasabel/cabal
3 participants
@Mikolaj @danidiaz @andreasabel