Remove "below" from user guide#4859
Conversation
…below" but at a different link.
…below" but at a different link.
…below" but at a different link.
…below" but at a different link.
…below" but at a different link.
…below" but at a different link.
…below" but at a different link.
|
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. |
|
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:
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. |
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:
CHANGES.txtandRELEASE.txt(and read theREADME.rst).