\start
Date: Wed, 06 Mar 2013 16:18:30 -0500
From: Tim Daly
To: list
Subject: Re: [axiom] a typesetting error in bookvol4, page 18 (#1)

> There is one line missing:
> 
> ~~~~
> --- tmp/axiom/books/bookvol4.pamphlet	2013-03-01 18:33:03.254730906 +0800
> +++ bookvol4.pamphlet	2013-03-06 12:17:50.170565342 +0800
> @@ -1189,6 +1189,7 @@
>          a x + b
>                                              Type: Fraction Polynomial Integer
>  
> +\end{verbatim}
>  \subsection{A simple integral}
>  
>  Now we will show an integration with successive levels of expansion
> 


Thanks for the patch. I applied it.
Who are you so I can give you credit?

\start
Date: Thu, 14 Mar 2013 15:00:16 -0400
From: Tim Daly
To: Jia Zhao Cong
Subject: Re: sorry for bothering and a small patch

> First, there is a misspelling in my email address. Second, there
> is a misspelling in bookvol0 and bookvol1.

Sorry. I will fix this.

Also I was unclear about your name format. I believe that the family name
comes first in Asian names (so I would be Daly Tim) but I took a 
guess based on your email address. Did I get it the way you prefer?

> I noticed that you have changed the buglist, is there something I
> can do?

The work you are doing to read and fix the books is valuable.

I reviewed the console output, collected all of the compiler
complaints, and added them to the buglist. There are duplicate
entries because I have done this before. This time I tried to
classify them into categories.

The easiest ones to fix are those marked

   "should replace by @"

Generally what this means is that someone wrote something like:
     
==============================================================
warnings 20542:

>compiling ITAYLOR.spad to ITAYLOR.nrlib

  Warnings:
    [1] series: pretend$ == should replace by @
    [2] := st has no value

The problem is to fix item [1]. What the compiler is complaining
about is that 'pretend' is a way of telling the compiler to 
"trust me, I know this is right" 

but the compiler knows how to coerce correctly. 

To find out what the problem is, first start Axiom and type

   )show ITAYLOR
   ......
   Issue )edit bookvol10.3.pamphlet to see algebra source code for ITAYLOR

so you know that ITAYLOR.spad is in bookvol10.3.pamphlet

If you edit this file and search for

   )abbrev domain ITAYLOR

you find the domain. The domain has 2 parts, the list of exported
functions and the implementation of those functions. The 
implementation happens after the word "add"

There we find the defintion (axiom definitions start with "=="

   stream x == x pretend %

The compiler knows from the export definition line that 

  stream: Stream Coef -> %

means that the function series takes a "Stream Coef" and 
returns an ITAYLOR thing. It also knows, from the line,

   Rep := Stream Coef

that ITAYLOR things are represented by Stream Coef objects.

When the compiler sees:

   stream x == x pretend %

it already knows that it can coerce the argument to stream correctly.
It does not need to "pretend" and it does not need to "trust us".

So you have to take several steps to fix this:

    1) verify that the problem occurs in the latest build
    2) isolate ITAYLOR as ITAYLOR.spad
    3) compile ITAYLOR to see the error message
    4) change the line
    5) recompile ITAYLOR to see the message is gone
    6) make the change in bookvol10.3.pamphlet/ITAYLOR
    7) rebuild Axiom
    8) check that the problem is gone in the build
    9) create a diff -Naur patch
   10) post it to the mailing list or send it to me

In detail:
================================================================
    1) verify that the problem occurs in the latest build
================================================================

   git clone git://github.com/daly/axiom.git silver
   cd silver
   export AXIOM=`pwd`/mnt/ubuntu
   export PATH=$AXIOM/bin:$PATH
   time make NOISE= TESTSET=regresstests
      ... scan output for ITAYLOR
      ... look for 
        Warnings:
          [1] series: pretend$ == should replace by @
          [2] := st has no value

(This way you know that the error still exists in the latest build
and has not been fixed)

================================================================
    2) isolate ITAYLOR as ITAYLOR.spad
================================================================

edit bookvol10.3.pamphlet. search for

   )abbrev domain ITAYLOR

clip the code between \begin{chunk} and \end{chunk}
put it into a file called ITAYLOR.spad

(This way you have an isolated case where you can easily 
reproduce the error)

================================================================
    3) compile ITAYLOR to see the error message
================================================================

   axiom -nox
   )co ITAYLOR
      ... scan output for ITAYLOR
      ... look for 
        Warnings:
          [1] series: pretend$ == should replace by @
          [2] := st has no value

(Now you can reproduce the error and make sure you fixed it)

================================================================
    4) change the line
================================================================

change

   stream x == x pretend %

to

   stream x == x @ %

================================================================
    5) recompile ITAYLOR to see the message is gone
================================================================

   axiom -nox
   )co ITAYLOR
      ... scan output for ITAYLOR
      ... look for 
        Warnings:
          [1] := st has no value

(Now you fixed the error)

================================================================
    6) make the change in bookvol10.3.pamphlet/ITAYLOR
================================================================

edit bookvol10.3.pamphlet
search for 
   )abbrev domain ITAYLOR
find the line that reads:

   stream x == x pretend %

and change it to

   stream x == x @ %

================================================================
    7) rebuild Axiom
================================================================

   cd silver
   export AXIOM=`pwd`/mnt/ubuntu
   export PATH=$AXIOM/bin:$PATH
   make clean
   time make NOISE= TESTSET=regresstests

================================================================
    8) check that the problem is gone in the build
================================================================

   ... scan output for ITAYLOR
   ... look for 
     Warnings:
       [1] := st has no value

(Now you know the fix to bookvol10.3.pamphlet worked)

================================================================
    9) create a diff -Naur patch
================================================================

   cd silver
   git diff >20130314.01.jzc.patch

(Note that patch names are written as
   year          2013
   month             03
   day                 14
   increment             .01
   author                   .jzc
   type                         .patch

but you can use any name you like)

================================================================
   10) post it to the mailing list or send it to me
================================================================

cat 20130314.01.jzc.patch | mail -s "20130314.01.jzc.patch" -c
list Tim Daly 

\start
Date: Mon, 25 Mar 2013 06:04:48 -0400
From: Tim Daly
To: Jia Zhao Cong
Subject: Re: how to send a patch

>I found a lot typos and a few logical errors in bookvol0,
>I think it's better to use a git branch instead of a big patch,
>do you agree?

No matter how you send it I'm going to go through the change on
a line-by-line basis. 

A branch might be a way to go but I had a very bad experience with
creating branches for people. Two developers had their own branches
and never bothered to merge the results back into the main line.

Eventually the branches were incompatible with each other
and with the main line. When I tried to pick up and merge the
changes I was unable to resolve them all, causing a lot of anger
and grief.

The end result was forking.

If you want to maintain a branch I expect that you'll pull from
the main branch, resolve any conflicts, build cleanly, and then
ask me to pull from your branch. If my pull fails I'm just going
to ask you to "fix" your branch by going through the process again.

I do not want to be in a position of having to resolve other
people's conflicts again. I can only get it wrong and end up
making people angry.

Create a branch if you like but I'd prefer a diff -Naur patch
or git patch.

>
>About typos, I found there are many many patterns like this:
>"a word or a phrase," next sentence.

>
>Should I exchange the comma and the quotation mark?

It turns out that, much to every programmers annoyance, putting the
punctuation inside the double-quote is correct. Real english language
editors "fix" this all the time by moving the punctuation inside. 
So, no, don't "fix" these.

\start
Date: Fri, 29 Mar 2013 03:23:25 -0400
From: Tim Daly
To: Jia Zhao Cong
Subject: Your Jenks book patch set

Jia,

I applied your fixes to the Jenks book.

Be aware that you probably want to pull the latest version.
I have made several changes.

I added all of the images to the book (about 70 pictures added).
I added and changed some text. 
I will add more of the new Axiom domains soon.
I added latex comments of the form:
   %Original Page xxx
so it is possible to find where the electronics text aligns with the
pages in the hard copy of the book.


