Back after a little break

[Carl Worth]

José Fonseca <jose.r.fonseca at gmail.com> writes:
> Welcome back.

Thanks.

> I'm still missing merging your trim tests in the tests repository
> (trim-auto branch). It's some portability issue -- the tests fail on
> some platform -- but I don't remember exactly. I'll get back to  you
> on that.

I had meant to ask why that wasn't merged. I'll look forward to what you
can explain there.

> The reasons I pointed to stick with the "retrace" metaphor were (
> http://lists.freedesktop.org/archives/apitrace/2011-October/000082.html
> ):
> - I don't perceive "retrace" metaphor as wrong or particularly bad

Obviously, I disagree on that point. :-)

> - for consistency with the trace metaphor

Using "trace" for the operation that "apitrace trace" performs is a well
established metaphor among software tools. Think of things like strace,
ltrace, DTrace, etc. All of these tools allow one to run an existing
program and collect additional information. But that metaphor does not
apply at all to the case of replaying a collected trace.

So consistency here actually hurts, rather than helps user
understanding.

> - for consistency with the project name (apitrace)

I cannot see any benefit to this. Would you prefer "difftrace" to "diff"
or "dumptrace" to dump, etc.? We have "apitrace" in the command-line
interface always, so there's plenty of reinforcement of that naming
already.

> - for consistency with what we have (though this might not be clear)

I'm not sure what you're referring to here.

> I do believe that changing nomenclature now is a bigger disservice to
> our current users than using a more user friendly name.

In what sense? I can see a valid point about compatibility with existing
scripts, etc. I would be more than happy to do work to help address that
issue, (such as ensuring that "apitrace retrace", "glretrace" and
"d3dretrace" commands work and are made available).

> I hate to refuse this when you already put some work carrying out the
> rename. You're obviously a great contributor to apitrace which I don't
> want to aggravate. But I really can't accept it. If nothing else, all
> the work and time it would require me to update our (VMware's)
> internal documentation and scripts for the rename is a showstopper.

For scripts, we don't have to break compatibility. For anything else,
I'd be happy to help edit things if you can make them available to
me. (For example, I'd be happy to help edit the webpages if that content
can be made available in some form that I could edit it with sed and
emacs, etc.)

The only two tricks I've seen as far as automating the rename are

	1. We have to be careful to search/replace retraced->replayed
	   and retracer->replayer before doing retrace->replay.

	2. We have to be careful to preserve case, (RETRACE->REPLAY,
	   Retrace->Replay, retrace->replay).

With those two points taken care of, things are quite easy to
automate. The only potential issue I can see is that "replay" is one
letter shorter than "retrace" so any formatting relying on the length
could be changed. (I haven't noticed any cases of this in the code, and
it's probably less likely that there's anything in the documentation.)

> I know I'm terribly unimaginative with names. Even the name "apitrace"
> itself is source of some regret to me (as it is not unique enough).

Yes, we've discussed this too. It's not unique enough to enable reliable
web searches. And even in the realm of similar tools there are already
collisions. For example, AMD's GPU PerfStudio 2 has a sub-tool named
"API Trace":

http://developer.amd.com/tools/graphics-development/gpu-perfstudio-2/gpu-perfstudio-2-api-trace/

In addition to that, I've found the name hard to use in documentation.
The use of the initialism "API" makes it a bit tricky to spell the name
so that the new readers get the right interpretation. For example, how
should I capitalize the name when it appears as the first word of a
sentence? Leaving it as "apitrace" violates English conventions.
Capitalizing it as "Apitrace" seems odd and might encourage a misreading
as "a pit race" which would be most unfortunate. Breaking down to
"APItrace" or "API-trace" would make the initialism clear, but would be
totally inconsistent with all existing documentation, (and the
command-line interface). So that seems unattractive as well.

So I agree that the name is imperfect. I would have preferred to rename
it back when I first started coding here, (and when I requested a
rename), but I decided to choose my battles and let this one be.

But the "apitrace replay" naming is totally different. The "apitrace"
command line is something I designed and implemented and over which I
feel some sense of ownership. And from the beginning, I named it
"apitrace replay" so any incompatibility in scripts, etc. would be from
the earlier renaming of "replay" to "retrace".

> But for good or worse, this is the nomenclature we have now, and
> changing it is a source of trouble that simply is not worth my while.
> I hope you can understand and accept it.

For all the reasons I've explained above, I'm not willing to just accept
"retrace". I think that apparently trivial aspects of user-interface
design can be very important. (See git's command-line interface where
a collection of several small inconsistencies have given it a reputation
of being hard to learn.)

> All I need is your github user name. After I add you to the commiter
> list you're free to add new branches.

Oh, right. I had forgotten this was on github. I'll pass on that,
then. [*]

Given that, would you prefer me to email complete patches to the list or
just requests for you to pull and merge particular branches hosted in my
personal repository?

-Carl

[*] My reasoning for not using github might be perceived as off-topic
for the apitrace mailing list. But I'll at least mention some things in
this footnote:

I think it's a strategic mistake to host free software on non-free
services. I don't have a totally concrete definition of a free service,
but I think it should provide at least the following:

  1. Users own their own submitted data.

  2. Users can extract their data at any time through a mechanism and
     format preferred for that data.

  3. The service should be implemented with free software

Non-free services are a big problem across the internet now. And with
respect to that, github does a lot better than many. For example point
(1) seems to be in place for all data. That's good.

Point (2) is perfect for the code itself due to the way "git clone"
works. But I don't think anything is in place for things like the
website, wiki, issue-tracking, etc. There's an easy test for this one:
If github.com disappeared from the internet today, would you lose any
data or any convenience in your ability to edit your data? Another test
came up in the renaming question above. Can I run a sed job over the
existing web-site and wiki contnet?

As far as I'm aware point (3) is not in place for anything on github.
And I try as much as I can to avoid using software systems where I don't
have the ability to change the way they work.

-- 
carl.d.worth at intel.com
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 197 bytes
Desc: not available
URL: <http://lists.freedesktop.org/archives/apitrace/attachments/20130129/eb812065/attachment.pgp>