summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/ieeepes/ieeepes_doc.tex
blob: 4476c860a13ce74f8ab92cf3068e0b99484c7abd (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
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
%%----------------------------------------------------------------------