FITS 4.0 language-editing summary

latexdiff postscript differences

between approved standard and Aug 2017 M.Currie's edits (diff1.ps) (diff1.pdf)

between Aug 2017 M.Currie's and Dec 2017 L.Chiappetti's edits (diff2.ps) (diff2.pdf)
diff2 should correspond to the items marked magenta fixed
pending items were indicated in red

between Dec 2017 L.Chiappetti's and M.Currie's/joint 18 June 2018 edits (diff3.ps) (diff3.pdf)
items which were red in the previous stage and were fixed are in dark red marked OK
items still pending, or arisen in the latter stage are indicated in medium red
they were all fixed

between M.Currie's/joint 18 June 2018 and Jun21 version edits (diff4.ps) (diff4.pdf)
this was missing some edits applied by Bill Pence in Dec 2017, recovered in final version and listed with the rest below.

between M.Currie's/joint 21 June 2018 and Jun 22 final version edits (diff5.ps) (diff5.pdf)

between approved standard and Jun 22 final version edits (diff9.ps) (diff9a.pdf, truncated at pag.69) (diff9.pdf, complete but no ToC)
All the above was submitted to IAUFWG for comments on Jul 25. After that we processed the comments received, corrected some typos, and improved the uniformity of usage of LaTeX macros. What follows are final difference files:
between Jun 22 final version and the very last final version (diff8.ps) (diff8.pdf)
between approved standard and the very last final version edits (diff99.ps) (diff99a.pdf, truncated at pag.69) (diff99.pdf, complete but no ToC)
The "very last final" is the one submitted to the call for vote on Jul 20

Note formatting of latexdiff is not always perfect. For instance in very few cases it fails to compare formulae (so to prevent LaTeX loops the formula is replaced by a placeholder in the diff file and the comparison is done by eye on the original documents). Also the formatting of tables in latexdiff output is sometimes awkward. And of course latexdiff output may indicate differences between things which look the same, because the same result is achieved using different LateX macros.
Also in some cases the Postscript (.ps) diff is complete, while the PDF diff is not (if generated with psd2pdf might be truncated, if generated with pdflatex might be missing the ToC and cross-references since it should be run twice and the second run takes ages).
In case of doubts compare the actual document PDF or the latex sources.

Item 2016 approved standard Jun 22 Language edited version Jul 20 "very last final"language edited version

LaTeX source fits_standard40aa.tex fits_standard40aa-finalmerging.tex fits_standard40aa-last.tex

PDF document fits_standard40aa.pdf fits_standard40aa-finalmerging.pdf fits_standard40aa-last.pdf

Item	2016 approved standard	Jun 22 Language edited version	Jul 20 "very last final"language edited version
LaTeX source	fits_standard40aa.tex	fits_standard40aa-finalmerging.tex	fits_standard40aa-last.tex
PDF document	fits_standard40aa.pdf	fits_standard40aa-finalmerging.pdf	fits_standard40aa-last.pdf

Note line numbers refer to the first edit (Aug 2017) latex source, unless marked as "new" in which case they refer to the 18 Jun 2018 latex source (penultimate).

The edits have been applied to the entire LaTeX source including:

the bulk of the used Standard
the part used for the A&A publication of the FITS 3.0 Standard (A&A 524 A42), even if that is no longer up to date w.r.t. FITS 4.0
commented parts of the LaTeX source not currently used
C-code comments (now reverted back to original)
Appendix G (which should be extracted verbatim from RFC 4047)
is this a problem ? according to RFC 4047 coauthors, no problem

LaTeX macros

A few unused LaTeX macros have been removed from the LaTeX source, and a larger number of new macros have been added and are now used systematically. They are listed here as a guide for future authors:

Latest version includes "instruction for authors" as LaTeX comments in the preamble, as well as a summary of edits in appendix H.4.
typo "simliar" at new line 119 (in such comments) fixed
why did you remove the blue line on language edit at end of tab 2 (after new 572) fixed
the language editing part of appendix H (H4) was misplaced in appendix L1 now OK
LaTeX tables are now formatted in the LaTeX source in an easily-readable way
\kwd{KWDNAME} produces KWDNAME in \tt font, and must be used for the names of all (non-indexed) keywords.
fixed at 1890 OK
why word "ephemerides" is a \kwd at 6041 (caption table tab:SSEphem) new 6090 fixed
\keyw{KWDNAME} looks the same as \kwd NOW OK only \kwd
\indxkw{KWDNM}{i} produces KWDNMi for indexed keywords with name root in \tt font and variable indices in italics (e.g. NAXISn)
Note that the index i shall be described in text as $i$ , not {\tt i}, or i=1-99 as $i = $ 1-99.
\column{COLNAME} produces COLNAME in \tt font, and must be used for the names of table columns.
fixed at 6534 \kwd{ZBLANK} should be \column{ZBLANK} OK
\keyv{value} produces value in \tt font, and must be used for keyword values instead of \texttt or \verb. Exceptions are full keyword records for which the \kwd=\keyv notation is too heavy (particularly when one wants to show the blank spaces in the keyword record)
fixed at 5703 OK
check new lines 4261 4272 4281 for construct \indxkw{TFORM}{n}\texttt{= 'rA'} or alike Should it be\indxkw{TFORM}{n}=\keyv{'rA'} or alike ? now such construct used systematically
however in several places \texttt{T} or \texttt{F} is used for logical values, which is considered acceptable now almost all replaced by \keyv
but there are places where the logical values T or F are incorrectly presented as strings 'T' or 'F'. Fixed at 6389-90, 6449, 6695-6 all OK
leftover \texttt T or F instead of \keyv at new 4100-01 4275-76 OK as it is
new 2323 why \texttt replaced with url ? we do not want to provide a specific link here ! fixed
fixed at 6587, 6590, 6593 \kwd shall be \keyv all OK
Note that a string values shall include the enclosing quotes, e.g. \keyv{'FK4'}, while for numeric values one uses e.g. \keyv{8}.
check \keyv{'xxx'} vs \keyv{`xxx'} which is correct ? the former, now used exclusively
same for \texttt{'xxx'} vs \texttt{`xxx'} ditto
\IMAGE, \TABLE and \BINTABLE produce the name of the standard extensions in \tt font (e..g. IMAGE).
Note that if further words follow the macro must be followed by a \ coded blank, which is not the case if a punctuation mark follows the macro, e.g.
"in the \IMAGE, \TABLE, and \BINTABLE\ standard extensions"
fixed at 7880 OK
\may, \must, \shall, \should, \optional, \recommended, \required, and the negated forms \mustnot, \notrecommended, \notrequired, \shallnot, \shouldnot produce italicized words (e,g. must) or locutions (e.g. must not) to indicate obligations or recommendations etc. according to RFC 2119.
Note that macros corresponding to verbal forms (e.g. may, must, shall) imply and include a blank space separating the modal verb from the following verb (e.g. \must be used results in must be used), while macros corresponding to adjectives, if further words follow the macro, must be followed by a \ coded blank, which is not the case if a punctuation mark follows the macro, e.g. an \optional\ value indicator results in an optional value indicator, but this is \optional. results in this is optional.
new lines 8115 8856 check why \\should with two slashes now fixed

fixed not recommended at 5942 OK
fixed optional at 897 OK
fixed should not at 8854 OK
fixed required at 1231 1863 1871 2769 3012 OK
there are many cases for: may, must, should, required, rcommended and a few for: not required and should not which are probably OK, common speech and not prescriptions general revision done by MJC
few cases of common speech for shall (including some already OK as {\em shall only}, similarly there are {\em strongly recommended} also OK

All these changes will be summarized in Appendix H with a collective description, like "systematic application of LaTeX macros for kewyord names and values, and for RFC 2119 expressions, according to instructions reported in the LaTeX source preamble".

Other LaTeX issues

the acronym FITS itself was systematically changed to macro \FITS.
fixed at 8831 OK
{\tt ...} and {\it ...} constructs were changed to \texttt{...} and {\textit{...}.
fixed at 5162, 8120, 8712 OK
\mathrm instead of \rm (also \mathtt)
minus zero -0 expressed as $-$0
-- becomes $-$ (in MJD definition)

Capitalization

Changes from lower case to upper case (or vv) are listed in order of first occurrence. They were applied systematically to all applicable occurrences (if more than one).

capitalized Version (where numbered}
capitalized Standard (when referring to the FITS standard doc)
Gzip instead of GZIP or gzip for the GNU algorithm.
bytes > Bytes (where appropriate)
column > Column (where appropriate)
parameter > Parameter (where appropriate)
field > Field (where appropriate)
data type > Data Type (where appropriate)
axis {\tt m} > Axis~\texttt{m}, axis 1 > Axis~1 etc.
fixed at 2833 OK
coordinate > Coordinate (where appropriate)
year > Year (where appropriate)
FITS Support Office website lowercase and single word website
# > Position (table 7 or 13 heading)
capitalized Solar System (NOT hyphenated)
Appendix > appendix (where unnumbered)
second (and following) words in section title lowercase (e.g. Data representation not Data Representation) (many cases in compression chapter)
capitalized Longitude only in tab. 21 footer
capitalized Intermediate Coordinate Axis/es and Pixel Axes
remains pixel axis/es in 4671 4919 4962: correct ? yes
lowercased universe (but in a book title)
lowercase initial of \items in \itemize list if terminated by ; not .
capitalized Unix
Solar System ephemeris (last word lowercased)
Phase lowercased
uppercased 1st word in footnotes e.g. Required in addition
lowercased and added article: Biased exponent > a biased exponent
capitalised Boolean

Other typographical issues

These too are listed in order of first occurrence (and may repeat as necessary).

Added commas in several places
Added a few non-breaking spaces (LaTeX tilde)
references to Sections indicated systematically as Sect.~\ref{...}, not Section nor Sect, and the space between Sect. and reference is a tilde ~ not a blank or an hardcoded blank \ . Use Sects.~\ref{...},~\ref{...} in lists of more sections.
fixed at 2301, 6339, 6714 OK
No labelled \ref references for "next section"
this loses hyperlinks e.g. at 1302 OK
Hardcoded all sections or appendices as symbolic labels
Colon becomes a full stop before a list or item list or verbatim text.
XYZ LBH coordinates italicized (9.2.3)
Footnotes with same text may appear once per page, and footnotemark revised accordingly

Rewording

Changes in wording are listed in order of first occurrence. They might be applied to more occurrences, if necessary or applicable (so not necessarily to all instances). Also a few typos fixed.

zeroes > zeros
that > which
font > typeface
n-dimension > n-dimensional
does not impose .. nor > neither imposes ... nor
This is followed in Sect.\ \ref{s:Units} with recommendations > Sect.~\ref{s:Units} offers recommendations (in Headers)
less than > fewer than
is no longer than 67 characters in length. > contains fewer than 68 characters.
added xref to iso04b at line 2574
reworded Table~\ref{ta:extunit} lists: additional units that are commonly used in astronomy.
added word: respectively to specify the minimum and maximum values (TLMIN TLMAX, twice)
reworded strings of five characters each > strings each comprising five characters
added words: This is expressed in the table header as shown below.
reworded define a bulk rotation > specify a bulk rotation
indexes > indices
added words: in which all of the time part \may be omitted (section ISO-8601)
added words "shown below" ibidem.
In time scale UTC > In the UTC time scale
fixed also "time scale GMT" at 5738 OK
tied to time scales ET and TDB > tied to the ET and TDB time scales
added words: specified by the following keyword (et sim., in more places)
see text > see the text
added words: three keywords specified below.
inserted words: not recommended if there is no entry
But > However
added word: in \textit{FITS} images and \BINTABLE\ extensions
uncompress > decompress (but uncompressed, sometimes)
with a single row > containing a single row
character > character string (in description of ZDATASUM)
are composed of > comprise (in sect:VLAcols)
i.e.: > as depicted below. (in PLIO)
followed by > and finally (in H-Compress algorithm)
alphabetized > alphabetical
like \ref{sect:Celestkw} > such as Sect.~\ref{sect:Celestkw}
since 1994 > during 1994 (twice, once also 1993)
added word concern the following.
or reworded concern > are listed below
fixed at 8337 "concern are as follows" does not make sense
Similar fix at 8355 but is commented out OK
since 1996 > from 1996
added caption label to figure ascii.ps

Small numbers in letters

In all occurrences that a small number (1-9) was expressed in figures, it has been changed into letters (unless not required by context, e.g. 8-, 16- and 32-bit). First occurrence listed, but may apply to more cases. In some cases involves also an hyphenation change (see further below).

nine-track magnetic tape (not 9)
eight-bit bytes/characters (not 8) also 8 > eight
fixed at 2695, 4093, 6485 OK per context
seven-bit ASCII (not 7)
five-element contiguous array (not 5)
four-digit-year date (not 4)
three currently defined (not 3)
two-byte (16-bit) integer value (not 2)
also 2nd byte > second byte
one-bit sign (not 1)

Hyphenation

Compound phrases of more than 2 elements are hyphenated to highlight the correct grouping of the components. But for the three FITS file types listed first, items are listed in order of first occurrence, but may apply to more cases.

ASCII-table (when attributive)
binary-table (when attributive)
random-groups (when attributive)
Less common, but allowed standard values are: > Less-common, but allowed standard values (in table:refpos)
most-significant (least-significant)
fix at 8534 OK
more-complex data
character- and numeric-value representations
character-string value/length/column
spectral-coordinate systems and celestial-coordinate systems, time-coordinate systems
lower-case (and upper-case)
ASCII-text characters/representation
fixed at 899, 920, 1216, 1246, 2295, 3350, 3493, 4212 (LaTeX index or end of line) OK
zero-or-more table entries
line-feed characters
more-complicated structure
Bitstream devices > Bit-stream devices (but in verbatim title)
magnetic-tape devices
fixed at 7908 OK
data-storage devices
REVERSE multiples of 2880-bytes in length > multiples of 2880 bytes in length
Single-record string keywords
single-quote characters
zero-length string
long-string value
fixed at 582 and 1380 but not 1314 all OK
forward-slash character
single-precision 32-bit floating-point number
fixed at 4168 OK
double-precision
floating-point number
1-d one-dimensional (also 2-d, 3-d)
fixed 2-D at 6847 OK
plain-text form
Data-integrity keywords
(un)signed-integer keyword/constant (when attributive)
ASCII-table extensions
FITS-reading programs
at 6364-5 FITS reading and writing software OK ? reworded by MJC
Binary-table extensions
photon-counting device
zero-or-more members
random-access storage or sequential-access storage
pixel-coordinate values
world-coordinate formalism/axes/etc.
but not world coordinate systems including \section{World coordinate systems} but \subsection{World-coordinate-system representations} OK ? all revised by MJC
Coordinate-system specifications
single-dish radio-astronomy data
coordinate-transformation values
intermediate-world-coordinate axis numbers
but Intermediate World Coordinate Axis capital not dashed at 4923 4962 4966 4991 4997
or intermediate world-coordinate element at 4680
and intermediate world coordinates at 5142, 5262 (the latter are OK) now all OK
intermediate-coordinate axes
celestial-coordinate-algorithm codes
Celestial-coordinate-system representations (also Spectral-)
planetary, lunar, and solar-coordinate systems at 5165 shouldn't be planetary-, lunar-, and solar-coordinate systems ? yes OK
spectral-axis coordinate(s)
fixed at 5379 OK
Cosmic-microwave-background dipole
Conventional-coordinate types
100-element array
image-axis descriptions
atomic-time standard
radio-signal distributions
velocity time-dilation variations
reference-time keywords
time-coordinate axes but Time coordinate frame at 5696 ? unchanged
(three-dimensional) spatial-coordinate frame
orbital-ephemeris file
fixed also orbital ephemeris keyword at 4897 OK
time-series data
axis-number identification
data-compression algorithm
REVERSE zero point NOT zero-point but zero-point values/offset
subtractive-dithering technique
fixed also at 6574 OK as it was
random-number sequence/generator
pseudo-random numbers
of order 100-million elements
most-efficient compression algorithm
variable-length vector
variable-length-array convention
fixed at 6800 \index{variable-length arrays, compression}, possibly harmless OK
16-bit instruction
three-bit opcode
time-scale specification but time scale substantive,
fixed also timescales > time scales at 5791 OK
32-bit single-format number (64-bit double-format)
a more-flexible and efficient
single-dimensioned array
more-general FOREIGN extension type
more-precise RFC-2219 compliant wording

sax.iasf-milano.inaf.it/~lucio/FITS/Conventions/languageediting-full.html :: original creation 2018 lug 20 16:46:57 CEST :: last edit 2018 Jul 20 16:46:57 CEST