[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH] Path conversion documentation
From: |
Ralf Wildenhues |
Subject: |
Re: [PATCH] Path conversion documentation |
Date: |
Mon, 30 Aug 2010 22:20:12 +0200 |
User-agent: |
Mutt/1.5.20 (2010-04-22) |
* 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 address@hidden'.
> >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
> >>address@hidden://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.
> >>address@hidden 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.
> >>address@hidden
> >>+/var/tmp/foo/src/ (application code)
> >>+/var/tmp/foo/lib/ (library code)
> >>address@hidden 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.
> >>address@hidden Cygwin @tab MinGW (w32)
> >>address@hidden @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,
> >>address@hidden 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.
> >>address@hidden
> >>+cygwin$ export PATH="/c/MinGW/bin:address@hidden@}"
> >>+cygwin$ configure --build=i686-pc-mingw32 \
> >>+ --host=i686-pc-mingw32 \
> >>+ --disable-dependency-tracking
> >>address@hidden 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
> >>address@hidden case to operate correctly, such as the use of so-called
> >>address@hidden 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
> >>address@hidden 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