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
> > +<!-- Boost.Build... unless of course you think it's likely to work
> > +<!-- 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
> > 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
> > 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.
> > Must have misunderstood something. Is <varname> for features and <code>
> <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.
> > The set of properties specified in the command line
> > - <firstterm>build request</firstterm> — a description
> > + <firstterm>build request</firstterm>—a description of
> > Why spaces are gone? At least in LyX/TeX, I always surround em-dashes with
> My publisher never puts spaces around em-dashes.
Hmm... I need to do some research.
> > <programlisting>
> > exe hello
> > : hello.cpp
> > : <include>/home/ghost/Work/boost <threading>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.
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------------------^
> > - "free" feautures like <code><include></code>
> > - <footnote>See <xref
> > - linkend="bbv2.reference.features.attributes"/></footnote>,
> > - augments) the target requirements.
> > + “free” features like
> > 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
> > 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
> > + 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
> > 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.
> > 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
You're right. I gues I need to get my own "semantics-free alarm bell"
> > 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('bar', ['bar.cpp', 'foo']);
Program('main', ['main.cpp'], LIBS=['bar'], LIBPATH='.')
StaticLibrary('bar', ['bar.cpp'], LIBS=['foo'], LIBPATH='.');
Program('main', ['main.cpp'], LIBS=['bar'], LIBPATH='.')
> > 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
> > - easily achieved using requirements:
> > + <para>
> > + We can also use the <varname><link></varname> property
> > + to express linking requirements on a per-target basis.
> > + <!-- <orderedlist> The use of an orderedlist is inappropriate
> > 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.
> > +
> > + <!-- 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
> > + The processing of the <varname><link></varname> feature
> > + 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
> > +
> > + 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 ;-)
> > 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.
> > 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
Boost-Build list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk