Re: [PATCH] Path conversion documentation

[Ralf Wildenhues]

* 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