[Scons-users] What is the difference between Variables and Options

[Stefan Seefeld]

On 03.01.2016 10:43, William Blevins wrote:
> Stefan,
>
> Although I understand what you are saying, the User's Guide is pretty
> long and dense already, I cannot imagine what it would look like if
> you tried to make every artifact completely unambiguous with natural
> language which is already ambiguous. If you find specific artifacts
> that you can word better, please feel free to make a pull request?

Fair enough. To be entirely clear, I didn't mean to suggest to add
(substantially) to the User's Guide. Rather, I'm thinking of
cross-references to other documents such as the API reference (for a
more in-depth discussion of specific functions etc.), and a (to be
written) glossary (for a brief conceptual introduction of terminology).

>
> Also you mentioned wanted a search feature. There are versions of the
> User's Guide which have the entire document as 1 HTML page; thus, you
> can search however you like with any browser, etc.

Right, but I find that a bit limited. My use-case is the same as above:
I regularly run into a chunk of documentation / example that looks
useful but not quite complete, or unambiguous, and there is no way to
"narrow in". Let me illustrate what I mean:

Within http://scons.org/doc/production/HTML/scons-user.html I'm
searching for "action", which takes me to section "12.7 Executing an
action immediately...", which starts with "We've been showing you how to
use |Action| factories in the |Command| function." which suggests that
the "Action" term is either well known or introduced before (it's even
typographically highlighted), while it really is the first occurrence of
"action" in that entire document. So how can I learn more about the
meaning of "action" ? Ideally the "Action" word in that first sentence
in this section would be a link to a glossary that explains what an
Action is (in the context of SCons), and some means (such as a search
widget  to search for other occurrences of Actions, in the User's Guide,
in the API reference, and anywhere else.

Does that clarify what I have in mind ?

Anyhow, I'm not proposing to rewrite the SCons documentation from
scratch. But perhaps there are things that could be done incrementally
to improve things...

Thanks,
        Stefan


-- 

      ...ich hab' noch einen Koffer in Berlin...