Links to each requirement

[murata2makoto]

It is not easy to reference specific requirements in JLREQ. Some requirements are represented by sub- or sub-sub-sections, while others are represented by itemized lists or sentences. Ideally, each requirement should be named and referencable by a fragment identifier.

But embedding names and anchors in JLREQ requires a big effort. One work around is to use EPUB publications (available as EPUB in GitHub epub-samples) and use EPUB canonical fragment identifiers. Then, everything becomes URI-referencable.

[r12a]

@murata0204 i looked at the pull request at gh-pages...murata0204:asXML. It breaks the respec document in many places, so i can't just merge it, but before you take action to fix that, i'd like to understand better how you see this working.

The ids use a format like this:

<p id="m1051">

What is your expectation wrt content authors adding (or removing) material in the future and how would they manage allocation of ids?

[murata2makoto]

I do not think that I submitted a pull request yet. Do you prefer my another branch https://github.com/murata0204/jlreq/tree/asHTML ?

When I wrote "Minimal Requirements on EPUB for Japanese Text Layout", it was difficult to reference specific features in JLREQ. I had to write "b in the itemized list in 2.2.3 Elements of Page Formats". To avoid such clumsy references, I very often referenced figures rather than text immediately before the figures.

[r12a]

I understand the problem you describe. In fact, i have struggled with that too.

I have some suggestions about how to avoid breaking the document, which i suspect may also apply to the script that produced the asHTML version, but what i'd like to do first is discuss how content authors will work with ids as new content is added, since that will influence what we do to the source code.

I'd prefer not to require the use of a tool chain to publish the document - that's one of the great things that respec helped us with, that really helps productivity and clarity. There could also be potential issues with automatic assignment of ids, if not done carefully.

If the content author is to provide ids themselves as they are editing the doc, then we may be better off with a different format.

Given the current id format, It seems to me that before you add text to the document you would need to scan the whole file to figure out what is the highest id used so far before you can add any new id. An easier approach might be to use the id for the section+a counter, but that would still lead to some searching in the case of jlreq, because sections are often (a little too) large.

Another alternative would be to use a format like this:

<p id="f20170321000">

where the last 3 digits are the unique part, and are reset to 000 each UTC day (or we could even extend the format to include the UTC hour). I think that would be more manageable. It's quick and easy to locate all the ids that start with today's date.

That's the kind of thing i was wanting to address first, since it affects how we change the doc.

[r12a]

I was also wondering whether it would actually make sense to improve the signposting in the document instead, and reduce the number of long, nested lists by converting them to subsections with headings (and links, of course). This would change the document itself, so would have to be done more carefully, but it might also make it easier to maintain and add links going forward. For example, you wouldn't have to necessarily stop and add an id every time you split a paragraph in two while editing. I haven't had time to fully analyse the opportunities or risks for that approach yet.

[murata2makoto]

JLREQ is too lengthy. Core features, features for paginated documents only, and those for printed documents only should be separated. Features for scrollable documents should be added. Features from magazines, textbooks, etc. should be added. As you wrote, long, nested lists should be converted to subsections. But I am not sure if this is doable.

In this attempt, I had "in place rewrite" in mind. That is, we do not change the URL for my proposed changes. I do not expect addition of several paragraphs.

The id format you suggested is fine to me. Let me try.

[r12a]

Just before i disappear for the night, i had a quick look at the document earlier and wondered whether it might be better to add ids to the list items rather than to each paragraph. Most list items seem to have only one paragraph in them anyway. If we convert list items to sections later, they can retain the ids. I didn't have long to check the idea out, but it seemed to me that it would be better for content authors to work at that level of granularity than to require ids on every paragraph. Also there's something more structural about list items than about paragraphs. Just a thought.

I think we'd need to reconvene a task force before making the other visible changes you mention above, and check with the Kobayashi-sans.

[murata2makoto]

Adding ids to list items is a possibility. Let me try.

[murata2makoto]

Done in a new branch. See https://github.com/murata0204/jlreq/tree/listItemsOnlly

[r12a]

This is now done.

@murata0204 i didn't use your version, since i'd found that your tool broke some things in the past, and it would have taken me as long to find and fix those as to add the ids myself, so i did the latter.

There are ids on each li that are simply numbered for now, eg. id="id21". When authors add new ids they should use the datetime approach outlined above, rather than continue the numbering.

I also added ids of the form id="n21" to all the notes in the document. These are more stable than the ones assigned by respec.