Bug 262661

Summary:	FreeBSD documentation: long HTML: references to items within the same document should not switch away (to short/split HTML)
Product:	Documentation	Reporter:	Graham Perrin <grahamperrin>
Component:	Books & Articles	Assignee:	Sergio Carlavilla Delgado <carlavilla>
Status:	Closed FIXED
Severity:	Affects Some People	CC:	carlavilla, pauamma, sec.research.2005
Priority:	---
Version:	Latest
Hardware:	Any
OS:	Any
URL:	https://github.com/freebsd/freebsd-doc/blob/main/documentation/content/en/books/handbook/book.adoc
See Also:	https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=265274
Bug Depends on:
Bug Blocks:	263315

Description Graham Perrin freebsd_committer

2022-03-19 10:02:32 UTC

1. <https://docs.freebsd.org/en/books/handbook/book/#_footnotedef_2>
2. click Home

Expected: 

3. <https://docs.freebsd.org/en/books/handbook/book/#top> (long HTML)

Actual result: 

3. <https://docs.freebsd.org/en/books/handbook/> (short HTML)

Comment 1 Pau Amma 2022-03-19 22:45:02 UTC

(In reply to Graham Perrin from comment #0)
To clarify: are you asking for "Home" in the single-HTML version to send you to the top of that version, not the split-HTML version?

(I agree that expectation sounds reasonable.)

Comment 2 Graham Perrin freebsd_committer

2022-03-21 08:37:30 UTC

(In reply to PauAmma from comment #1)

Correct, for the Home button.

Comment 3 Graham Perrin freebsd_committer

2022-03-21 09:05:13 UTC

Similarly, under <https://docs.freebsd.org/en/books/handbook/book/#wine-synopsis>: 

> …
> 
> * Understand the basics of UNIX® and FreeBSD. 
> * …

The link within that sentence leads away from the non-split version, to the split version of the Handbook, which is a drag (reloading, orientation etc.) when the long version is preferred. 

----

I imagined some kind of automation, for links to not behave in this way. Did I imagine wrong? Is it necessary to maintain the two versions of things such as the Handbook, in isolation, in parallel? 

Thanks

Comment 4 Pau Amma 2022-03-25 06:54:22 UTC

*** Bug 262766 has been marked as a duplicate of this bug. ***

Comment 5 Pau Amma 2022-05-23 10:30:18 UTC

Someone mentioned this bug as a serious navigation pain point in their survey answers.

Comment 6 Sergio Carlavilla Delgado freebsd_committer

2022-11-06 18:07:10 UTC

I'll take this

Comment 7 commit-hook freebsd_committer

2022-12-07 18:23:28 UTC

A commit in branch main references this bug:

URL: https://cgit.FreeBSD.org/doc/commit/?id=22d9c0d697157330d9d6298eaf0ee27659fe30d0

commit 22d9c0d697157330d9d6298eaf0ee27659fe30d0
Author:     Sergio Carlavilla Delgado <carlavilla@FreeBSD.org>
AuthorDate: 2022-12-07 18:22:10 +0000
Commit:     Sergio Carlavilla Delgado <carlavilla@FreeBSD.org>
CommitDate: 2022-12-07 18:22:10 +0000

    Fix link references in single book

    PR:             262661
    Submitted by:   grahamperrin@

 shared/lib/InterDocumentReferencesMacro/extension.rb | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

Comment 8 Sergio Carlavilla Delgado freebsd_committer

2022-12-07 18:23:56 UTC

Fixed.

Comment 9 Graham Perrin freebsd_committer

2022-12-08 02:40:38 UTC

Thanks!