doc-en/.svn/text-base/chapter-1-en.tex.svn-base

   1 \section{Constitution of the package -- Distribution}
   2
   3 \begin{compactitem}
   4 \item \textbf{Required files:} \texttt{pst-solides3d.sty}, \texttt{pst-solides3d.tex},
   5 \texttt{solides.pro} and the latest version of the basic PSTricks package.
   6 \item \textbf{Workflow:} This package is made for \texttt{dvips} and \texttt{ps2pdf}, however
   7 \texttt{pdf\TeX{}} won't work.
   8 \item \textbf{Documentation and examples:} \texttt{pst-solides3d-doc.tex(pdf)},
   9 \texttt{doc-exemples-solides3d.tex(pdf)}.
  10 \end{compactitem}
  11
  12 This package is available on:
  13 \url{http://syracuse.eu.org/syracuse/pstricks/pst-solides3d/}
  14 as well as on CTAN.
  15
  16 Numerous examples are available on:
  17 \url{http://syracuse.eu.org/lab/bpst/pst-solides3d}
  18
  19 Finally, the actual developer's version is available on the
  20 \texttt{SVN} of \textit{m\'{e}lusine}:
  21 \url{http://syracuse-dev.org/pst-solides3d}
  22
  23
  24 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  25
  26 \section{Installation hints}
  27
  28 Here we give some hints on how to install \texttt{pst-solides3d}
  29 on your \TeX{} system.
  30
  31 The \texttt{pst-solides3d} package consists of three main files:
  32 \begin{compactitem}
  33 \item \texttt{solides.pro}: the prolog file for \texttt{pst-solides3d}
  34 \item \texttt{pst-solides3d.sty}: the appropriate style file
  35 \item \texttt{pst-solides3d.tex}: the appropriate tex file
  36 \end{compactitem}
  37 as well as the actual PSTricks base files:
  38 \begin{compactitem}
  39 \item \texttt{pstricks.pro}: the prolog file for pstricks
  40 \item \texttt{pstricks.tex}: the appropriate tex file
  41 \end{compactitem}
  42 available on CTAN.
  43
  44 Some extension files for \texttt{pst-rubans}:
  45 \begin{compactitem}
  46 \item \texttt{pst-rubans.sty}: the appropriate style file
  47 \item \texttt{pst-rubans.tex}: the appropriate tex file
  48 \end{compactitem}
  49
  50 Save the files \texttt{pst-solides3d.sty|tex},
  51 \texttt{pst-rubans.sty|tex} and \texttt{pstricks.tex} in a
  52 directory which is part of your local \TeX{} tree.
  53
  54 However the \texttt{solides.pro} and the \texttt{pstricks.pro} file should go into the
  55 folder \verb+$TEXMF/dvips/pstricks/+  %$
  56
  57 Do not forget to run \texttt{texhash} to update this tree. For
  58 MiK\TeX{} users, do not forget to update the file name database
  59 (FNDB).
  60
  61 For more detailed information see the documentation of your
  62 personal \LaTeX{} distribution on installing packages to your
  63 local \TeX{} system.
  64
  65
  66
  67
  68 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  69
  70 \section{Preface}
  71
  72 The package presented in this documentation arose from teamwork
  73 initiated via the mailing list of the syracuse web site
  74 (\url{http://melusine.eu.org/syracuse}).
  75
  76 The idea was born of a confrontation between the work of
  77 Jean-Paul \textsc{Vignault} on the software package \textit{jps2ps}%
  78 \footnote{\url{http://melusine.eu.org/syracuse/bbgraf/}}
  79 and Manuel \textsc{Luque}'s work on PSTricks%
  80 \footnote{\url{http://melusine.eu.org/syracuse/pstricks/pst-v3d/}},
  81 especially in relation to the subject of representing solids in
  82 three-dimensional space.
  83
  84 The two authors decided to unify their efforts and co-author a
  85 PSTricks package dedicated to three-dimensional scenes. The work
  86 took place on the ``machine \textit{m\'{e}lusine}'' within an
  87 environment generated and maintained by Jean-Michel
  88 \textsc{Sarlat}.
  89
  90 The team was completed with the addition of Arnaud
  91 \textsc{Schmittbuhl}, Herbert \textsc{Voss}
  92 and J\"{u}rgen \textsc{Gilg}, the latter specialising in animation-based beta-testing%
  93 \footnote{\url{http://melusine.eu.org/syracuse/pstricks/pst-solides3d/animations/}}.
  94
  95
  96 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  97
  98
  99 \section {Presentation}
 100
 101 The package \texttt{pst-solides3d}, with the help of PSTricks,
 102 allows for 3D views of predefined or user-generated solids. You
 103 will find most of the usual solids, which can be drawn with or
 104 without hidden edges, whose colour can be varied with lighting.
 105
 106 This package can project text or simple graphics (in 2D) onto
 107 arbitrarily chosen planes or onto plane faces of solids that are
 108 created by the user.
 109
 110 From the user's standpoint, most of its functionalities are
 111 accessible by way of three \TeX{} macros: \Lcs{psSolid}, which can
 112 manipulate objects in 3 dimensions, \Lcs{psSurface}, related to the
 113 first macro and designed to represent surfaces that are defined by
 114 an equation of the type $f(x,y) = z$ and \Lcs{psProjection} which
 115 allows the user to project two-dimensional graphics/text onto any
 116 plane face of a 3D solid.
 117
 118 In using this package, two languages come together: on the one
 119 hand PSTricks, with its well-known macros and familiar syntax, and
 120 on the other PostScript code, which appears within the optional
 121 arguments of the former.
 122
 123 We have made the decision to strictly limit the involvement of
 124 PSTricks. Its function is only to transmit parameters from \TeX{}
 125 to PostScript. All calculations and displays are done by the
 126 latter.
 127
 128 A PostScript library, which was developed for another application
 129 (the software package \textit{jps2ps}), is used for all
 130 calculations and display routines. The PostScript code used in
 131 this library is called \textit{jps code}.
 132
 133 The aim of the present document is to describe PSTricks syntax for
 134 each operation provided by the package.
 135
 136 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 137
 138 \section{Changes by comparison with previous versions}
 139
 140 \subsection{Changes compared to version 3.0}
 141
 142 \begin{compactitem}
 143 \item The macro \Lcs{psProjection} has been completely rewritten. We now need to use an
 144 object of type \Lkeyword{plan} to define a projection.
 145 \item The object \Lkeyword{courbe} now uses the argument $r$. To reproduce the previous behaviour
 146 we now have to specify $r=0$.
 147 \item The option \Lkeyword{resolution} of the object \Lkeyword{courbe} is replaced with the option
 148 \Lkeyword{ngrid}
 149 \item Suppression of the argument \Lkeyword{tracelignedeniveau}.
 150 \end{compactitem}
 151
 152 \subsection{Changes compared to version 2.0}
 153
 154 \begin{compactitem}
 155 \item The option \Lkeyword{hue} is not a Boolean anymore.
 156 \item The scaling in PostScript will from now on follow the workings of \textit{jps code}.
 157 To be consistent, the commands \verb+smoveto+,
 158 \verb+srmoveto+, \verb+slineto+, \verb+srlineto+ now
 159 respectively replace the commands \verb+moveto+,
 160 \verb+rmoveto+, \verb+lineto+, \verb+rlineto+.
 161 \end{compactitem}