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

[William Blevins]

On Sun, Jan 3, 2016 at 10:13 PM, Bill Deegan <bill at baddogconsulting.com>
wrote:

> 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.
>

Yes, I think this would be useful. I have also thought about need a section
in the introduction that describes key SCons constructs and/or paradigms. I
find that the SCons mailing list gets a lot of questions that I would
consider to be about basic architecture. This might help with that,


>
>
> -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
>>
>
>
> _______________________________________________
> 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/3aa5fccf/attachment.html>