[tei-council] CVS README

Sat Apr 16 18:57:31 EDT 2005

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

I've noticed I've often a tendency towards unnecessarily overnesting.

>         <head>README for TEI P5 CVS</head>
> I'm concerned that the title and the content don't match. 

What about "CVS P5 Module README File" ?

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

In my view, if they are reading this file, then they've already
got the P5 Module from CVS and don't need instructions for getting
it.  The proper place for this information, I'd think is the TEI
CVS page http://sourceforge.net/cvs/?group_id=106328 though this
also links to the sourceforge Basic Introduction to CVS I'd prefer
not duplicate the information that the better qualified provide.

 > * what all those files are for
 > * how to submit suggestions or patches

These two I agree with, but should either go in a README for
each CVS module or somehow in an overall one.  (But since
you have to check out each module individually, an overall
one is impossible and I'm assuming the TEI CVS page
http://sourceforge.net/cvs/?group_id=106328 I suppose.

> Is it called a "module" (by Sourceforge)?
Yup. I think to distinguish from the stable releases you
can download which they call 'packages'.

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

Strangely I originally wrote directory and changed it to folder for
some unknown reason.

>           P5 version of the TEI Guidelines and Schema. These are
> s/Schema/associated schemas/

Done.

> 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.

Done.

>         <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.

As someone who often overuses @type I'm happy to do so -- but what
type are these divisions?

> "... of the guidelines, schemas, and DTDs, amongst various ..."
Done.

> Shouldn't that be <name type='target' rend='quoted'>fasicule</name> or
> some such? :-)
Done.

> "either internet access or a locally served TEI eXist database to use
> this"
Done.
>               /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?

I've done that for now; perhaps <code type="path"> ?

>               copy of the stylesheets, or
>               /usr/share/xml/tei/stylesheet which is the

and here

>               location used by the debian package for TEI
> s/debian/Debian/

Done.

>             installed: 'make check'.</p>
> Perhaps <code type="cmd">make check</code> ? 
> Maybe <rs type="command">make check</rs>   ?

Used <code type="cmd"> for now.

> I think I'd encode all the following as triplets:
>   <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>
Done.
>  <!-- ... -->

> Missing the Oxford comma after "xmllint".
Done.

> "the TEI P5 schemas in RelaxNG &amp; DTD and the HTML version of"
Done.

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

Since it was a simple one I included it.

> As with "default".
Done.

>             <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.
That means to me that this would produce a version of the TEI Lite 
DTD/Schema/Guidelines not that it produces P5 Guidelines in Lite.
Not sure what it should be then.

> s/TEI P5 XML/TEI Lite (P5)/
Done.
> "current directory (i.e., P5/)."
Done.
> 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.
Done.

>               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?

It takes you to the Jetty server (if you've not embedded eXist into 
Cocoon and are using the default).  I could change this to
http://localhost:8080/exist/ which would point to the local
exist homepage.  In fact, But really this target uses 
http://localhost:8080/cocoon/services/Admin?WSDL so assumes
use of sebastian's packages.  Perhaps I should remove reference to it?

> May want to add "(See <ptr target='PFX'/>, above.)", and then put an
> id=PFX on the entry for that variable.

Done.
> 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.)

Yes, I ignored those because I thought it less likely that people would
need them (or those that would won't need help). Test, in specific, uses
software which 'make check' doesn't test for (and which it turns out I
didn't have installed).

> 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...)

Yeah, I thought about that kind of thing as well -- but perhaps it
should follow whatever order is in the Makefile (or that changed
to such an ordered principle...)  My order was based mostly on my
perception of frequency of use.

-James