From maintainers-request at octave dot org Sat Jan 21 08:07:08 2006
Subject: Re: Sparse Doc patch
From: David Bateman <David dot Bateman at motorola dot com>
To: Quentin Spencer <qspencer at ieee dot org>
CC: "John W. Eaton" <jwe at bevo dot che dot wisc dot edu>,         octave maintainers mailing list <maintainers@octave.org>
Date: Sat, 21 Jan 2006 15:02:44 +0100

Quentin Spencer a écrit :

>
> >I'm replying on the maintainers list to give others a chance to
> >comment.
> >
> >Without looking at the patch, I'm in favor of the idea of making this
> >change.  I see no reason to omit figures from the docs now.  It was
> >more of a problem back in the dark ages (say, 10-12 years ago) when
> >fewer people had ways to display PostScript and Texinfo did not have
> >any standard way of supporting figures, so there was reason to avoid
> >them.  It would be nice to have ASCII art for the info format, but if
> >that is not possible, then we can just put a text tag in that briefly
> >describes the figure (for example, "[Figure showing the sparsity
> >pattern for FOO]").
> >
> >If possible, I think we should store the source code for generating
> >the figures rather than the figures themselves, then add rules to
> >create EPS, PDF, PNG or whatever formats are needed.  That way, we can
> >easily modify the figures as needed in the future.  It will be much
> >harder to do that if all we have are the figures in the final
> >format(s).
> > 
> >
>
> I think including figures is a great idea, and I agree that it is now
> more practical than it once might have been. I also agree with John's
> suggestion of storing the source code. In addition to making long-term
> maintenance, having some example code in the octave distribution could
> also be a helpful resource for people asking one of the most FAQs of
> them all on the help list: "How do I save my figures?"
>
> -Quentin
>
Hummm, ok for the texinfo.tex and other minor changes I made, but using 
a script to create the figures implies a large overhead for me, though I 
can understand the convenience afterwards.

The figures I used are those in Andy's and my Octave 2006 paper and 
based on a fairly large example matrix from the eidors project. To make 
the figures a reasonable size (The original gnuplot file of one of these 
was 7MB) I had to manipulate the figures significantly by hand.Firstly 
the script would need access to the original Eidors example matrix, 
which is itself large. But I also had a lot of hassles to optimize the 
figures for use.

 What I did was convert to 600dpi PNG's with a command like

export epsfile="file.eps"
export pngfile="file.png"
export PNMTRANSPARENT="-background white -transparent =white"
cat ${epsfile}| epsffit $(grep '^%%BoundingBox:' ${epsfile} | head -1 |  
awk '{printf "0 0 %d %d", $4-$2, $5-$3;}') |  gs -q -dNOPAUSE -dBATCH 
-sDEVICE=pnm -sOutputFile=- $OPTIONS -f - -c quit | pnmcrop | pnmtopng 
$PNMTRANSPARENT > ${pngfile}

I then convert to pdf and back to eps with ImageMagik to get a smaller 
file size. For the eps it was in monochrome, while pdf was in colour, 
otherwise I didn't win. If the basic eps file size was smaller then I 
could do the above for the png files and to pdf with

export pdffile="file.pdf"
 cat ${epsfile} | epsffit -c $(grep '^%%BoundingBox:' ${epsfile} | head 
-1 | awk '{printf "0 0 %d %d", $4-$2, $5-$3;}') | gs -q -dNOPAUSE 
-dBATCH -sDEVICE=pdfwrite -dDEVICEWIDTH=2100 -dDEVICEHEIGHT=2100 
-sOutputFile=${pdffile} -f - -c quit

Given the optimization of the figures I did, basically using a script is 
asking me to fiind a reasonable test matrix for the matrix and redo all 
of the figures and supporting text.. For the info documentation I used 
the script at the end of this message. I suppose I could use this with a 
larger value of "n" for the other figures to get reasonable figure, but 
they will have less generic interest.

Another question is how and where are the scripts to be stored? In a 
directory doc/interpreter/scripts? Can I assume that epsffit, pnmcrop, 
pnmtopng, etc are available, as this adds yet another external 
dependency on the build of octave?

Ok, I'll rework what I did to use scripts, and resubmit a patch, but the 
above questions need answers...

Regards
David


function script1
  n = 15;
  a = 10*speye(n) + sparse(1:n,ceil([1:n]/2),1,n,n) + ...
      sparse(ceil([1:n]/2),1:n,1,n,n);
  spy(a);
  printsparse(a);
  r1 = chol(a);
  printsparse(r1);
  q2 = symamd(a);
  r2 = chol(a(q2,q2));
  printsparse(r2)
  [r3,p3,q3]=chol(a);
  printsparse(r3)
endfunction

function printsparse(a)
  for i = 1:size(a,1)
    if (rem(i,5) == 0)
      printf ("         %2d - ", i);
    else
      printf ("            | ");
    endif
    for j = 1:size(a,2)
      if (a(i,j) == 0)
    printf("  ")
      else
    printf(" *")
      endif
    endfor
    printf("\n")
  endfor
  printf("            |-");
  for j=1:size(a,2)
    if (rem(j,5)==0)
      printf("-|");
    else
      printf("--");
    endif
  endfor
  printf("\n")
  printf("              ");
  for j=1:size(a,2)
    if (rem(j,5)==0)
      printf("%2d",j);
    else
      printf("  ");
    endif
  endfor
  printf("\nnnz = %4d\n",nnz(a))
  fflush(stdout);
endfunction