Skip to content

Remove "below" from user guide#4859

Open
Prabhu-LANL wants to merge 8 commits into
SCons:masterfrom
Prabhu-LANL:Remove-below-from-User-Guide
Open

Remove "below" from user guide#4859
Prabhu-LANL wants to merge 8 commits into
SCons:masterfrom
Prabhu-LANL:Remove-below-from-User-Guide

Conversation

@Prabhu-LANL
Copy link
Copy Markdown
Contributor

@Prabhu-LANL Prabhu-LANL commented May 28, 2026

When using the multiple pages user guide, the word "below" is used incorrectly in multiple places. It is referencing material that comes later, but cannot be found "below."

There are several places where the word "below" is used just after a link. Those instances are not necessarily needed either, but when the material was in fact "below" I left the word there.

Contributor Checklist:

  • I have created a new test or updated the unit tests to cover the new/changed functionality.
  • I have updated CHANGES.txt and RELEASE.txt (and read the README.rst).
  • I have updated the appropriate documentation

@mwichmann
Copy link
Copy Markdown
Collaborator

This is a kind of interesting one. We have directional references ("above", "below") as navigation hints because some output formats don't get hyperlinks (text and pdf). Agree they don't work out well in the chunked html format - no really good answer. It's a little reminiscent of the problems cause by the four "generated" sections - builders, tools, construction variables and environment methods - which appear in both the reference manual and the use guide, meaning links from those sections to other sections aren't ideal; they work fine in the reference manual but not in the user guide which doesn't have those other reference manual sections inline, so we use awkard textual references ("see the section called XXX") instead of actual hyperlinks.

I'm inclined to feel that the html formats are so much the predominantly used form that it's okay to just lean on hyperlinks and not try to give textual navigation hints in this case (that is, accept this PR), but will leave the decision on that to @bdbaddog to make.

@bdbaddog
Copy link
Copy Markdown
Contributor

Hmm. ideally (but maybe not really importantly) we'd render "below" only in text format where we don't have hyperlinks.

That said, even if you type "man scons", you can search within that output on modern systems.

Downsides:

  1. Any format with hyperlinks = None
  2. Format without hyperlinks = slight inconvenience and probably not really affect many user.

I think I'm ok with this, but let me ponder a day or so.

@mwichmann
Copy link
Copy Markdown
Collaborator

Hmm. ideally (but maybe not really importantly) we'd render "below" only in text format where we don't have hyperlinks.

That said, even if you type "man scons", you can search within that output on modern systems.

Downsides:

1. Any format with hyperlinks = None

2. Format without hyperlinks = slight inconvenience and probably not really affect many user.

I think I'm ok with this, but let me ponder a day or so.

Just to close the loop, this is about the user guide which has the "Multi Page HTML" option that the manpage doesn't.

@mwichmann mwichmann changed the title Remove below from user guide Remove "below" from user guide Jun 1, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants