[Axiom-developer] RE: Ping: case insensitive filesystems

[Page, Bill]

On Wednesday, November 15, 2006 10:48 AM Gaby wrote:
> 
> Bill Page writes:
> 
> [...]
> 
> | My suggestiong is that when we start to work on a patch, we first
> | ask on the axiom-developer list for someone to play the role of
> | 2nd person. Perhaps this is a way for people who do not yet feel
> | bold enough to work on Axiom themselves yet to get started.
> 
> That would definitely increase the among of shared knowledge.
> 
> | Yes, I would agree to act as the 2nd person and write such
> | documentation from time to time. :-)
> 
> OK, you're officially appointed as that second person :-)
> 

Here is my proposed documentation patch to src/hyper/Makefile:

$ diff -au Makefile.pamphlet_orig Makefile.pamphlet

--- Makefile.pamphlet_orig      2006-11-12 22:20:19.000000000 -0600
+++ Makefile.pamphlet   2006-11-15 11:11:09.000000000 -0600
@@ -145,6 +145,11 @@


 \section{bitmaps}
+There are two files for each (special) character glyph, one
+for the upper case form, and one for the lower case form.
+For more information about hese bitmaps see 'util.ht' in the
+section 'pages', below.
+
 <<bitmaps>>=
 mouse11.bitmap: $(srcdir)/bitmaps.pamphlet
        $(axiom_build_document) --tangle=mouse11.bitmap --output=$@ $<
@@ -236,6 +241,17 @@
 @

 \section{pages}
+The 'ht.db' is built when pages from 'src/hyper/pages' such as
'util.ht'
+and 'util.pht' are installed in the target directory. Because the .db
+file must be kept in sync with the page filesof course care must be
+taken not to overwrite these files at a later time without re-building
+the database.
+
+The Axiom system from which this branch had been made appears
+to contain a redundant copy of util.ht. Removing the version of
+'util.ht' in 'src/share/doc/hypertex/pages/util.ht' would make
+Makefile logic simpler has been removed so as to minimize problems
+when this file is updated.

 The [[.pht]] files contain hardcoded pathnames to viewport directories
 in the installed system.  Of course, that is asking for trouble.
During
@@ -259,8 +275,19 @@
              ${HTADD} *.ht *.pht
 \end{verbatim}

-To avoid conflicts on case-insensitive filesytems we renamed
[[poly.ht]]
-to [[polys.ht]] and [[poly.pht]] to [[polys.pht]].
+On case-insensitive filesytems such as Windows and traditional Mac
+checkout from the source archive can fail if files have names
+differing only in case: poly.ht contra POLY.ht and
+poly.pht contra POLY.pht. To avoid conflicts on case-insensitive
+filesytems we renamed [[poly.ht]] to [[polys.ht]] and [[poly.pht]]
+to [[polys.pht]].
+
+The page [[util.ht]] refers to two files for each (special) character
+glyph, one for the upper case form, and one for the lower case form.
+The names for these files avoid the use of upper and lower letters
+to distinguish these forms. Intstead we use 'xxx.bitmap' for lower case
+and 'xxx-cap.bitmap' for upper case, where "xxx" is the common name for
+the glyth. For example alpha.bitmap and alpha-cap.bitmape.

 We need to make sure that [[ht.db]], the hypertex database file
 is up to date. The file contains absolute offsets into the various

----------

Regards,
Bill Page.