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

[Bill Deegan]

Stefan,

I think of a user guide as a low depth document and a reference guide
and/or manpage as the depth document.
So when I'm not sure about the details in the user guide I look to a
reference guide or manpage.
This is a pretty typical pattern.

We've not heard much (if any) other requests for such cross referencing.
If you'd like to create a pull request to demonstrate more fully what
you're suggesting, please feel free.

It does sound like perhaps there should be a section in the user guide with
more foundational information, what's a builder, what's an action, whats a
scanner,etc.
Or perhaps you can file a doc bug for the specific example above and we'll
see what we can do.

-Bill


On Sun, Jan 3, 2016 at 9:23 AM, Stefan Seefeld <stefan at seefeld.name> wrote:

> 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...
>
> _______________________________________________
> Scons-users mailing list
> Scons-users at scons.org
> https://pairlist4.pair.net/mailman/listinfo/scons-users
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://pairlist4.pair.net/pipermail/scons-users/attachments/20160103/71d24b1f/attachment.html>