Re: Tutorial edits comments

From: David Abrahams (dave_at_[hidden])
Date: 2004-12-28 15:20:12

Vladimir Prus wrote:
> On Tuesday 28 December 2004 20:39, David Abrahams wrote:
> 
>> > +<!-- You can't launch into this stuff without describing how to 
> configure -->
>> > +<!-- Boost.Build... unless of course you think it's likely to work 
> with -->
>> > +<!-- no configuration. But even if you do you have to tell people 
> how to -->
>> > +<!-- configure their installation in case it doesn't work. -->
>> > +
>> > 
>> > Sure, the "how to use this document" suggest that whenever the user 
> decides to really try
>> > V2, he look at installation docs. 
>> 
>> There are two problems:
>> 
>> 1. people typically turn directly to a tutorial and expect to be
>> able to follow along.
>> 
>> 2. When I said "configure" I meant not just installation but the
>> neccessary user-config/site-config settings required to find
>> toolsets.
>> 
>> > Do you think a link is in order here, too?
>> 
>> I don't think a link is sufficient.
> 
> Is complete documentation needed then? Won't that duplicate content of the 
> installation section?

All you need is something that says, "Try this quick example: <example>
It will probably work automatically, but if it doesn't, you may need to
configure some toolsets. Refer to <xref to section on setting up a
user-config.jam> in that case."

The xref'd section should tell the user how to find out what toolsets
are supplied by the build system and how to configure them.

>> > <programlisting>
>> > exe hello 
>> > : hello.cpp
>> > : &lt;include&gt;/home/ghost/Work/boost &lt;threading&gt;multi
>> > ;
>> > </programlisting>
>> > 
>> > +<!-- Can those requirements be written as
>> > + "include=/home/ghost/Work/boost threading=multi"? If so, we
>> > + should do everything in the manual, or at the very least in the
>> > + tutorial, that way. If not, why not? -->
>> > 
>> > We can't, because it's not implemented. I sure would like this syntax.
>> 
>> Okay.
> 
> Filed an issue, so that we don't forget.

Thanks!

>> Well, it's illegal in BoostBook apparently, but it's a left curly
>> double quote. I replaced it with the correct Unicode this morning.
> 
> And... why it's better than "quot"?

It looks right in print. Note that when you put in straight quotes in
latex, it will make them curly for you automatically.

>> > + <footnote>
>> > +<para>
>> > +See <xref linkend="bbv2.reference.features.attributes"/>
>> > + augments) the target requirements.
>> > 
>> > Are there unmatched parenthesis?
>> 
>> I don't think so. See above.
> 
> Actually, there <footnote> is placed wrongly -- the "augments...." parts ends 
> up in the footnote. I'll fix this.

Thanks.

> 
>> > +<!-- Shouldn't we be introducing Jamroot here instead of -->
>> > +<!-- project-root.jam? It certainly is simpler. -->
>> > +
>> > 
>> > We definitely should. 
>> 
>> Or we should eliminate the need for Jamroot, which would be simpler still.
> 
> Ok, then this doc edit have to wait for us to decide something on Jamroot 
> issue.

Agreed.

>> > + Of course, the
>> > + path will be interpreted relatively to 
> <filename>util/foo</filename> and will be
>> > + adjusted according to the <command>bjam</command> invocation
>> > + directory. 
>> > + <!-- You need to explain this path adjustment in the first 
> place
>> > + you introduce #include paths, probably with a "Tip"
>> > + element. 
>> > 
>> > Agreed.
> 
> BTW, "tip" or "note"? IIRC, on boost-doc we decided that "note" is 
> supplemental information, which can be skipped, and "tip" is information user 
> better read.

I'm sure you can make a correct judgement about this one.

>> > I think this section should actually start with "Libraries can be either 
> shared or static, and which one is best
>> > depends on your situation". 
>> 
>> Do you think that adds any useful information? I don't. A user that
>> doesn't know there are static and shared libraries will immediately
>> infer that from the rest of the text. Saying "which one is best
>> depends on your situation" is semantics-free. That's true of
>> anything.
> 
> You're right. I gues I need to get my own "semantics-free alarm bell" 
> somewhere ;-)

I suggest as a first step you get Strunk & White's "The Elements of
Style." It's a very short book. It's biggest lesson is

use fewer words

If you always keep that in mind you will become very reluctant to write
anything unless you're sure what it means.

>> > Then it will say about <link>static and <link>shared,
>> 
>> What will it say about them?
>> 
>> > say that putting a library in sources of other library works no
>> > matter what kind of linking is used
>> 
>> It's _almost_ not worth saying that. The only reason anyone would
>> assume otherwise is experience with dumber build systems. If you want
>> to you can add a footnote that says "Don't worry; this works even with
>> static linking because Boost.Build passes static library dependencies
>> along to the final application."
> 
> The reason I've put this is that I don't know any system which does this 
> equally easy. I've just tried with SCons: both
> 
> StaticLibrary('foo', ['foo.cpp'])
> StaticLibrary('bar', ['bar.cpp', 'foo']);
> Program('main', ['main.cpp'], LIBS=['bar'], LIBPATH='.')
> 
> and 
> 
> StaticLibrary('foo', ['foo.cpp'])
> StaticLibrary('bar', ['bar.cpp'], LIBS=['foo'], LIBPATH='.');
> Program('main', ['main.cpp'], LIBS=['bar'], LIBPATH='.')
> 
> don't work.

I understand. That's why it's reasonable to say something. Not
everyone is aware of this pitfall, though -- do it in a way that doesn't
introduce worry for someone that isn't already thinking about it and
doesn't force the reader to go through an explanation of build details
the hiding of which is the build system's whole reason for existence
(boy, that was badly phrased; sorry!)

>> > + 
>> > + <!-- You should introduce the alias rule in an earlier
>> > + section, before describing how it applies to this
>> > + specific use-case, and the foregoing sentence should
>> > + go there. -->
>> > 
>> > Do you think "alias" deserves a separate section?
>> 
>> Possibly, although I have doubts about whether this belongs in the
>> tutorial at all. The tutorial ought to cover what you need to know
>> to get started, but not neccessarily the things you need to know in
>> order to use the system elegantly. This particular point is all
>> about elegance.
> 
> I'm starting to wonder if "shared and static linking" should be moved out of 
> tutorial completely.

Quite possibly so. I believe you can make a good judgement about that.

-- 
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com