Re: [jamboost] Re: Tutorial edits comments

From: Vladimir Prus (ghost_at_[hidden])
Date: 2004-12-28 14:09:46

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?

> > Of course, you probably have better wording anyway.
> 
> Don't assume I do. Unless I've suggested wording, go ahead and make
> the edits. I can always improve things later if I think of a way.

Okay.

> > Must have misunderstood something. Is <varname> for features and <code> 
for values?
> 
> <varname> is a fairly close match for features, but again a BoostBook
> extension should help. For values I should be using <literal> until
> we get the right extension, I think. <code> is probably a mistake.

Okay.

> > The set of properties specified in the command line 
constitute a
> > - <firstterm>build request</firstterm> &#x2014; a description 
of
> > + <firstterm>build request</firstterm>&#x2014;a description of
> > 
> > Why spaces are gone? At least in LyX/TeX, I always surround em-dashes with 
spaces.
> 
> My publisher never puts spaces around em-dashes.

Hmm... I need to do some research.

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

> > requirements specified above will normally always be present.
> > If the build request given on the <command>bjam</command>
> > command-line explictly contradicts a target's requirements,
> > the command-line usually overrides (or, in the case of
> open paren------------------^ 
> > - &quot;free&quot; feautures like <code>&lt;include&gt;</code>
> > - <footnote>See <xref
> > - linkend="bbv2.reference.features.attributes"/></footnote>,
> > - augments) the target requirements. 
> > + &ldquo;free&rdquo; features like 
<varname>&lt;include&gt;</varname>,
> > 
> > What's ldquo and why it's better than quot?
> 
> 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"?

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

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

> > 
> > 
http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.WhichvsThat.html
> > 
> > which discusses "that" vs. "which" quite clearly. OTOH, at the end
> > it says that using "which" in restrictive clauses is "more or less
> > okay (and popular among writers of British English)", so I have an
> > excuse ;-) (After all, my spellchecker uses British dictionary)
> 
> Okay, I understand. Don't feel bad; I only learned the rule this
> year because of the book I wrote. Sometimes I wish I hadn't; now I
> see thousands of misuses all over the place and they drive me crazy!

;-)

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

> > 
> > It applies to all relative paths in
> > + Boost.Build, some of which you've covered. -->
> > 
> > What do you mean?
> 
> You've already covered #include paths and paths to other projects at
> the very least. At a high level you just want to say "all relative
> paths are interpreted relative to the Jamfile where they appear."
> That way you don't have to talk about "adjusting" the paths. The new
> user has no idea that bjam runs commands from the invocation directory
> and not from the directory of the Jamfile (as many other build systems
> do) anyway.

Ok. Changed.

> > 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 ;-)

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

> > and then mention (in <tip>) the hardcode-dll-paths feature.
> 
> That part I agree with ;-)
> 
> > - <orderedlist>
> > - <listitem>
> > - <para>
> > - Suppose your library can be only build statically. This 
is
> > - easily achieved using requirements:
> > + <para>
> > + We can also use the <varname>&lt;link&gt;</varname> property
> > + to express linking requirements on a per-target basis. 
> > + <!-- <orderedlist> The use of an orderedlist is inappropriate 
here. -->
> > 
> > Why? I'm trying to list several situation which are possible for
> > shared/static linking combinations.
> 
> An ordered list should be used with an introduction like "There are
> three ways to do <whatever>:", and probably should only be used if
> you're really sure you're enumerating *all* the ways to do that. I'm
> guessing that you're not sure of that here.

Ok.

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

> > + The processing of the <varname>&lt;link&gt;</varname> feature 
is
> > + built in, and is quite complex, but 
> > + <!-- These two points don't make an appropriate "A but B"
> > + clause, because <link> doesn't allow the system to "do
> > + different things depending on properties. -->
> > + there are a couple
> > + of mechanisms that allow ordinary users to do different things 
> > + depending on properties.
> > + <!-- They don't _allow users_ to do different things; it's the
> > + build system that does different things. And "different
> > + things" is too vague. -->
> > + </para>
> > +
> > + <!-- You could replace the foregoing paragraph with: 
> > +
> > + "Sometimes, particular relationships need to be maintained
> > + among a target's build properties. In this section we'll
> > + discuss two mechanisms for expressing those 
relationships."
> > +
> > + It took me about five minutes to figure out how to say that,
> > + and it still isn't perfect. But at least it says what we're
> > + about to talk about with _some_ precision. Saying what you
> > + mean is hard and requires an investment of effort and
> > + attention.
> > + -->
> > 
> > I think your suggestions is fine. The only problems is that alternatives 
are not exactly
> > "relationships among properties", 
> 
> I believe that although they aren't implemented that way, because you
> have the <source> property, the can thought of as being a relationship
> among properties. But as I said, I know my wording isn't perfect but
> I think it's a big improvement. It took me five minutes, so I suggest
> you take *ten* minutes to try to improve it ;-)

I'll try.

> > Do you consider xref generally better than link? Like in TeX, where
> > most references do not include text?
> 
> It is better if you're going to make PDFs. You can usually count on
> it that TeX got the right abstractions for printed output. In fact I
> have half a mind to make a BoostBook -> LaTeX -> PDF toolchain. We
> couldn't get XSL:FO to work for the book and as much as I hate
> LaTeX's quirks and limitations, it really works.

That's true.

> > Now, what shall we do next? I can go ahead and apply edits which you
> > did not apply, if that won't cause any conflicts with what you're
> > doing.
> 
> I'm only moving on to the other .xml files. You should do the work
> in tutorial and install, and edit out my comments once you've handled
> them. You have to learn by doing.

Sure, I'm in the process.

> By the way, thanks for being so receptive to my criticism and
> teaching. It really makes the effort I invested feel worthwhile!

That you for helping! It's really pleasant when somebody provides such 
constructive criticism.

- Volodya