[texhax] upgrade of PSTricks documentation

[Tom Schneider]

Philip:

> Well, I think you're either very unlucky, or your
> choice of search engine is seriously flawed.
> I typed "pstricks manual" into Google, and the
> first hit was :
> 
> 	http://www.see.ed.ac.uk/~ltex/pstricks/
> 
> of which the first few lines read
> 
> > PSTricks package
> > 
> > PSTricks is a package that allows access to features of PostScript 
>  > that would not be directly accessible from LaTeX otherwise. It
>  > operates in conjunction with dvips so results may not be seen
>  > in previewers such as xdvi. The user manual for PSTricks comes i
>  > n four parts:
> > 
> >     * Part 1
> >     * Part 2
> >     * Part 3
> >     * Part 4 
> > 
> > There is also a quick reference guide which may be worth a look. 
> 
> Parts 1 to 4 contain hyperlinks to
> 
> 	http://www.see.ed.ac.uk/~ltex/pstricks/pst-usr1.ps
> 
> 		<etc>
> 
> which after distilling gives me a perfectly usable PDF version
> of the manual ...

By "distilling" I assume you mean convertion to PDF with some
commercial program?  Do you mean ps2pdf?

That's all fine, but you have found a secondary source.

The primary source is at CTAN:

google:
pstricks
first hit:
http://tug.org/PSTricks/main.cgi/

That is the primary
source.  There is a manual there but it is rather difficult to find. 
You click on the left, 'Documentation', skip all the stuff and click
on

   PSTricks user guide:  as one PDF (without an index) (with an
   index).  The two doc files in in one file)

I am looking for the *original* tex files so that I can CORRECT this
manual.  If you click on the left, 'Doc errors' you get

http://tug.org/PSTricks/main.cgi?file=pst-doc.err&verb=1

which are corrections to the manual.  I stubbed my toe because this
was not properly incorporated into the actual manual.

These pages are quite a tangle.  A new user (me!) gets lost in all the
irrelevant files.  I suggest that primary manual should be up top and
in large letters.  Secondary files should be further down the page.

I also suggest that a short description about *what this program does*
be put up top with one or two example images.

One of the major problems with LaTeX is that, although it is extremely
powerful, people have no idea what all the packages do and finding out
...  if like pulling teef. ;0)

So, for example, on the main page the first thing a user sees is:

    Welcome to the PSTricks web site

so far so good.  What is 'PSTricks'?

We are then told:

    Most of the PSTricks related packages are available at CTAN. For
    others choose topic packages from the left menu.

Well that's too much detail.  How about the next line?

    For more information read the documentation of the packages and/or
    search the PSTricks mail archives of the pstricks mailing list at
    http://www.tug.org

It gets more technical and confusing after that.

But wait!  I don't even KNOW what PSTricks DOES or why I should CARE
about it!  At this point 99% of the potential audience for this very
powerful tool is GONE.

I suggest a rewrite of this page.

Google:
pstricks.tex

gets me various things.  Where is the original *official* source that
I should work with?

Tom

  Dr. Thomas D. Schneider
  National Institutes of Health
  National Cancer Institute
  Center for Cancer Research Nanobiology Program
  Molecular Information Theory Group
  Frederick, Maryland  21702-1201
  toms at ncifcrf.gov
  permanent email: toms at alum.mit.edu (use only if first address fails)
  http://www.ccrnp.ncifcrf.gov/~toms/

http://en.wikipedia.org/wiki/Top-posting
http://www.uwasa.fi/~ts/http/quote.html
http://why.openoffice.org