Markup changes in preparation for FPWD (URGENT)

[r12a]

we're hopefully quite close to publishing a FPWD of clreq. When we do so, we expect to publish a snapshot of the chinese version of the document in the TR (technical report) space alongside the english FPWD.

to prepare for that, i'd like to work on various aspects of the markup of the zh doc. If i don't hear any objections in the next couple of days, i'll begin making these changes.

[1] i'd like to migrate the document to respec. This is a javascript framework used widely at the W3C, which makes it much easier to create documents. For example, it automatically generates much boilerplate text and the toc, etc. It also makes it easier to provide the needed metadata, and produces an output document that is easier to get through the publication requirements.

Robin Berjon has, today, implemented a localization of respec for Simplified Chinese. You can see a very quick and dirty example of it at http://www.w3.org/International/docs/chinese-layout/zh-respec/index.html (ignore the double numbering, missing images, etc. – i propose to clean up that stuff when porting to the respec framework). We may need to tweak some of the boilerplate text. (Thanks to Xiaoqian for the initial translation.)

[2] i'd like to add more ids as anchors. For example, i tried pointing someone today to the information about characters used for quotations in Chinese, and had to say "point 2.1 under http://w3c.github.io/clreq/#categories_and_usage_of_punctuation_marks", rather than being able to link closer to it.

[3] i'd like to flatten out some of the nested lists, making h5 into real headers (which will help with the ids, as well as improving the semantics of the document) and make h6 into span class=leadin. This will also help reduce some of the complexity for editing (i already fixed a couple of errors that were confusing my editor, but there are some more, and i'm struggling to find where exactly the markup is broken).

[4] i plan to implement the changes to the way unicode characters are referred to, per the separate issue.

[5] i'd like to implement some of the inline and other markup and styling conventions described at http://www.w3.org/International/docs/styleguide (modified, as necessary, for Chinese).

any objections?

[ethantw]

I agree to most of your suggestions. But I don’t really understand the difference between h5 and ‘real headers’. Is it only because it isn’t syntactically correct to put an h[1-6] element inside a list?

Also, as far as I understand, the Respec tool does not recognise CJK characters while transforming from texts into IDs. It simply generates a number. Is there any solution to that?

[r12a]

i'd like to give h5 headers ids and put section tags around them and their contents. This makes them addressable as headings, semantically cleaner, and part of the hierarchical structure of the document, but also simplifies the structure of the source code, making it easier to avoid and to fix incorrectly nested tags. (I already fixed a couple, but there appear to be more somewhere). It also conforms to W3C publication rules, which is important for the English version, and I'd like to keep the markup of both English and Chinese versions identical, if possible, since it greatly aids translation and comparison.

wrt IDs, Ethan, can you give me an example, so that i'm sure i'm talking about the same thing? I think we should provide more explicit IDs in the content so that the number of automatically generated ids is small. Again, I think it would help a lot if those ids, when used as fragment identifiers for URLs, etc. were the same in both the SC and TC Chinese and English versions – it would make it easier to cross-reference information across versions.

[VirgilMing]

Out of curiosity: if not for the restriction of Respec tool, why would it be important to explicitly assign ID for elements? Should it not be the task for markup builder?

Virgil Ming

On Fri, Jun 5, 2015 at 10:24 PM, r12a notifications@github.com wrote:

i'd like to give h5 headers ids and put section tags around them and their contents. This makes them addressable as headings, semantically cleaner, and part of the hierarchical structure of the document, but also simplifies the structure of the source code, making it easier to avoid and to fix incorrectly nested tags. (I already fixed a couple, but there appear to be more somewhere). It also conforms to W3C publication rules, which is important for the English version, and I'd like to keep the markup of both English and Chinese versions identical, if possible, since it greatly aids translation and comparison.

wrt IDs, Ethan, can you give me an example, so that i'm sure i'm talking about the same thing? I think we should provide more explicit IDs in the content so that the number of automatically generated ids is small. Again, I think it would help a lot if those ids, when used as fragment identifiers for URLs, etc. were the same in both the SC and TC Chinese and English versions – it would make it easier to cross-reference information across versions.

Reply to this email directly or view it on GitHub:
#50 (comment)

[r12a]

i'd be worried if differences in markup between versions mean that the markup builder generated different ids for the same fragments. It also helps to have meaningful ids, which i think was one of Ethan's concerns.

[ethantw]

@r12a:

Sorry for the late reply. Below is my idea of how IDs should be. They have to have their own corresponding messages (in English or in Pinyin) of what they are semantically instead of the generated numbers provided by Respec. Otherwise if we add some new sections, the old URLs with IDs would be corrupted.

I added these IDs to the current Chinese version manually. Is there an easier way to do so?

[r12a]

@ethantw I agree that it's desirable to have semantically meaningful, and persistent ids. I don't know of a better way to add the ids than to do it manually. Respec should respect the manually created ids, it only generates ids where a manually created one was missing. In the case of clreq, that is for the h5 and h6 headings, and for the figures. It was my plan to provide ids for those locations, so that respec wouldn't need to generated them.

[r12a]

this is now done wrt basic markup. Ported to respec, adjusted headings, assigned ids, converted unicode names. Styling can be revisited later.