[tei-council] Comments on getting started

Fri Aug 29 07:02:46 EDT 2008

Hello all,

Elena and David, thank you for your comments.

Elena Pierazzo wrote:
> 1. I think that a short chapter on text analysis would be of great
> help. From my teaching experience I have noticed that for someone
> that it is really complicated for someone that is used to work on
> Word to understand the rationale of semantic markup and use elements
> like <div> and <head>; tables are really complicated. Once these
> concepts are passed, it's then relatively easier understand other
> kind of inline markup.

This would seem quite useful to discuss. Would you see this as something
to be discussed before we get to the actual editing or only afterwards?
David (see below) suggests this is an advanced subject, like the
schemas, but I can also see a case for including it as a section in
chapter 4, 'Overall structure of a TEI text'.

> 2. The fact that we are including screenshots and editor specific 
> instruction imply that the document will need a regular (and
> frequent) maintenance as editors tend to change very quickly.

Yes, alas.

> Versions of editors, processors and browsers are an issue to be
> considered carefully. For instance: for Oxygen are we offering
> support for the full program of just for the Author version of it?
> etc.

As to oXygen: you can't edit xslt or schema's in oXygen Author, so we'd 
have to use the full product. But I wouldn't use the word 'support'.

> I volunteer for helping with the writing, if Peter, Arianna and the 
> others (I forgot who else is in the group) need it.

Thank you. (As yet there is no group).

David Sewell wrote:
> It seems to me that there is a natural division between the 
> basic/intermediate sections that virtually every user will need to
> cover (outline chapters 1-8) and advanced topics (9-Schemas; and
> Elena's suggested chapter on textual analysis, if we agree to add
> it).

See above.

> Another way to look at it is that chapters 1-6 are applicable to
> anyone working with TEI files, including assistants who are simply
> adding or correcting content following project guidelines; chapters 7
> and beyond are more applicable to people in charge of projects
> (including independent work) or designing TEI-based publications.
> (This could be explained to readers in the introductory material.)

OK.

> I'll volunteer to help with authoring and editing.

Thanks.

> Would it make sense to put the outline document on the TEI Wiki, to
> make it easier for people to edit it and keep up to date with
> changes? (We could use a "private" Wiki page, not linked from
> elsewhere, so that the document and our comments wouldn't be open to
> the public while work is in progress.)

Good idea

> Audience
 > As someone (Dan I believe) said during our last telco, we
> should also include in our target audience people who are not
> themselves specialist scholars but who are, or will be, working as
> encoders with a project. These may be undergraduates, editorial
> assistants, etc. We can assume that they are equally motivated with
> the academic readers, but they may not be familiar with the technical
> vocabulary of textual studies, bibliography, etc.

OK

> Software 
 > It will take some discussion and maybe experimentation to
> decide just how to present the examples connected with different
> software platforms. One option would be to illustrate each major task
> with screen shots and instructions for each of the platforms we
> decide to include. Or we could choose a single platform, say oXygen,
> for the main presentation, and link to illustrations of how tasks are
> handled in the other platforms via appendices. (Or we could be very
> clever and compose alternate texts for the software sections that
> would be toggled via reader choice in the online version?)

My preference would be for your second option: to write the document
based on oXygen, and have appendices, maybe even wiki pages, about how
to do this in other programs. (I would like to avoid people having to
print a document that is very repetitive).

What do others feel? Extending this to other platforms could even become 
a community effort.

> Contents
> "We explain RELAX using the XML syntax, and mention the existence of
> the compact syntax." This should be discussed further. In my
> experience the syntax of DTDs or Relax NG compact is easier to grasp,
> and better to use for the very first example of how schema rules
> constrain a document.

I always felt that
     <oneOrMore> ... </oneOrMore>
is much more intuitive than
    ( ... )+

Other opinions?

> In chapter 3, we could offer an example of an extremely simple
> non-TEI XML language with maybe three elements and one attribute, and
> show the Relax NG compact schema used to validate it. Later, in
> chapter 9, we could explain the relation between the XML and compact
> forms of Relax NG and use the XML form in relation to the ODD
> discussion.
> 
> This is more or less the way that things work elswhere in the TEI
> world: the "Gentle Introduction to XML" uses compact syntax, and the
> Element reference in the Guidelines defaults to compact; but in the
> Guidelines chapters on ODD, the RELAX NG XML syntax is necessarily
> used.

I would like to place all schema related discussions after ch. 8,
'Getting this to work on sample of own text'. People should get to the
stage where they can actually use TEI as soon as possible.

Peter