Comparison for T-SP-RR.25.1-2018 service-publication type against original

[ronaldtse]

Original: T-SP-RR.25.1-2018-MSW-E.docx

Generated: T-SP-RR.25.1-2018-MSW-E-generated.doc.zip

Source adoc: https://github.com/ituob/service-publications-data/blob/master/1154-RR.25.1/T-SP-RR.25.1-2018-MSW-E.adoc

@anermina can you please help make a comparison between the original and generated document and list out the issues here? Screenshots will be helpful. Thanks!

[ronaldtse]

@w00lf Can you help write the content part of the adoc file using yaml2text? Thanks.

This will be a good example for the other service publications. CC @manuel489 too.

[ronaldtse]

This relates to https://github.com/ituob/service-publications-docs/issues/1

[anermina]

1. Frontpage: Information provided in :series: in source adoc is not generated.

Original:

Generated:

2. Preface: Generated file includes some header and the title, unlike the original. This seems good to me, but just to stay on the safe side - reporting this as a difference. The same behavior is noticed on the first page after preface, only headers differ.

Original:

Generated:

3. Footnote: Generated file includes the date, unlike the original (seems fine to me). Format of page numbers also differs - original always uses centered arabic numbers, while generated file uses left-aligned lowercase roman numerals for preface sections. For the rest of the sections, left-aligned arabic numerals are used.

Original:

Generated:

4. Tables: Vertical centering (e.g. for "Remarks and restrictions imposed") is not applied, despite the markup indication.

Original:

Generated:

5. Tables: There is an option to repeat the heading at each new page, but in this document, only one row should be repeated, according to the original. I believe it would be fine to repeat the whole heading, so I added heading indication in source adoc.

Table sample from the original document:

Original repetition:

Generated:

6. Numbering sections: Original document doesn't number the sections/chapters and chapter titles are centered.

Original:

Generated:

7. Multi-paragraph notes with items list: They don't look good in generated doc.

Original:

Generated:

8. Too long words for the allowed table width: They don't look good in generated doc. I suppose it is not advisable to reduce the font size in case this happens, but it would be good if we could break these words into syllables and use - at the break.

Original:

Generated:

9. Sections spanning to multiple pages: In this case, original document uses (See cont.) and (continued) indications, unlike the generated one. I'm not sure whether we need this.

Original:

10. Nesting items list in definition lists: First item on the list is placed too high.

Original:

Generated:

Notes about markup:

1. Uppercase titles are changed to lowercase + uppercase where needed.

2. I changed markup a little bit, since it seems that page breaks were unnecessarily inserted in case of too long definition list. This and further markup corrections were added in https://github.com/ituob/service-publications-data/pull/45.

[opoudjis]

@ronaldtse @anermina Should I action these?

As I've argued, a lot of these I won't want to action, either because I think what we're generating is an improvement, or because it would involve idiosyncratic formatting changes. How do we proceed with evaluating these discrepancies?

[ronaldtse]

1. The title is a Title + Subtitle construction.

4. Tables: Vertical centering

Should work?

9. Nesting items list in definition lists: First item on the list is placed too high.

Seems like a bug?

[opoudjis]

1. There is indeed no provision for series in the front page of SP. But then again, I dispute that

:series: Status of Radiocommunications between Amateur Stations of Different Countries
:series1: (In accordance with optional provision No. 25.1 of the Radio Regulations)
:series2: and

are a series at all. This is a multi-part title, and should be marked up as such, with line breaks and all:

:doctitle: Status of Radiocommunications between Amateur Stations of Different Countries + \
(In accordance with optional provision No. 25.1 of the Radio Regulations) + \
and + \
Form of Call Signs Assigned by Each Administration to its Amateur and Experimental Stations

Currently, those line breaks are ignored in document titles in ITU Doc and HTML, because they are treated as text not marked up text. I'm changing that for ITU, but I'd like confirmation that we will routinely have such multi-part, multi-line titles in ITU OB.

The presence of AND makes me dispute that this is a subtitle construction. Again, we need investigation of OB before we decide if AND is to be routinely inserted between ttile and subtitle. I will also however add subtitle to OB title page.

[opoudjis]

4. valign=middle is in fact passed on, but we decided to ignore valign in Word documents in ITU as a result of https://github.com/metanorma/metanorma-itu/issues/85. I am not interested in going backwards and forwards in these design decisions: we had a good reason to make that decision.

[opoudjis]

9. The "(See cont.)" has been inserted by hand, and a manual page break inserted in the table.

This has not been automated, and we should not be automating it. If there is a need to insert it manually (which I strongly dispute), we can do so by breaking the table, and right aligning the continuation notice.

[opoudjis]

10. Nesting items list in definition lists: First item on the list is placed too high.

There is 6pt before the left cell but not the right. That's because the left cell is MsoNormal, with 6pt margin on the top, but the right cell is a list, and list styles in the stylesheet have their 6pt margin on the bottom rather than the top. The inconsistency doesn't have a good motivation, and I'm making lists consistent with normal paragraphs in their spacing.

[opoudjis]

8. I really would rather not get into font sizes in our markup; I think we need to reconcile to post-editing complex Word documents, and have said so in the past. An optional hyphen can always be inserted in Unicode, as ­.

[opoudjis]

7. List indentation within a note clearly have incorrect indentation in Word. The intent was to add left indentation, but using CSS left margin is not working.

Adding indentation to existing lists in Word is not going to work, because the left margin can only be provided once, for list indentation in the default case. So I have to give up on additional indentation of lists within notes in order to delimit them.

[opoudjis]

6. This is a styling distinction, in numbering and in centring, that I'd rather not action until we've done an analysis of OB documents; if we can streamline formatting, we should.

[opoudjis]

5. Word only allows the repetition of table headers. In this case, to achieve the repetition of the third row, the actual first two heading rows have been encoded as a separate table in Word.

There are manual Word tricks, which we should not be trying to automate. This is the same issue as identified in https://github.com/metanorma/hk-ogcio-infosec-docs/issues/14

[opoudjis]

3. Making OB documents not have separate preface/main section page numbers. Leaving the date in the OB footer—it seems if anything to be an improvement.

[opoudjis]

2. Would rather not action until more documents analysed.