diff options
author | Karl Berry <karl@freefriends.org> | 2006-01-09 00:44:40 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2006-01-09 00:44:40 +0000 |
commit | b4fc5f639874db951177ec539299d20908adb654 (patch) | |
tree | 52f08823ca58fffe3db6a9b075635038c567626c /Master/texmf-dist/doc/latex/ieeepes/ieeepes_doc.tex | |
parent | dec3d98ebe442d7ea93efbaa8dd2e2be8149a467 (diff) |
doc 4
git-svn-id: svn://tug.org/texlive/trunk@80 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/ieeepes/ieeepes_doc.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/ieeepes/ieeepes_doc.tex | 620 |
1 files changed, 620 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/ieeepes/ieeepes_doc.tex b/Master/texmf-dist/doc/latex/ieeepes/ieeepes_doc.tex new file mode 100644 index 00000000000..4476c860a13 --- /dev/null +++ b/Master/texmf-dist/doc/latex/ieeepes/ieeepes_doc.tex @@ -0,0 +1,620 @@ +%%---------------------------------------------------------------------- +%% ieeepes_doc.tex +%% +%% Volker Kuhlmann +%% c/o EEE Dept +%% University of Canterbury +%% Private Bag 4800 +%% Christchurch, New Zealand +%% Email: KUHLMAV@ELEC.CANTERBURY.AC.NZ +%% +%% 4.0 20Apr99 Environments Table, Figure. Reserved name nophoto. +%% 1.7 03Apr96 Option noieeebox. +%% 1.6 20Nov95 Corrections. +%% 1.5 16Nov95 Added summary. +%% 1.4 14Nov95 Corrections. +%% 1.3 12Nov95 Finished first version. +%% 1.2 11Nov95 Extended. +%% 1.1 09Nov95 Extended. +%% Version 1.0, 24 Sep 1995 +%%---------------------------------------------------------------------- + +\def\Filename{ieeepes\_doc.tex} +\def\Fileversion{V4.0} +\def\Filedate{20 April 1999} +\def\Packageversion{package ieeepes version 4.0, 1999/04/13} + + +\documentclass[twoside,twocolumn,a4paper]{article} + + +\usepackage{doc} +\MakeShortVerb | + +\parindent 0em +\parskip 1.5ex plus.5ex minus.5ex +\columnsep 7mm + +%\usepackage{ieeepes} + +% Load PostScript Times font, if desired +%\usepackage{times} + + + +\title{A \LaTeX-Package for IEEE PES Transactions} + +\author{ + Volker Kuhlmann\\ + Dept of Electrical and Electronic Engineering\\ + Christchurch, New Zealand +} + + + +\abovedisplayskip 0\abovedisplayskip +\belowdisplayskip 0\belowdisplayskip +\abovedisplayshortskip 0\abovedisplayshortskip +\belowdisplayshortskip 0\belowdisplayshortskip + + + +\begin{filecontents}{ieeepes_doc.bbl} +\begin{thebibliography}{1} + +\bibitem{IEEEPES_PaperPreparation} +J.~W. Hagge and L.~L. Grigsby, +\newblock ``Preparation of papers in a two-column format for ieee transactions + on energy conversion ieee transactions on power delivery ieee transactions on + power systems'', +\newblock in {\em IEEE Power Engineering Society Publication Guide}. IEEE Power + Engineering Society, January 1995. + +\end{thebibliography} +\end{filecontents} + + + +\begin{document} + +\def\today{\Filedate} +\newcommand\file{\textsf} +\newcommand\ag{\textsc} + + + +\maketitle + +{ +\parskip 0ex plus.2ex +\tableofcontents +\par +} + + +%\newpage +\begin{abstract} +\bfseries +This \LaTeXe\ package implements the layout requirements for +Transactions of the IEEE Power Engineering Society (PES). This covers +the Transactions on Energy Conversion (T-EC), Transactions on Power +Delivery (T-PWRD), Transactions on Power Systems (T-PWRS), and Special +Publications. Discussions and closures can also be generated in the +required form. + +This document is version \Fileversion, \Filedate, and describes +\Packageversion. + +Thanks are due to John Crequer for proof-reading an early version of the +documentation. +\end{abstract} + + + +\section{Introduction} + +This document comprises the documentation for the \LaTeXe\ package ieeepes, +which implements the layout for publications of the Power Engineering Society +(a branch of IEEE). It is assumed that the reader is familiar with a standard +\LaTeX\ setup. Only new commands implemented by ieeepes are described in this +document. This document by itself is by now means sufficient in describing the +requirements to papers for submission to the IEEE PES. The +specifications~\cite{IEEEPES_PaperPreparation} must still be consulted. +Wherever possible, ieeepes enforces any requirements, but there are limits to +what can be done. Refer to section~\ref{s:cantdo} for a list of limitations of +ieeepes. Every author should be particularly careful with these. + +Provided with ieeepes are the files \file{ieeepes\_skel.tex}, a skeleton for +new papers which might be useful, and \file{ieeepes\_check.tex}, a document +exercising the various features of ieeepes and intended as a test. It is also +useful as example. + +This documentation can be compiled with standard \LaTeX, but the check file +needs ieeepes to be installed, and \file{ieeepes\_check.bib} to be available. + +ieeepes requires \LaTeXe\ version 1998/06/01. It will probably work +with older versions of \LaTeXe, however this has not been tested. It +will not work with \LaTeX\ 2.09. + +Please report any problems to Volker Kuhlmann\footnote + {\textbf{v.kuhlmann@elec.canterbury.ac.nz}}% +, and I will do my best to fix them. + + + +\section{Installation} +\label{s:installation} + +The file \file{ieeepes.sty} must be copied into a directory where \TeX\ looks +for input files. The file \file{ieeepes.bst} must be copied into a directory +where \BibTeX\ looks for \BibTeX\ styles. The exact location of these +directories is dependant on the particular platform used and can not be +discussed here. Refer to the documentation of your \LaTeX\ software. + +Package ieeepes requires package vmargin. Refer to section~\ref{s:options} for +other requirements. All the software mentioned can be downloaded from any +CTAN\footnote + {Comprehensive TeX Archive Network. + Try \textbf{ftp://ftp.dante.de/} or \textbf{http://www.dante.de/}.} +host. A copy of package vmargin is included for your convenience, +\file{vmargin.sty} should be installed in the same place as \file{ieeepes.sty}. + + + +\section{Changes from older Versions} +\label{s:changes} + +It is now necessary to use |\maketitle|. The \LaTeXe\ user interface changed, +and ieeepes can no longer use the |\AtBeginDocument| hook to insert the page +title. A warning is displayed if |\maketitle| is not used. + +Using a reserved filename for the image file in the |biography| environment +suppresses the author image for this instance only. See +section~\ref{s:biographies}. + + + +\section{Options to the Package} +\label{s:options} + +The following options will be recognised by the ieeepes package: + +\begin{description} +\item{\textbf{draft}}: + Print page numbers. This violates requirements, but is very useful + while writing the paper. This also enables markers which can be used to + determine a useful width for a |minipage| (section~\ref{s:figtab}). Do + not use this for the final version. + +\item{\textbf{psphotos}}: + A photographic image of the author can be printed into the + space which is reserved for this. See + section~\ref{s:biographies} for further details. + + This option requires the graphics bundle to be installed, as the + graphicx package is loaded. The graphics bundle can be obtained from + any CTAN host (see section~\ref{s:installation}). + +\item{\textbf{photofit}}: + This option will scale the photographic image of the author in + the biography in both directions so that the image fills up the + space provided. If the image had the required aspect ratio, + this scaling will have no effect. If the aspect ratio was not + as required, the image will be slightly distorted. However, + this distortion might be less visible than an image which does + not ``fit'' the space. Also see section~\ref{s:biographies}. + +\item{\textbf{PStimes}}: + Use font PostScript Times for the main document font. + Typesetting mathematics is shifted over to PostScript fonts as + much as possible without using commercial fonts. + + This option requires the psnfss bundle to be installed. The psnfss + bundle can be obtained from any CTAN host (see + section~\ref{s:installation}). Packages times and mathptm are loaded. + +\item{\textbf{noieeebox}}: + This option suppresses the empty box at the bottom of the left + column of the title page. I added this option because someone + had a purpose for it. + + Do not use this option for papers submitted to the IEEE PES! + +\item{\textbf{puttoc}}: + Put a table of contents into the paper, which is useful while writing + the paper, but do not use this for the final version! This option has + no effect unless option draft is also used. + +\end{description} + + + +\section{Document Structure} + +The main structure of an IEEE PES document is as follows: + +\begin{verbatim} +\documentclass[10pt,...]{article} +\usepackage[...]{ieeepes} +\title{...} +\author{... \and ... \and ...} +\begin{document} +\maketitle +\begin{abstract} +... +\end{abstract} +... +\end{document} +\end{verbatim} + +The point size must be 10pt (which is the default). Do not use any of +the paper size options for the class, because the paper size is set up +by the ieeepes package. + +The syntax for |\title| and |\author| is as for standard \LaTeX. There +can be any number of authors (separated by |\and|), but they all have +to fit next to each other on the width of the paper. No overfull +warning is generated if the author names overlap, or extend into the +margin. Within the argument to |\author| lines can be separated by +|\\|. + +If the space available does not fit all the authors, other solutions +must be found. The standard \LaTeX\ command |\parbox| and environments +minipage and tabular might be useful, but |\and| probably is not. The +argument to |\author| is inside a tabular environment. + +The standard \LaTeX\ commands |\tableofcontents| is not necessary and has been +disabled. It is now necessary to use |\maketitle| at the beginning of the +document. The use of \LaTeX's |\appendix| command might lead to papers not +meeting the requirements. + +The text of the abstract is enclosed in the abstract environment, which +follows the |\begin{document}| and the |\maketitle|. + +The sectioning commands |\section|, |\subsection|, and |\subsubsection| +are available, but |\paragraph| and |\subparagraph| can not be used in +IEEE PES papers. + +Strictly speaking, the title text for |\section| should be all upper +case, but this can not always be accomplished easily. Currently it is +set in small caps. If this is not desired, entering the text in capitals +will have the desired result. + +When the text of the paper is finished, the two columns on the last page must +be justified manually by inserting a |\columnbreak| at the correct position. +This should put the text on the last page equally into the two column. +Automation of this is tricky and left for a future version (if not left out). + + + +\section{Paper Sizes} + +Printing can be done on either A4 or USletter paper, there is no +difference for the resulting camera ready copy. Refer +to~\cite{IEEEPES_PaperPreparation} when using A4 paper, for cutting the +paper after printing. + +When using dvips for generating PostScript code for printing, the +default paper size for which dvips generates code can be overridden with +the \textbf{-t} option: \textbf{-t letter} for USletter paper, and +\textbf{-t a4} for A4 paper. This might help to keep the printer happy. + + + +\section{PostScript Fonts} + +Package option PStimes switches the text font and as much math as +possible to PostScript Times (see section~\ref{s:options}). There are +no complete mathematical fonts in the public domain, if these are +desired then they must be purchased. Do not use option PStimes for +selecting purchased fonts. + + + +\section{Figures and Tables} +\label{s:figtab} + +Figures and tables are used exactly as before, except that their +contents is now centred by default. Care must be taken with table +captions, which have to be inserted \emph{before} the table. +Example: + +\begin{verbatim} +\begin{table} +\caption{Table caption text.} +\label{label name} + The table matter goes here. +\end{table} +\end{verbatim} + +As always with \LaTeX, the |\label| must be after the |\caption|, and +inside the figure or table environments. + +The new environments |Table| and |Figure| have been introduced to make figures +and tables easier to handle. Use of these environments is recommended because +they take care of a few things which otherwise would have to be done manually +(e.g.\ the caption position). Their syntax is: + +\begin{verbatim} +\begin{Table}[FLOATPLACE]{LABEL}% + [TOC CAPTION]{CAPTION} + The table matter goes here. +\end{Table} +\end{verbatim} + +Arguments in square brackets are optional and can be left out, those in braces +are required. \ag{floatplace} is the float placement parameter, and +\ag{toc caption} is the caption for the table of contents if they have been +enabled with the package options draft and puttoc. \ag{toc caption} +defaults to \ag{caption}. + +|Figure| has the same syntax as |Table|. + +The width of the caption is held in |\capwidth|, and is initialised to +|0.8\columnwidth|. + +Reference figures with |\figref|, and tables with |\tabref|. Their +syntax is equal to |\ref|. Use these two new reference commands within +as well as at the beginning of a sentence, and do not write out +``figure'', ``table'', or something to this effect. Do not use |\ref| +for figures or tables. Example: + +\begin{verbatim} + is shown in \tabref{table1} + and \figref{figure2}. +\end{verbatim} + +Footnotes can be used within tables. For this the table must be put +inside a minipage environment. The problem with this is that the width +of the minipage must be specified before the width of the contents can +be known. When writing the paper, specify the width as |1\columnwidth|, +and when finished, step by step reduce the width of the minipage (by +reducing the |1|) to the width of the table produced by tabular. + +To aid with this, markers can be printed which show the extent of the +tabular and the minipage. Ideally, the two arrows facing the same +direction are horizontally aligned. The markers are generated by +|\Lhighlight| and |\Rhighlight|, they do not take up any space and are +only displayed when option draft is in effect. |\Lhighlight| and +|\Rhighlight| are equivalent to |\mbox{}|. + +\begin{verbatim} +\begin{table} +\caption{...} +\label{...} +\Lhighlight +\begin{minipage}{1\columnwidth} + \centering + \Lhighlight + \begin{tabular}{...} + Here can be footnotes. + \end{tabular} + \Rhighlight +\end{minipage}% <--!! +\Rhighlight +\end{table} +\end{verbatim} + +Note the \% sign after |\end{minipage}|, which ensures that there is no white +space between the minipage and the arrow produced by the following +|\Rhighlight|. Refer to file \file{ieeepes\_check.tex} for an example. + + + +\section{Equations} +\label{s:equations} + +Equations are used in the same way as described in the \LaTeX\ manual. + +For referencing equations, use |\equref| within a sentence, and +|\Equref| at the beginning of a sentence. The syntax is the same as for +|\ref|. Do not spell out ``Eq.'', ``equation'', or anything similar. +Using these two commands will keep your paper in line with requirements. + + + +\section{Footnotes} +\label{s:footnotes} + +There are no changes to the standard \LaTeX\ use of footnotes. + + + +\section{Referencing} + +For figure and table references, see section~\ref{s:figtab}. For +equation references, see section~\ref{s:equations}. + + + +\section{Citations} +\label{s:citations} + +There are no changes in the use of the |\cite| command. Do not spell +out ``ref.'', ``reference'', or similar. + +For conference citations (\BibTeX\ entry type InProceedings) the +publication number (e.g. ``91CH3070-0'') is entered into the \BibTeX\ +note entry field. This will result in the number being printed after +the page number instead of before, as shown in the example +paper~\cite{IEEEPES_PaperPreparation}. Correction of this is left for a +future version of the ieeepes package. + +%The example paper~\cite{IEEEPES_PaperPreparation} + +The \BibTeX\ style ieeepes.bst was derived from ieee.bst found on CTAN. +The only changes made are the spelling out of the month names (as in +plain.bst), and the definition of the additional strings: +\textbf{ieeepes}, +\textbf{ieeetec}, +\textbf{ieeetpd}, +\textbf{ieeetps}, +yielding the respective texts ``IEEE Power Engineering Society'', and +the titles of the three transactions. + +A call to |\bibliographystyle| is performed by the ieeepes package, and +it is not necessary to use this command again. + +The bibliography supplied with the ieeepes package should be consulted +for an example of how to enter bibliographic data. + + + +\section{Biographies} +\label{s:biographies} + +A biography for each author of the paper can be typeset with the |biography| +environment. Space is reserved for the image, which is inserted by the +publisher photographically. Optionally, an encapsulated postscript image of the +author can be printed with the text. The general syntax is: +% +\begin{verbatim} +\begin{biography}{AUTHOR NAME}% + [UP SHIFT]{FILENAME} +\end{verbatim} +% +Substitute the name of the author for \ag{author name}. + +\ag{filename} is the name of the file containing the image of the author. +This argument can be empty and no image is printed. \ag{up shift} is +optional and is the amount by which the image is shifted up or down, +the default is 0\,mm. This parameter might be useful for certain aspect +ratios of the author's image. Package option psphotos is required for +printing author images, see section~\ref{s:options}. + +Using the reserved \ag{filename} |nophoto| will suppress the insertion of an +image altogether and will not reserve space for one, for this instance only. +This is useful if not all authors of a paper want to have an image appear in +the paper. + +Because of the use of the \TeX\ paragraph parameters |\hangindent| and +|\hangafter| to leave enough space for the photograph, it is vitally +important to have enough text material in the first paragraph of the +|biography| environment. Care should also be taken when the biography +starts close to the bottom of the column; if the photo does not fit +into the space left it will extend into the bottom margin. + +As many |biography| environments as needed can be used. + + + +\section{Summary} +\label{s:summary} + +A summary is started with the |\summary| command, which is used much in +the same way as |\appendix| from \LaTeX. A summary can be put into a +separate document: +% +\begin{verbatim} +\begin{document} +\summary + ... +\end{document} +\end{verbatim} +% +or appear at the end of the paper, before the |\end{document}|. + + + +\section{Discussions} +\label{s:discussions} + +The discussion environment is provided for typesetting discussions. The +syntax is: +% +\begin{verbatim} +\begin{discussion}{PAPER NUMBER}% + {PAPER TITLE}% + {AUTHOR NAMES}% + {DISCUSSER NAME}% + {AFFILIATION INCL ADDRESS}% + {SHORT AFFILIATION} +\end{verbatim} +% +enter the respective data. \ag{author names} are the authors of the paper, +\ag{discusser name} is the author of the discussion about the paper. The +next argument is the affiliation including a complete mailing address, +while the last argument is of the form ``\emph{University of \ldots, +town, country}''. + +The general document structure for a discussion is: +% +\begin{verbatim} +... +\begin{document} +\begin{discussion}{..... +.. text of discussion .. +\end{discussion} +\end{document} +\end{verbatim} +% +There can be multiple discussion environments, though this is not +of much use. + + + +\section{Closures} +\label{s:closures} + +Closures are written using the closure environment: +% +\begin{verbatim} +... +\begin{document} +\begin{closure}{AUTHOR NAME} +.. text of closure .. +\end{closure} +\end{document} +\end{verbatim} + +There can be multiple closure environments in one document, but again +this is not of much use. It is however possible to have a closure +environment at the end of a paper, following the biographies, or the +summary. This feature relies on an internal \LaTeX\ mechanism behaving +in a certain way, so caution is required. It works with the +example---but please report any problems. + + + +\section{What This Package Can Not Do} +\label{s:cantdo} + +There are a few things with which authors must take care themselves, +because they can not be enforced by \LaTeX. +Consult~\cite{IEEEPES_PaperPreparation} for details. Some are: + +Table captions must be inserted \emph{before} the table. See +section~\ref{s:figtab} for details. Better, use the |Table| environment. + +Commands provided for referencing figures, tables, and equations should +be used, and no additional words should be spelled out in the +sentence. + +Punctuation marks follow the |\cite| command. + +The main document point size must be 10pt. + +Use initials for the Christian names of authors in the |\author| +command. + +Ensure that there is enough material in the first paragraph of a biography +environment, and that the biography does not appear at the bottom of a page. + +Ensure the two columns on the last page are balanced. + + + +%\bibliographystyle{ieeepes} +%\bibliography{ieeepes_check} +% To remove the dependency on ieeepes.bst and ieeepes_check.bib for this +% document, the bibliography is copied into this file (see preamble, +% filecontents environment). +\bibliography{ieeepes_doc} + + + +\end{document} + +%% +%% EOF ieeepes_doc.tex +%%---------------------------------------------------------------------- |