
------------------------------------------------------------------------

DEVELOPMENT AND RELEASE STEPS

------------------------------------------------------------------------

Although one need not develop Derivations in a Debian GNU/Linux
environment, the author---who happens to be a Debian user and
developer---does so.  This file documents some of the author's
development practices in that context.  (The file does not carefully
distinguish between actions the author takes as upstream developer and
actions he takes as Debian developer, though the two roles are indeed
logically distinct.)

In all the file,

  * $VER represents the version number sans date, as 0.99.
  * $D1 represents the top development directory;
    for example, ~/der/derivations-0.99.19700101.
  * $DW represents the top development directory before it has been
    assigned an actual revision date (see $TW below).
  * $DL represents the top development directory of the last revision.
  * $DP represents $D1/.., $DW/.. and $DL/.., the parent
    of the top development directory, as ~/der.
  * $T1 represents the revision date; for example 20070322.
  * $TW represents the working revision date, inasmuch as the actual
    revision date normally is not known until release time.  (For this
    date, the author usually but not always chooses the next day not a
    Sunday following the actual date of the last revision.)
  * $DSC represents the Debian .dsc file, where the needed Debian source
    package files in $DP are as

        derivations_0.99.19700101.orig.tar.gz
        derivations_0.99.19700101-1.diff.gz
        derivations_0.99.19700101-1.dsc

  * $DIFFGZ and $ORIGTARGZ represent the .diff.gz and .orig.tar.gz
    as above.
  * $DEB represents the Debian binary package,
    as derivations_0.5.20070322-1_all.deb.
  * $TRASH is a directory in which you can keep some files you probably
    no longer need.

The file naturally is not a complete set of instructions, being rather
notes to jog the author's memory.  For example, the file does not
explain what the command "view foo" is for, though of course it is for
the author to review foo to ensure that all is in order, making
corrections if necessary.  However, there is probably enough information
here to be of use to a future developer.

------------------------------------------------------------------------
BEGINNING DEVELOPMENT OF A NEW REVISION
------------------------------------------------------------------------

The author opens development of a new revision of the book by
approximately the following steps.

1.  Optionally, or if $DL does not exist,

    cd $DP
    rm -R $DL || true
    dpkg-source -x $DSC
    cd $DL
    # The next command is probably unnecessary given a recent Dpkg.
    #bash debian/helper/letexec
    cd ..

2.  Give the commands

    cd $DL
    fakeroot debian/rules clean
    cd ..
    cp -ai $DL $DW
    cd $DW
    debian/helper/extend-changelog
    debian/helper/update-date $TW

If there are Quilt patches, then the author probably integrates them
into the source, after which he probably runs

    debian/helper/rm-quilt

to de-Quilt the source.

------------------------------------------------------------------------
RELEASING
------------------------------------------------------------------------

The author closes development of a new revision of the book and prepares
it for release by approximately the following steps.

1.  Decide on an official revision date, then

    cd $DP
    mv -i $DW $D1
    cd $D1
    debian/helper/update-date $T1
    fakeroot debian/rules clean
    debian/helper/buffe-src

2.  Repeatedly give the following commands, making corrections as
indicated, until no further corrections remain to be made:

    debian/helper/ispell-all
    make clean && { make clean tex/derivations.pdf >/tmp/check.txt 2>&1; }
    fakeroot debian/rules clean
    debian/helper/buffe-src

During the check, index entries can overfill their margins by any
amount less than 9.0pt.  Where necessary (hopefully not often), any
page can be less than 3.0pt too tall.  (These limits may be too strait,
but experience has not yet asked the author to judge looser limits; so,
these are the limits to enforce for now.)

3.  Finalize doc/changelog and debian/changelog with the following
commands.  Change the distribution in debian/changelog from experimental
to unstable if appropriate.

    cd ..
    diff -turN $DL $D1 >der.diff
    grep -B3 -A3 '19\(69\|70\)' der.diff
    view der.diff
    cd $D1
    vim doc/changelog
    vim debian/changelog
    fakeroot debian/rules clean
    debian/helper/buffe-src
    cd ..
    diff -turN $DL $D1 >der.diff
    grep -B3 -A3 '19\(69\|70\)' der.diff
    cd $D1

4.  Give these commands, now and, if you like, later, too:

    debian/helper/ispell-all
    fakeroot debian/rules clean

5.  Optionally,

    fakeroot debian/rules cleandeb-force

6.  Because the author actually uses the Debianized source to develop,
create a non-Debianized upstream source by

    fakeroot debian/rules orig

7.  Omitting the --no-sign if it is wanted actually digitally to sign
the sources, build source and binary package files by

    time dpkg-buildpackage -tc --no-sign
    cd ..

8.  Optionally review the .debian.tar.xz to ensure that it actually
contains the Debianization as it ought.

9.  Log in as root.  Observe that the author keeps a debian archive
on his PC, so if like most you do not then you will probably need to
vary the --bindmounts below accordingly.  As root,

    cd $DP
    time pbuilder build --bindmounts /debian $DSC
    dpkg -P derivations
    dpkg -i /var/cache/pbuilder/result/$DEB

10. As nonroot, check that the package has seemed to install correctly.

11. Optionally log out as root.

12. As nonroot,

    cd $DP
    mv -iv derivations[-_]${VER}.${T1}* $TRASH/
    cp -aiv /var/cache/pbuilder/result/derivations_${VER}.${T1}{.orig.tar.xz,-1.debian.tar.xz,-1.dsc} ./
    dpkg-source -x $DSC

13. Optionally upload.

------------------------------------------------------------------------

For lack of a better place to note it, it is here noted that the author
might check the following on completing a chapter:

  * /\~\$                        (short math)
  * /\(^\|[[:space:]]\)\$        (long math)
  * /[$)]\('s\|th\)\([^a-z]\|$\) (no tied *'s or *th)
  * /}[,.?;:!]                   (\emph{text[,.?;:!]})
  * /\\\\                        (no \\ at the end of an array or eqnarray)
  * /\(^\|[[:space:]]\)(\\ref{   (no untied eqn references)
  * /^[[:space:]]*\\emph         (no \emph inadvertently in place of \index)
  * /\\index.*\![[:space:]]      (no space following `!' in \index)
  * /\((\|\[\|\\{\)[ \n]*\\sqrt  (\sqrt adheres to leftward parenthesis)
  * /bad break                   (bad breaks are in fact bad)
  + pcregrep -M -n '\\(?:right|[Bb]ig+)(?:\)|\]|\\\})[\s\n]*\\,[\s\n]*d(?:[[:alpha:]](?![[:alpha:]])|\\)'
                                 (no thin space between big right delimiter and dt)
  + pcregrep -M -n '\\\w*int\w*(?:[_\^](?:\{[^\{\}]*\}|\\\w+|\w))*\s*\\,'
                                 (no thin space immediately after \int)

And here are noted commands to scan TeX files in book order:

grep -E 'PATTERN' $(for A in $(<../debian/helper/FilesTex); do echo $A.tex; done)
for A in $(<../debian/helper/FilesTex); do B="$A.tex"; grep -H 'PATTERN' $B; done

And here is a search in main.log for overlong index lines:

  * /Overfull \\hbox (\(9\|[[:digit:]]\{2\}\)

