Language techniques: biggish changes

After reading Deborah's recent comments on the Language techniques document, I have created a proposal for new material and organization.  Please take a look at this and voice your opinions by email and/or during the telecon this week.

If I do not hear voices to the contrary, I will begin to make permanent changes to the document towards the end of this week, ie. after the telecon.  I also plan to remove the current change marks at the same time - so please comment on those if you are intending to.




[1] Additional introductory material
====================================
I have quickly written up three new sections:

2 Why specify language?
3 Important concepts
    3.1 Primary language
    3.2 Text processing language
    3.3 Relationships with character encoding and directionality
4 Mechanisms for declaring language in HTML

You can see these at http://www.w3.org/International/geo/html-tech/test (Note that I temporarily left in the following 'Definitions' section (section 5) so as not to break id-refs.  Assume that that will not be there in a final version.)

The effect of adding these is to make this document more self-contained for someone wanting to know about language declarations. Previously we had aimed to largely document just the techniques themselves, and use pointers to faqs, etc. to flesh out the areas in the new sections.  

These additions make the document much more the type of document you might read end to end - rather than just dip into for clarification on a particular technique.

Note also that it duplicates some of the material in Faqs and tutorials.

Is this a good approach?



[2] Changes to the table of contents
=====================================
I have had people comment on how useful the toc was because it included the text of the techniques.  Indeed I have found that very useful myself for getting an overview of the document.

It is arguable, however, that such information is available in the outline document.

As an experiment, I implemented Deborah's idea of shorter titles for the techniques in the toc.

See http://www.w3.org/International/geo/html-tech/test#contents for the new approach.

See http://www.w3.org/International/geo/html-tech/tech-lang.html#contents for the current approach.

Should we adopt the new approach, or return to the previous?




[3] Reordering of techniques
============================
I made plans to substantially reorder the techniques.  The proposal is NOT yet implemented in the document linked to above.  You should instead look at the language section of 
http://www.w3.org/International/geo/html-tech/outline/html-authoring-outline.html

(Note that the section "Identifying in-document language changes" duplicates material, and would NOT appear in the techniques doc - only in the outline.)

The rearrangement helps to more clearly separate primary vs text processing declarations, and improves the clarity of the section headings.

I have not followed Deborah's suggestions exactly, but I think this is a good alternative.

Do you have any objection to this new order?




Comments asap please.
RI



============
Richard Ishida
W3C

contact info:
http://www.w3.org/People/Ishida/ 

W3C Internationalization:
http://www.w3.org/International/ 

Publication blog:
http://people.w3.org/rishida/blog/

Received on Tuesday, 8 February 2005 11:03:49 UTC