summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/ieeepes/ieeepes_doc.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/ieeepes/ieeepes_doc.tex
Initial commit
Diffstat (limited to 'macros/latex/contrib/ieeepes/ieeepes_doc.tex')
-rw-r--r--macros/latex/contrib/ieeepes/ieeepes_doc.tex620
1 files changed, 620 insertions, 0 deletions
diff --git a/macros/latex/contrib/ieeepes/ieeepes_doc.tex b/macros/latex/contrib/ieeepes/ieeepes_doc.tex
new file mode 100644
index 0000000000..4476c860a1
--- /dev/null
+++ b/macros/latex/contrib/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
+%%----------------------------------------------------------------------