1 From aff23d05642705f738f788648c060085bdc476d6 Mon Sep 17 00:00:00 2001
2 From: Matteo Frigo <athena@fftw.org>
3 Date: Sun, 2 Jun 2013 09:05:50 -0400
4 Subject: [PATCH] Fix the manual to work with both texinfo-4 and texinfo-5.
6 Texinfo has been stable for the first 15 years of FFTW's history.
7 Then some genius, with too much time in his hands and on a mission to
8 deliver the world from the evil of the C language, decided to rewrite
9 makeinfo in Perl, the old C version of makeinfo being, as I said,
10 evil. The official excuse for the rewrite was that now I can have my
11 manual in XML format, as if XML were a feature.
13 The result of this stroke of genius is that texinfo-5 has different
14 rules for macro expansion than texinfo-4 does, specifically regarding
15 whether or not spaces after a macro are ignored. Texinfo-4 had weird
16 rules, but at least they were constant and internally more or less
17 consistent. Texinfo-5 has different rules, and even worse the rules
18 in texinfo-5 are inconsistent between the TeX and HTML output
19 processors. This situation makes it almost impossible for us to
20 produce a manual that works with both texinfo 4 and 5 in all modes
21 (TeX, info, and html). The @noindent/@refill hack is my best shot at
22 patching this situation.
24 doc/fftw3.texi | 72 +++++++++++++++++++++++++++++++++++++++++++++++--
25 doc/install.texi | 8 +++---
26 doc/legacy-fortran.texi | 10 +++----
27 doc/modern-fortran.texi | 22 +++++++--------
28 doc/mpi.texi | 58 +++++++++++++++++++--------------------
29 doc/other.texi | 18 ++++++-------
30 doc/reference.texi | 72 ++++++++++++++++++++++++-------------------------
31 doc/threads.texi | 8 +++---
32 doc/tutorial.texi | 16 +++++------
33 10 files changed, 180 insertions(+), 108 deletions(-)
35 diff --git a/doc/fftw3.texi b/doc/fftw3.texi
36 index 0465c06..0b7af92 100644
40 @parskip=@medskipamount
44 +@c The following macros are coded in a weird way:
52 +@c The @noindent/@refill stuff is not necessary in texinfo up to version
53 +@c 4, but it is a hack necessary to make texinfo-5 work.
55 +@c Texinfo has been stable for the first 15 years of FFTW's history.
56 +@c Then some genius, with too much time in his hands and on a mission to
57 +@c deliver the world from the evil of the C language, decided to rewrite
58 +@c makeinfo in Perl, the old C version of makeinfo being, as I said,
59 +@c evil. The official excuse for the rewrite was that now I can have my
60 +@c manual in XML format, as if XML were a feature.
62 +@c The result of this stroke of genius is that texinfo-5 has different
63 +@c rules for macro expansion than texinfo-4 does, specifically regarding
64 +@c whether or not spaces after a macro are ignored. Texinfo-4 had weird
65 +@c rules, but at least they were constant and internally more or less
66 +@c consistent. Texinfo-5 has different rules, and even worse the rules
67 +@c in texinfo-5 are inconsistent between the TeX and HTML output
68 +@c processors. This situation makes it almost impossible for us to
69 +@c produce a manual that works with both texinfo 4 and 5 in all modes
70 +@c (TeX, info, and html). The @noindent/@refill hack is my best shot at
71 +@c patching this situation.
73 +@c "@noindent" has two effects: First, it makes texinfo-5 believe that
74 +@c the next "@ifinfo" is on a new line, otherwise texinfo-5 complains
75 +@c that it is not (even though it obviously is). Second, "@noindent" is
76 +@c a macro that eats extra space, and we want this effect because somehow
77 +@c macro expansion in texinfo-5 inserts extra spaces that were not there
80 +@c "@refill" stops texinfo-5 from interpreting the rest of the line after
81 +@c a macro invocation as an argument to "@end tex". For example, in
82 +@c "FFTW uses @Onlogn algorithms", somehow texinfo-5 thinks that
83 +@c "algorithms" is an argument to "@end tex". "@noindent" would have the
84 +@c same effect (as would any other macro invocation, I think), but,
85 +@c unlike "@noindent", "@refill" does not eat spaces and does not scan
86 +@c the rest of the input file for macro arguments. However, "@refill" is
87 +@c deemed "obsolete" in the texinfo-5 source code, so expect this to
88 +@c break at some point.
90 +@c This situation is wholly unsatisfactory, and the GNU project is
91 +@c obviously out of control. If this nonsense persists, we will abandon
92 +@c texinfo and produce a latex-only version of the manual.
100 @@ -36,9 +89,11 @@ O(n log n)
110 n[0] x n[1] x n[2] x ... x n[d-1]
112 @@ -48,9 +103,11 @@ n<sub>0</sub> × n<sub>1</sub> × n<sub>2</sub>&nb
114 $n_0 \\times n_1 \\times n_2 \\times \\cdots \\times n_{d-1}$
122 n[0] x n[1] x n[2] x ... x (n[d-1]/2 + 1)
124 @@ -60,9 +117,11 @@ n<sub>0</sub> × n<sub>1</sub> × n<sub>2</sub>&nb
126 $n_0 \\times n_1 \\times n_2 \\times \\cdots \\times (n_{d-1}/2 + 1)$
134 n[0] x n[1] x n[2] x ... x [2 (n[d-1]/2 + 1)]
136 @@ -72,9 +131,11 @@ n<sub>0</sub> × n<sub>1</sub> × n<sub>2</sub>&nb
138 $n_0 \\times n_1 \\times n_2 \\times \\cdots \\times [2(n_{d-1}/2 + 1)]$
143 @macro twodims{d1, d2}
148 @@ -84,9 +145,11 @@ $n_0 \\times n_1 \\times n_2 \\times \\cdots \\times [2(n_{d-1}/2 + 1)]$
155 @macro threedims{d1, d2, d3}
160 @@ -96,9 +159,11 @@ $\d1\ \\times \d2\$
162 $\d1\ \\times \d2\ \\times \d3\$
172 @@ -108,10 +173,12 @@ n<sub>\k\</sub>
183 n[1] x n[0] x n[2] x ... x n[d-1]
185 @@ -121,6 +188,7 @@ n<sub>1</sub> × n<sub>0</sub> × n<sub>2</sub>&nb
187 $n_1 \\times n_0 \\times n_2 \\times \\cdots \\times n_{d-1}$
193 @@ -156,8 +224,8 @@ approved by the Free Software Foundation.
196 @subtitle for version @value{VERSION}, @value{UPDATED}
197 -@author{Matteo Frigo}
198 -@author{Steven G. Johnson}
199 +@author Matteo Frigo
200 +@author Steven G. Johnson
202 @vskip 0pt plus 1filll
204 diff --git a/doc/install.texi b/doc/install.texi
205 index e7fd9dd..02d5b1e 100644
206 --- a/doc/install.texi
207 +++ b/doc/install.texi
208 @@ -33,10 +33,10 @@ efficiently by the standard FFTW distribution.
212 -* Installation on Unix::
213 -* Installation on non-Unix systems::
215 -* Generating your own code::
216 +* Installation on Unix::
217 +* Installation on non-Unix systems::
219 +* Generating your own code::
222 @c ------------------------------------------------------------
223 diff --git a/doc/legacy-fortran.texi b/doc/legacy-fortran.texi
224 index b7013dd..7ae6142 100644
225 --- a/doc/legacy-fortran.texi
226 +++ b/doc/legacy-fortran.texi
227 @@ -26,11 +26,11 @@ The MPI parallel interface to FFTW is @emph{not} currently available
231 -* Fortran-interface routines::
232 -* FFTW Constants in Fortran::
233 -* FFTW Execution in Fortran::
234 -* Fortran Examples::
235 -* Wisdom of Fortran?::
236 +* Fortran-interface routines::
237 +* FFTW Constants in Fortran::
238 +* FFTW Execution in Fortran::
239 +* Fortran Examples::
240 +* Wisdom of Fortran?::
243 @c -------------------------------------------------------
244 diff --git a/doc/modern-fortran.texi b/doc/modern-fortran.texi
245 index 4a2cf44..cad11fd 100644
246 --- a/doc/modern-fortran.texi
247 +++ b/doc/modern-fortran.texi
248 @@ -20,13 +20,13 @@ few subtle points such as memory allocation, wisdom, and data types
249 that deserve closer attention.
252 -* Overview of Fortran interface::
253 -* Reversing array dimensions::
254 -* FFTW Fortran type reference::
255 -* Plan execution in Fortran::
256 -* Allocating aligned memory in Fortran::
257 -* Accessing the wisdom API from Fortran::
258 -* Defining an FFTW module::
259 +* Overview of Fortran interface::
260 +* Reversing array dimensions::
261 +* FFTW Fortran type reference::
262 +* Plan execution in Fortran::
263 +* Allocating aligned memory in Fortran::
264 +* Accessing the wisdom API from Fortran::
265 +* Defining an FFTW module::
268 @c -------------------------------------------------------
269 @@ -124,7 +124,7 @@ Multiple planner flags are combined with @code{ior} (equivalent to @samp{|} in C
273 -* Extended and quadruple precision in Fortran::
274 +* Extended and quadruple precision in Fortran::
277 @node Extended and quadruple precision in Fortran, , Overview of Fortran interface, Overview of Fortran interface
278 @@ -532,9 +532,9 @@ from Fortran, however, because of differences in file I/O and string
279 types between C and Fortran.
282 -* Wisdom File Export/Import from Fortran::
283 -* Wisdom String Export/Import from Fortran::
284 -* Wisdom Generic Export/Import from Fortran::
285 +* Wisdom File Export/Import from Fortran::
286 +* Wisdom String Export/Import from Fortran::
287 +* Wisdom Generic Export/Import from Fortran::
291 diff --git a/doc/mpi.texi b/doc/mpi.texi
292 index 1b976d4..6f4ac38 100644
295 @@ -45,19 +45,19 @@ of the serial (uniprocessor) FFTW, and focus only on the concepts new
296 to the MPI interface.
299 -* FFTW MPI Installation::
300 -* Linking and Initializing MPI FFTW::
302 -* MPI Data Distribution::
303 -* Multi-dimensional MPI DFTs of Real Data::
304 -* Other Multi-dimensional Real-data MPI Transforms::
305 -* FFTW MPI Transposes::
307 -* Avoiding MPI Deadlocks::
308 -* FFTW MPI Performance Tips::
309 -* Combining MPI and Threads::
310 -* FFTW MPI Reference::
311 -* FFTW MPI Fortran Interface::
312 +* FFTW MPI Installation::
313 +* Linking and Initializing MPI FFTW::
315 +* MPI Data Distribution::
316 +* Multi-dimensional MPI DFTs of Real Data::
317 +* Other Multi-dimensional Real-data MPI Transforms::
318 +* FFTW MPI Transposes::
320 +* Avoiding MPI Deadlocks::
321 +* FFTW MPI Performance Tips::
322 +* Combining MPI and Threads::
323 +* FFTW MPI Reference::
324 +* FFTW MPI Fortran Interface::
327 @c ------------------------------------------------------------
328 @@ -298,10 +298,10 @@ for these intermediate steps and tell you the correct amount to
332 -* Basic and advanced distribution interfaces::
334 -* Transposed distributions::
335 -* One-dimensional distributions::
336 +* Basic and advanced distribution interfaces::
338 +* Transposed distributions::
339 +* One-dimensional distributions::
342 @node Basic and advanced distribution interfaces, Load balancing, MPI Data Distribution, MPI Data Distribution
343 @@ -745,9 +745,9 @@ uses besides FFTs, FFTW's transpose routines can be called directly,
344 as documented in this section.
347 -* Basic distributed-transpose interface::
348 -* Advanced distributed-transpose interface::
349 -* An improved replacement for MPI_Alltoall::
350 +* Basic distributed-transpose interface::
351 +* Advanced distributed-transpose interface::
352 +* An improved replacement for MPI_Alltoall::
355 @node Basic distributed-transpose interface, Advanced distributed-transpose interface, FFTW MPI Transposes, FFTW MPI Transposes
356 @@ -1135,12 +1135,12 @@ datatypes, and constants. See also @ref{FFTW Reference} for information
357 on functions and types in common with the serial interface.
360 -* MPI Files and Data Types::
361 -* MPI Initialization::
363 -* MPI Data Distribution Functions::
364 -* MPI Plan Creation::
365 -* MPI Wisdom Communication::
366 +* MPI Files and Data Types::
367 +* MPI Initialization::
369 +* MPI Data Distribution Functions::
370 +* MPI Plan Creation::
371 +* MPI Wisdom Communication::
374 @node MPI Files and Data Types, MPI Initialization, FFTW MPI Reference, FFTW MPI Reference
375 @@ -1296,9 +1296,9 @@ first dimension of an @ndims{} array that is stored on the local
376 process. @xref{Basic and advanced distribution interfaces}. For
377 @code{FFTW_MPI_TRANSPOSED_OUT} plans, the @samp{_transposed} variants
378 are useful in order to also return the local portion of the first
379 -dimension in the @ndimstrans{} transposed output. @xref{Transposed
380 -distributions}. The advanced interface for multidimensional
382 +dimension in the @ndimstrans{} transposed output.
383 +@xref{Transposed distributions}.
384 +The advanced interface for multidimensional transforms is:
386 @cindex advanced interface
387 @findex fftw_mpi_local_size_many
388 diff --git a/doc/other.texi b/doc/other.texi
389 index 55c6f75..962f6ee 100644
393 @node Other Important Topics, FFTW Reference, Tutorial, Top
394 @chapter Other Important Topics
396 -* SIMD alignment and fftw_malloc::
397 -* Multi-dimensional Array Format::
398 -* Words of Wisdom-Saving Plans::
399 -* Caveats in Using Wisdom::
400 +* SIMD alignment and fftw_malloc::
401 +* Multi-dimensional Array Format::
402 +* Words of Wisdom-Saving Plans::
403 +* Caveats in Using Wisdom::
406 @c ------------------------------------------------------------
407 @@ -74,11 +74,11 @@ was necessary. Since several different formats are common, this topic
408 is often a source of confusion.
411 -* Row-major Format::
412 -* Column-major Format::
413 -* Fixed-size Arrays in C::
414 -* Dynamic Arrays in C::
415 -* Dynamic Arrays in C-The Wrong Way::
416 +* Row-major Format::
417 +* Column-major Format::
418 +* Fixed-size Arrays in C::
419 +* Dynamic Arrays in C::
420 +* Dynamic Arrays in C-The Wrong Way::
424 diff --git a/doc/reference.texi b/doc/reference.texi
425 index 0381e9a..19343e6 100644
426 --- a/doc/reference.texi
427 +++ b/doc/reference.texi
428 @@ -6,14 +6,14 @@ one-processor) FFTW functions. Parallel transforms are described in
432 -* Data Types and Files::
435 -* Advanced Interface::
437 -* New-array Execute Functions::
439 -* What FFTW Really Computes::
440 +* Data Types and Files::
443 +* Advanced Interface::
445 +* New-array Execute Functions::
447 +* What FFTW Really Computes::
450 @c ------------------------------------------------------------
451 @@ -30,9 +30,9 @@ You must also link to the FFTW library. On Unix, this
452 means adding @code{-lfftw3 -lm} at the @emph{end} of the link command.
457 -* Memory Allocation::
460 +* Memory Allocation::
464 @@ -298,12 +298,12 @@ multiplicities, and strides. This section describes the the basic
465 interface, which we expect to satisfy the needs of most users.
471 -* Real-data DFT Array Format::
472 -* Real-to-Real Transforms::
473 -* Real-to-Real Transform Kinds::
477 +* Real-data DFT Array Format::
478 +* Real-to-Real Transforms::
479 +* Real-to-Real Transform Kinds::
483 @@ -985,9 +985,9 @@ the same fashion as in the basic interface, and the resulting
484 @code{fftw_plan} is used in the same way (@pxref{Using Plans}).
487 -* Advanced Complex DFTs::
488 -* Advanced Real-data DFTs::
489 -* Advanced Real-to-real Transforms::
490 +* Advanced Complex DFTs::
491 +* Advanced Real-data DFTs::
492 +* Advanced Real-to-real Transforms::
496 @@ -1186,12 +1186,12 @@ important that they pay special attention to the documentation lest they
497 shoot themselves in the foot.
500 -* Interleaved and split arrays::
501 -* Guru vector and transform sizes::
502 -* Guru Complex DFTs::
503 -* Guru Real-data DFTs::
504 -* Guru Real-to-real Transforms::
505 -* 64-bit Guru Interface::
506 +* Interleaved and split arrays::
507 +* Guru vector and transform sizes::
508 +* Guru Complex DFTs::
509 +* Guru Real-data DFTs::
510 +* Guru Real-to-real Transforms::
511 +* 64-bit Guru Interface::
515 @@ -1664,10 +1664,10 @@ This section documents the FFTW mechanism for saving and restoring
516 plans from disk. This mechanism is called @dfn{wisdom}.
521 -* Forgetting Wisdom::
522 -* Wisdom Utilities::
525 +* Forgetting Wisdom::
526 +* Wisdom Utilities::
530 @@ -1825,12 +1825,12 @@ one-dimensional (1d) transform definitions, and then give the
531 straightforward extension to multi-dimensional transforms.
534 -* The 1d Discrete Fourier Transform (DFT)::
535 -* The 1d Real-data DFT::
536 -* 1d Real-even DFTs (DCTs)::
537 -* 1d Real-odd DFTs (DSTs)::
538 -* 1d Discrete Hartley Transforms (DHTs)::
539 -* Multi-dimensional Transforms::
540 +* The 1d Discrete Fourier Transform (DFT)::
541 +* The 1d Real-data DFT::
542 +* 1d Real-even DFTs (DCTs)::
543 +* 1d Real-odd DFTs (DSTs)::
544 +* 1d Discrete Hartley Transforms (DHTs)::
545 +* Multi-dimensional Transforms::
549 diff --git a/doc/threads.texi b/doc/threads.texi
550 index e5047c3..ebf9d5f 100644
551 --- a/doc/threads.texi
552 +++ b/doc/threads.texi
553 @@ -26,10 +26,10 @@ threads if your problem is sufficiently large.
557 -* Installation and Supported Hardware/Software::
558 -* Usage of Multi-threaded FFTW::
559 -* How Many Threads to Use?::
561 +* Installation and Supported Hardware/Software::
562 +* Usage of Multi-threaded FFTW::
563 +* How Many Threads to Use?::
567 @c ------------------------------------------------------------
568 diff --git a/doc/tutorial.texi b/doc/tutorial.texi
569 index 5763275..f04dd6b 100644
570 --- a/doc/tutorial.texi
571 +++ b/doc/tutorial.texi
573 @node Tutorial, Other Important Topics, Introduction, Top
576 -* Complex One-Dimensional DFTs::
577 -* Complex Multi-Dimensional DFTs::
578 -* One-Dimensional DFTs of Real Data::
579 -* Multi-Dimensional DFTs of Real Data::
580 -* More DFTs of Real Data::
581 +* Complex One-Dimensional DFTs::
582 +* Complex Multi-Dimensional DFTs::
583 +* One-Dimensional DFTs of Real Data::
584 +* Multi-Dimensional DFTs of Real Data::
585 +* More DFTs of Real Data::
588 This chapter describes the basic usage of FFTW, i.e., how to compute
589 @@ -514,9 +514,9 @@ complex transforms.)
590 @node More DFTs of Real Data, , Multi-Dimensional DFTs of Real Data, Tutorial
591 @section More DFTs of Real Data
593 -* The Halfcomplex-format DFT::
594 -* Real even/odd DFTs (cosine/sine transforms)::
595 -* The Discrete Hartley Transform::
596 +* The Halfcomplex-format DFT::
597 +* Real even/odd DFTs (cosine/sine transforms)::
598 +* The Discrete Hartley Transform::
601 FFTW supports several other transform types via a unified @dfn{r2r}