[tei-council] CVS README

Sat Apr 16 03:26:00 EDT 2005

James --

First off, thank you for doing this. This will make the use of the
CVS version of the source ODDs much more accessible to lots of
people. Overall I think it looks very good. Specific nit-picks are
inserted left-aligned below, interspersed with the XML source which
is indented by 6 or more columns, with some general comments at the
end. Hope this is readable and helpful.

      <div>
This level of <div> is unnecessary. All of its children could be the
direct children of <body> instead.

        <head>README for TEI P5 CVS</head>
I'm concerned that the title and the content don't match. The content
gives lots of (very good) information on using the Makefile on a
GNU/Linux or other unixy system. But it doesn't say anything about 
* what and how to get from CVS
* where to put it
* how to update it
* what all those files are for
* how to submit suggestions or patches
* other things I may not have thought of 
I'm not suggesting you need to write all this ever, let alone before
the file is released. I think your "keep it simple to start" policy
is fine. But I am suggesting that either the title should be less
ambitious or specific placeholder <div>s should be inserted to be
filled in later.

        <p>This file contains some basic information about the
          files included in the P5 module, and what can be
Is it called a "module" (by Sourceforge)?

          generated from them. The Source/ folder is by far the
s/folder/directory/, no? (If so, everywhere.)

          most important. This contains the source files for the
          P5 version of the TEI Guidelines and Schema. These are
s/Schema/associated schemas/

          organised in folders by chapter of the Guidelines, and
          each contain one or more file in ODD (One Document Does
          it all) format. This is an XML format developed by the
          TEI for creating guidelines and schema.</p>
Last sentence: "This is a TEI format specifically intended for writing
Guidelines about encoding, from which schemas and reference
documentation can be automatically extracted." or some such.

        <div>
I think using type= of <div> is probably a good idea. In P3 they were
required, but because an SGML defaulting mechanism not available in P4
was used, the content model was loosened in P4 to make them optional.
Indeed there are cases (and the P3 Guidelines themselves were a
perfect example) where type= didn't serve a useful purpose, so there's
a pretty strong argument for leaving it optional. But nonetheless, I
personally think it can often be quite helpful, at least for the
humans.

          <head>Generating Other Formats</head>
          <p> A Makefile is provided to generate HTML versions of
            the guidelines, DTDs and schemas, amongst various
"... of the guidelines, schemas, and DTDs, amongst various ..."

            other possibilities. There are a number of
            variables that one can change at the beginning of
            the Makefile. These are:</p>
          <list type="unordered">
            <label>TEISERVER</label>
            <item>This is the eXist server storing TEI files
              used by the 'fasicule' target. You must have
Shouldn't that be <name type='target' rend='quoted'>fasicule</name> or
some such? :-)

              internet access to this target. By default this
"either internet access or a locally served TEI eXist database to use
this"

              is <ref target="http://www.tei-c.org.uk/Query/"
                >http://www.tei-c.org.uk/Query/</ref>
            </item>
            <label>PREFIX</label>
            <item>This is the default location under which you
              wish to install files locally if you use the
              'install' target. By default this is
              /usr/local/tei</item>
We (TEI internal documentation writers) really need to develop and
document a convention for encoding all sorts of things, among them
file paths. I'm thinking <rs type="path"> at the moment. Any
thoughts?

            <label>XSL</label>
            <item>This is the location of the XSLT stylesheets
              required for the transformation of ODD files.
              By default this is a URL pointing to <ref
                target="http://www.tei-c.org/stylesheet"
                >http://www.tei-c.org/stylesheet </ref>
              however, if you want to use a local copy of the
              stylesheets you may wish to change this.
              Possible options include the folder for the CVS
              copy of the stylesheets, or
              /usr/share/xml/tei/stylesheet which is the
              location used by the debian package for TEI
s/debian/Debian/

              stylesheets. </item>
          </list>
          <p>The makefile has a number of requirements, these
            include internet access (or a local copy of the
            stylesheets), and up-to-date versions of the perl,
            jing, trang, xmllint and xsltproc programs. If you
            do not have these installed then many of the make
            targets will not work. Fortunately, there is a
            target which will check to make sure you have these
            installed: 'make check'.</p>
Perhaps <code type="cmd">make check</code> ? 
Maybe <rs type="command">make check</rs>   ?
In truth (as I say above), we need a general purpose documentation
schema, and perhaps it should contain special purpose elements for
things like file names, file paths, URLs (that are not references),
system commands, error messages, command output, etc.

I think I'd encode all the following as triplets:

<list>
 <head>Makefile Targets</head>
  <item>
   <label>Check</label>
   <gloss>Usage: <code type="cmd">make check</code></gloss>
   <p>This target checks to see whether you have perl, jing,
   trang, xmllint and xsltproc installed.</p>
  </item>

          <list type="unordered">
            <head>Makefile Targets</head>
            <label>Check</label>
            <item>Usage: <hi rend="bold">make check</hi>
              <lb/> This target checks to see whether you
              have perl, jing, trang, xmllint and xsltproc
Missing the Oxford comma after "xmllint".

              installed. </item>
            <label>Default</label>
            <item>Usage: <hi rend="bold">make</hi>
              <lb/> This is the default target and creates
              the TEI P5 DTDs, Schemas and HTML version of
"the TEI P5 schemas in RelaxNG &amp; DTD and the HTML version of"

              the Guidelines. </item>
            <label>Convert</label>
I had not even taken notice of this one, let alone ever used it. :-)

            <item>Usage: <hi rend="bold">make convert</hi>
              <lb/> This target creates the TEI P5 DTDs and
              Schemas. </item>
As with "default".

            <label>DTDs</label>
            <item>Usage: <hi rend="bold">make dtds</hi>
              <lb/> This target creates DTDs for TEI P5 in
              the DTD/ folder. </item>
            <label>Schemas</label>
            <item>Usage: <hi rend="bold">make schemas</hi>
              <lb/> This target creates RelaxNG Schemas for
              TEI P5 in the Schema/ folder. </item>
            <label>HTML</label>
            <item>Usage: <hi rend="bold">make html</hi>
              <lb/> This target creates an HTML version of
              the TEI Guidelines in the Guidelines/ folder.</item>
            <label>XML</label>
The output of this target (Guidelines.xml) as intended to be the
Guidelines expressed in TEI Lite. Thus perhaps this label should be
"TEI Lite" or some such.

            <item>Usage: <hi rend="bold">make xml</hi>
              <lb/> This target creates a TEI P5 XML version
s/TEI P5 XML/TEI Lite (P5)/

              of the Guidelines as Guidelines.xml in the
              current (P5) folder.</item>
"current directory (i.e., P5/)."

            <label>Split</label>
            <item>Usage: <hi rend="bold">make split</hi>
              <lb/> This target creates a set of TEI P5 XML
              files that are a version of the Guidelines
              split into chapters, in the split/ folder.</item>
The output of this target is also XML, but is not TEI Lite (as with
the 'xml' target), but rather still ODD. The important thing here
(IMHO) is that the resulting files have had entity references
resolved.

            <label>exist</label>
            <item>Usage: <hi rend="bold">make exist</hi>
              <lb/> This target updates a locally running
              copy of the eXist XML database with the TEI
              files. The files are added via the SOAP
              interface and the database is assumed to be
              running at the <ref
                target="http://localhost:8080/"
                >http://localhost:8080/</ref> URL.</item>
Should this really be a ref with a target=? What happens if one clicks
on it?

            <label>Clean</label>
            <item>Usage: <hi rend="bold">make clean</hi>
              <lb/> This target removes most of the files
              created by the other targets.</item>
            <label>Install</label>
            <item>Usage: <hi rend="bold">make install</hi>
              <lb/> This target installs a separate local
              copy of the DTDs, Schema, and HTML version of
              the guidelines under the file path given by the
              PREFIX variable.</item>
May want to add "(See <ptr target='PFX'/>, above.)", and then put an
id=PFX on the entry for that variable.

          </list>

I gather you've ignored the dist, valid, validate, test, pdf, and
fasicule targets on purpose. Probably reasonable. But what about
"html-web" target? Do you know the difference between it and "html"?
(I don't -- I know it's the same except for slightly different
stylesheets, but even having glanced at the stylesheets and scanned
the results, I don't know what or why is really different. I suspect
the -web version is intended to have a useful navigation bar down the
left-hand column.)

I think the order of targets might use some thought. I'm inclined to
suggest that the more complex targets that call others be listed
later, so they can just refer to the previous ones. E.g. that 'make
convert' is the same as 'make dtds; make schemas'. Either that or just
list 'em in alphabetical order. (Then what do you do with "default",
or my suggestion that the label for 'xml' be "Lite"? Hmmm...)

Again, I'm really glad you're doing this. It's a Good Thing(tm :-).