* Charles Wilson wrote on Mon, Aug 30, 2010 at 09:45:00PM CEST: > On 8/30/2010 2:48 PM, Ralf Wildenhues wrote: > >Looks fine to me too, only one or two issues are not markup or typo > >nits (but I have been very nitpicky below). > > I expected that. This is really only a first draft with little in > the way of editing. I'm surprised at how few nits, or even major > criticisms, there are.
Oh, it is a strict improvement over no documentation. I might not have read it in full excruciating detail, but we can always improve things later. > >Thanks for writing this, > > Sure. Hopefully it also provides an appropriate spot (subsubsection > under Platform quirks:Cross compiling) for a discussion of sysroot. Sounds reasonable, yes. > >>+* File name/path conversion:: Converting filenames between platforms. > > > >FWIW, I would s/\/path// but only because I find the result more > >readable and as informative. > > Ack. Should filenames be 'file names', as well? I don't know; GCS does that consistently, yes. > >>+on one platform (the @code{$build} system) for use on a different platform > >>(the > > > >I don't much like variable references that include the $, because that > >ties you to a particular language, whereas here, you are talking about > >concepts rather than languages. standards.texi just use 'the build > >system'. Here, since you're defining the term, you could use > >@dfn{build system} or maybe @emph, and later on just use it without > >markup. > > Yeah, I really didn't know how to indicate that I'm talking both of > a concept, and some variable that libtool itself is sensitive to. I > tried @var, but that just looked wrong. @var is wrong. See my explanation of @var elsewhere in the mail. > This is a good place to > introduce terms; I'll use @dfn and reword as recommended in the > texinfo docu: Good. > >Use the command only in passages whose purpose is to > >introduce a term which will be used again or which the reader ought to > >know. Mere passing mention of a term for the first time does not > >deserve `...@dfn'. > >Actually, why not make this a normal inter-manual reference like > >@ref{GNU Build System,, The GNU Build System, automake, The Automake > >Manual} > > > >that way it will render well in all outputs? > > OK. The problem with @ref is that it *must* be followed by a . or , > This is not a problem in this instance, but it is a problem in > others. But if you look at how the references are rendered quite differently in the different output formats, and @pxref needs to go inside parentheses or at the end of a sentence, too. > >>+and @code{$host} were MinGW. In this situation, the WINE > >>+...@url{http://www.winehq.org/} environment can be used to launch "Win32" > > > >@uref{http://www.winehq.org/, Wine}, and s/WINE/Wine/ globally > > WINE is an acronym, in classic recursive style: WINE Is Not an > Emulator. But, it does appear the upstream folks have stopped > capitalizing it, so... Yeah, that's why I figured Wine would be more suitable (and readable). > I noticed one other thing at the winehq site: > > >Myth 9: "Wine is for Linux only" > >OK, as of now Wine does not run on many platforms: just Linux, MacOS > >X, FreeBSD and Solaris. Still, this is not 'Linux only'. > > I guess I'll need to reword a few things. Heh. > >>+...@code{$host} is MinGW (specifically, @code{i586-pc-mingw32}). On the > >>linux > > > >GNU/Linux > > OK. (Wasn't there a big discussion about how GNU should be > represented? @abbr{GNU} vs GNU vs... How'd that ever turn out?) Plain GNU. > >>+As described in the @pxref{Wrapper executables} section, the MinGW > >>@code{$host} > > > >@ref not @pxref. The latter is for inside parentheses and prints a > >"see", whereas the former doesn't. For details see 'info texinfo > >--index pxref'. More instances below. > > But since @ref must be terminated with a . or , I guess I'd need to > reword so the reference is treated as a noun rather than an > adjective (on 'section')? Yes, sorry. You could write: The following section (@pxref{...}) describes ... > +As described in @ref{Wrapper executables}, the MinGW ... Yep, sounds even better. > >>+...@example > >>+/var/tmp/foo/src/ (application code) > >>+/var/tmp/foo/lib/ (library code) > >>+...@end example > > > >What does this example code describe? You don't state that these are > >directories, and you don't state whether they belong to, say, the source > >tree, the build tree, or some install tree. > > Yes, I was trying to elide over all those details. I can be a lot > more specific, but it'll get (even more) wordy. Well, in a manual, wordy is good, if it's reasonably concise. Look at the Autoconf manual for some struggles between concise and detailed formulation. > >>+...@item Cygwin @tab MinGW (w32) > >>+...@tab @pxref{Cygwin/w32 Path Conversion} > > > >That'll be interesting to see whether doc tools cope well with references > >inside tables. > > You're _supposed_ to be able to do it. And, at least, the .info file > seemed ok. Ah ok, didn't know. Thanks! > >>+the two representations. In a correctly configured Cygwin installation, > >>+...@samp{cygpath} is always present, and is in the @var{$PATH}. > >>+ > >>+Libtool uses @samp{cygpath} to convert from Cygwin (unix) paths to w32 > >>format > >>+when @code{$build} is Cygwin and @code{$host} is MinGW or MSVC. > > > >For Peter's remark I suggest just using s/MinGW or MSVC/MinGW/ here. > > OK. I wasn't sure how much (if anything) to say about MSVC, since > Peter's patch series has only been partially merged so far, and I'm > not sure any of what HAS been merged is really MSVC-specific... Doesn't matter for the documentation. We'll get things working before too long. > >BTW, has it been reported upstream? > > Not yet. I'm not even sure it's a failure of Wine, or binfmt, or an > actual design (mis)feature. I mean, *wine* succeeded: it ran, and > did exactly what it was designed to do: emulate the Windows system > and launch a PE image. It's not Wine's fault that the PE image > itself loaded some DLLs that didn't provide the necessary APIs... > > *I* would return non-zero status, but then I don't know reasoning > behind the current behavior -- if it isn't simply a bug. Would be good to know (yeah, I'm getting lazy here). > >I suggest @kbd instead of faking a prompt. > > OK. (Can you /do/ that inside @example?) Yes, autoconf.texi has examples. > >>+does not automatically convert such arguments). However, so long as only > > > >Is "so long as" as right as "as long as"? (sorry for the pun) > > http://grammar.ccc.commnet.edu/grammar/grammarlogs2/grammarlogs359.htm > > "As long as" means "during the whole time that" and "so long as" > > means "provided that" or "only if,"... Ah, learned something new, thanks! > I can go ahead and replace it with "provided that" just to avoid > confusion... Naah, that's fine. > >>+...@example > >>+cygwin$ export PATH="/c/MinGW/bin:$...@{path@}" > >>+cygwin$ configure --build=i686-pc-mingw32 \ > >>+ --host=i686-pc-mingw32 \ > >>+ --disable-dependency-tracking > >>+...@end example > >>+ > > > >@noindent > > ??? > I don't understand. After the example: > >>+because otherwise the MinGW gcc will generate dependency files that contain you continue with a sentence. You don't want this to start a new paragraph, so @noindent (on a line of its own) avoids that initial indent of the first line of a paragraph. > >>+There have also always been a number of other details required for the > >>+...@emph{lying} case to operate correctly, such as the use of so-called > >>+...@samp{identity mounts}: > > > >@dfn or @emph, not @samp. > > OK. (Can you think of better names; something a little > less...informal and pejorative?) No idea, but we can change them later. > >>+should not be used within the source or build directory trees, and all > >>+...@code{-m*} options to @samp{gcc} except @code{-MMD} must be avoided. > > > >@option{-M*} > >@option{-MMD} > > D'oh. > > >This is not easy to achieve with Automake, as it will happily use some > >of these options. > > Are you suggesting I should add the above commentary---as long as > we're being opinionated, anyway: The one about Automake? No, not unless we have encountered problems. If we do, we can suggest --disable-dependency-tracking. > Thanks for the review. My pleasure. Cheers, Ralf