OASIS Open Document Format for Office Applications (OpenDocument) TC

  • 1.  Review of style use in ODF 1.3 specifications

    Posted 07-05-2020 21:52
    My action under item 5 of the TC meeting on June 29 was to report in my review of use of styles in the ODF 1.3 specifications.   I have performed a preliminary review of the use of paragraph, character and list styles in Parts 2, 3 and 4 of the specifications, considering all drafts issued between July 2018 and January 2020 (CSD02).   All three Parts exhibit similar problems, of which the main cases are:   Two or more styles being used for the same purpose within a draft, e.g. the paragraph styles ‘Text Body’ and ‘Default Style’ both being used for body text. New styles being introduced in later drafts, e.g. the conditional paragraph style ‘Appendix Heading’ being replaced by the non-conditional paragraph style ‘AppendixHeading1’ in CSD02 only. Styles being dropped in later drafts, e.g. the paragraph style ‘Default Value’, applied to paragraphs that contain default attribute values, was somehow removed from Part 3 in WD13-03 onwards. Many styles whose purpose is unclear and which appear to overlap other styles, e.g. in Part 3 there are four character styles ‘Attribute Value’, ‘Attribute Value Fragment’, ‘Attribute Value Instance’ and ‘Attribute Value Param’. Another example: Part 4 contains list styles ‘Example Numbering’, ‘Numbering 1’ and ‘Numbering 5’ (what happened to ‘Numbering 2’, ‘… 3’ and ‘… 4’?). Poor naming of styles, e.g. the character style ‘Furmula Sub’ [sic] in Part 3, and inconsistent use of title case in style names. Lack of stability in style definitions, which seem to change, especially in CSD01 and CSD02, e.g. changes to space above and below paragraphs, font sizes, background colors, etc.   My proposal is that the first Working Draft of ODF 1.4 should be based upon a template in which the named styles are well-defined in terms of their naming conventions, their definitions and their planned usage. For this to be achieved, the editors should ensure that:   A well-defined style schema is prepared, detailing the names, properties and intended usage of all paragraph, character and list styles. There is a single text template to be used as a basis for drafting all Parts of ODF 1.4 and future editions, in which all styles conform to the style schema. When ODF 1.3 is issued as a Candidate OASIS Standard, a version of the text of all four Parts is created in which all styles follow the style schema. The text so created is imported into the new template to generate a clean working draft of ODF 1.4.   In order to create a well-defined style schema, the editors will need to complete the current review of styles in ODF 1.3, deciding which styles are needed, what properties they should have and how they should be used. I anticipate that this process, ending with the issue of style schema, template and first working draft of ODF 1.4, will take a further two or three weeks.   In order to support work on extracting default attribute values from the Part 3 specification, and to improve the HTML generated from the ODT file, I have already prepared an informal draft of Part 3, based upon CSD02, in which the style definitions are reset to what they were in early working drafts (which corresponded better to the styles used in ODF 1.2) and the paragraph style ‘Default Value’ is re-applied to paragraphs in which default attribute values are specified.   Francis


  • 2.  Re: [office] Review of style use in ODF 1.3 specifications

    Posted 07-06-2020 13:13
    Hi Francis, Thanks for the update! Allow me three follow-up questions & suggestions: How about adding those editing subtasks to JIRA, perhaps those to be fixed for ODF 1.3 CS02 becoming part of OFFICE-4079 and those for later as a new ODF 1.4 editorial issue. What makes your review preliminary? What is missing? Could you point the documents you base your experiences from JIRA (and/or put your latest working draft to GitHub)? How about adding the automated tooling for changing the styles as part of the ODF-TC repo - these search & replace tasks should be done by automation. Thanks for your help! Talks to you soon! Svante Am So., 5. Juli 2020 um 23:52 Uhr schrieb Francis Cave < francis@franciscave.com >: My action under item 5 of the TC meeting on June 29 was to report in my review of use of styles in the ODF 1.3 specifications. I have performed a preliminary review of the use of paragraph, character and list styles in Parts 2, 3 and 4 of the specifications, considering all drafts issued between July 2018 and January 2020 (CSD02). All three Parts exhibit similar problems, of which the main cases are: Two or more styles being used for the same purpose within a draft, e.g. the paragraph styles Text Body and Default Style both being used for body text. New styles being introduced in later drafts, e.g. the conditional paragraph style Appendix Heading being replaced by the non-conditional paragraph style AppendixHeading1 in CSD02 only. Styles being dropped in later drafts, e.g. the paragraph style Default Value , applied to paragraphs that contain default attribute values, was somehow removed from Part 3 in WD13-03 onwards. Many styles whose purpose is unclear and which appear to overlap other styles, e.g. in Part 3 there are four character styles Attribute Value , Attribute Value Fragment , Attribute Value Instance and Attribute Value Param . Another example: Part 4 contains list styles Example Numbering , Numbering 1 and Numbering 5 (what happened to Numbering 2 , 3 and 4 ?). Poor naming of styles, e.g. the character style Furmula Sub [sic] in Part 3, and inconsistent use of title case in style names. Lack of stability in style definitions, which seem to change, especially in CSD01 and CSD02, e.g. changes to space above and below paragraphs, font sizes, background colors, etc. My proposal is that the first Working Draft of ODF 1.4 should be based upon a template in which the named styles are well-defined in terms of their naming conventions, their definitions and their planned usage. For this to be achieved, the editors should ensure that: A well-defined style schema is prepared, detailing the names, properties and intended usage of all paragraph, character and list styles. There is a single text template to be used as a basis for drafting all Parts of ODF 1.4 and future editions, in which all styles conform to the style schema. When ODF 1.3 is issued as a Candidate OASIS Standard, a version of the text of all four Parts is created in which all styles follow the style schema. The text so created is imported into the new template to generate a clean working draft of ODF 1.4. In order to create a well-defined style schema, the editors will need to complete the current review of styles in ODF 1.3, deciding which styles are needed, what properties they should have and how they should be used. I anticipate that this process, ending with the issue of style schema, template and first working draft of ODF 1.4, will take a further two or three weeks. In order to support work on extracting default attribute values from the Part 3 specification, and to improve the HTML generated from the ODT file, I have already prepared an informal draft of Part 3, based upon CSD02, in which the style definitions are reset to what they were in early working drafts (which corresponded better to the styles used in ODF 1.2) and the paragraph style Default Value is re-applied to paragraphs in which default attribute values are specified. Francis


  • 3.  RE: [office] Review of style use in ODF 1.3 specifications

    Posted 07-06-2020 14:20
    Hi Svante   Regarding your suggestions:   I have commented on OFFICE-4079, indicating how most of this issue can be resolved. I can raise a new JIRA issue, if that is appropriate, for the editorial tasks I think need to be carried out for ODF 1.4, but I ve not raised a JIRA issue before and maybe someone with more experience could guide me through this the first time.


  • 4.  Re: [office] Review of style use in ODF 1.3 specifications

    Posted 07-16-2020 18:10
    Hello Francis, when I was searching for further information on Daniel Carreras ODF 1.2 Formulas Test Suite Generator, I was stumbling over the ODF TC Wiki: https://wiki.oasis-open.org/office/FrontPage Most interesting is the page explaining the styling of the specification: https://wiki.oasis-open.org/office/How_to_prepare_ODF_specification_documents Perhaps this might help you in your styles task! I have gathered all XSLT files mentioned in the ODF Toolkit: https://github.com/tdf/odftoolkit/tree/master/xslt-runner/src/test/resources/xslt If you would not have started your work, yet, I would even consider going back to ODF 1.2 styling, create a mapping between ODF 1.3 and ODF 1.2 styles and replace the ODF 1.3 styles with ODF 1.2 via ODFDOM (Java). Doing some tests that no automatic styles are being used, concatenation consecutive spans with the same style, etc. I wonder how in the future OASIS will come up with new styling wishes in the future, perhaps we will discuss this together. Had a long phone call with Jos (former ODF-TC co-chair) last week and he was suggesting the following: https://designingwithlibreoffice.com/ We should keep in the back of our mind that we should strive for a generation of the specification from data - as we are already partly doing it. And should avoid manual tweakings at all costs and should gather scripts of cleaning-up, transforming our existing specification. Best regards, Svante Am Mo., 6. Juli 2020 um 16:19 Uhr schrieb Francis Cave < francis@franciscave.com >: Hi Svante Regarding your suggestions: I have commented on OFFICE-4079, indicating how most of this issue can be resolved. I can raise a new JIRA issue, if that is appropriate, for the editorial tasks I think need to be carried out for ODF 1.4, but I ve not raised a JIRA issue before and maybe someone with more experience could guide me through this the first time. ð My review is preliminary because a detailed reading of the specification may reveal additional styling and formatting issues that I haven t spotted so far, e.g. where direct formatting is overriding named styles (I haven t checked direct formatting overrides). I attach a spreadsheet that contains a list of the named styles that are used in the drafts of Parts 2, 3 and 4 that I have reviewed (in case there are any oddities in this spreadsheet, I created it in Google Drive to share with Patrick, and have downloaded a copy just now). Well, I m not sure about this. My hope is that this task only has to be done once and never again! ð In that case the effort in fully automating the task may not be worthwhile. Global search-and-replace in LibreOffice may be quicker for changing paragraph styles, and global search-and-replace in Oxygen may be quicker for changing character and list styles. Kind regards, Francis From: office@lists.oasis-open.org < office@lists.oasis-open.org > On Behalf Of Svante Schubert Sent: 06 July 2020 14:12 To: Francis Cave < francis@franciscave.com > Cc: office@lists.oasis-open.org Subject: Re: [office] Review of style use in ODF 1.3 specifications Hi Francis, Thanks for the update! Allow me three follow-up questions & suggestions: How about adding those editing subtasks to JIRA, perhaps those to be fixed for ODF 1.3 CS02 becoming part of OFFICE-4079 and those for later as a new ODF 1.4 editorial issue. What makes your review preliminary? What is missing? Could you point the documents you base your experiences from JIRA (and/or put your latest working draft to GitHub)? How about adding the automated tooling for changing the styles as part of the ODF-TC repo - these search & replace tasks should be done by automation. Thanks for your help! Talks to you soon! Svante Am So., 5. Juli 2020 um 23:52 Uhr schrieb Francis Cave < francis@franciscave.com >: My action under item 5 of the TC meeting on June 29 was to report in my review of use of styles in the ODF 1.3 specifications. I have performed a preliminary review of the use of paragraph, character and list styles in Parts 2, 3 and 4 of the specifications, considering all drafts issued between July 2018 and January 2020 (CSD02). All three Parts exhibit similar problems, of which the main cases are: Two or more styles being used for the same purpose within a draft, e.g. the paragraph styles Text Body and Default Style both being used for body text. New styles being introduced in later drafts, e.g. the conditional paragraph style Appendix Heading being replaced by the non-conditional paragraph style AppendixHeading1 in CSD02 only. Styles being dropped in later drafts, e.g. the paragraph style Default Value , applied to paragraphs that contain default attribute values, was somehow removed from Part 3 in WD13-03 onwards. Many styles whose purpose is unclear and which appear to overlap other styles, e.g. in Part 3 there are four character styles Attribute Value , Attribute Value Fragment , Attribute Value Instance and Attribute Value Param . Another example: Part 4 contains list styles Example Numbering , Numbering 1 and Numbering 5 (what happened to Numbering 2 , 3 and 4 ?). Poor naming of styles, e.g. the character style Furmula Sub [sic] in Part 3, and inconsistent use of title case in style names. Lack of stability in style definitions, which seem to change, especially in CSD01 and CSD02, e.g. changes to space above and below paragraphs, font sizes, background colors, etc. My proposal is that the first Working Draft of ODF 1.4 should be based upon a template in which the named styles are well-defined in terms of their naming conventions, their definitions and their planned usage. For this to be achieved, the editors should ensure that: A well-defined style schema is prepared, detailing the names, properties and intended usage of all paragraph, character and list styles. There is a single text template to be used as a basis for drafting all Parts of ODF 1.4 and future editions, in which all styles conform to the style schema. When ODF 1.3 is issued as a Candidate OASIS Standard, a version of the text of all four Parts is created in which all styles follow the style schema. The text so created is imported into the new template to generate a clean working draft of ODF 1.4. In order to create a well-defined style schema, the editors will need to complete the current review of styles in ODF 1.3, deciding which styles are needed, what properties they should have and how they should be used. I anticipate that this process, ending with the issue of style schema, template and first working draft of ODF 1.4, will take a further two or three weeks. In order to support work on extracting default attribute values from the Part 3 specification, and to improve the HTML generated from the ODT file, I have already prepared an informal draft of Part 3, based upon CSD02, in which the style definitions are reset to what they were in early working drafts (which corresponded better to the styles used in ODF 1.2) and the paragraph style Default Value is re-applied to paragraphs in which default attribute values are specified. Francis


  • 5.  RE: [office] Review of style use in ODF 1.3 specifications

    Posted 07-16-2020 20:32
    Hi Svante   I have been working on the styling of Parts 2 Packaging and 3 Schema, with a view to creating fairly soon a clean styling of an initial working draft of ODF 1.4. However, I do not expect that the documents I m working on will definitely be used for the first working draft of ODF 1.4. They are, in a sense, experimental, helping me to understand how and why these documents are styled the way that they are. In the preparation of ODF 1.3 Patrick and I were mainly concerned with text content, not with styling, although obviously we tried to be consistent.   I m not sure that reverting to the styling of ODF 1.2 will be much help. My impression (which will have to be confirmed by more detailed analysis) is that the styling of ODF 1.2 is at least as inconsistent as the styling of ODF 1.3, because I believe that most of the inconsistencies that I have discovered are in text that did not change between ODF 1.2 and ODF 1.3. ODF 1.2 is full of editorial mistakes, which is why Patrick and I took so much time last year going through the text and finding and proposing fixes for hundreds of textual errors, so there are certainly lots of styling errors too.   I m also not certain what is the best way to maintain the documentation in future. Programmers love the idea that documentation can be generated from data or in our case from schemas but that is because they don t care too much about the readability of the documentation, especially if they are already very familiar with the schemas and their implementation. But standards have to reach a high level of quality as human-readable text, especially for non-native-English readers, so the text has to be presented clearly and as simply as possible. The use of typographic features such as lists, tables, math formulae and other stylistic distinctions is an important part of ensuring maximum readability by new implementers who are unfamiliar with ODF and for whom English is not their native language. So, while it would be possible to embed ODF or HTML in the schema, making it possible to generate good-quality documentation, simpler methods such as using Markdown would not work, because they lack sufficient typographic features to ensure maximum readability of the results. But if we re going to be embedding ODF in the schema, we might as well draft that ODF in an ODF editor, since doing so as raw XML in an XML schema editor makes no sense at all. So, I think this has to be a two-way process: text embedded in data has to be generated first from documents, so that documentation can later be generated from text embedded in data.   With any type of automation at some point there is likely be a law of diminishing returns that comes into play. I m not saying we shoudn t automate, but we should bear in mind that total automation of everything may not be worth the effort. For some tasks editors are cheaper to employ than programmers!


  • 6.  New styles & possible future high-level design goals for editors - Re: [office] Review of style use in ODF 1.3 specifications

    Posted 07-17-2020 15:40
    Hi Francis, Am Do., 16. Juli 2020 um 22:31 Uhr schrieb Francis Cave < francis@franciscave.com >: Hi Svante I have been working on the styling of Parts 2 Packaging and 3 Schema, with a view to creating fairly soon a clean styling of an initial working draft of ODF 1.4. However, I do not expect that the documents I m working on will definitely be used for the first working draft of ODF 1.4. They are, in a sense, experimental, helping me to understand how and why these documents are styled the way that they are. In the preparation of ODF 1.3 Patrick and I were mainly concerned with text content, not with styling, although obviously we tried to be consistent. I m not sure that reverting to the styling of ODF 1.2 will be much help. My impression (which will have to be confirmed by more detailed analysis) is that the styling of ODF 1.2 is at least as inconsistent as the styling of ODF 1.3, because I believe that most of the inconsistencies that I have discovered are in text that did not change between ODF 1.2 and ODF 1.3. ODF 1.2 is full of editorial mistakes, which is why Patrick and I took so much time last year going through the text and finding and proposing fixes for hundreds of textual errors, so there are certainly lots of styling errors too. If there is an updated "clean" styling version available soon, there is certainly no reason to go back to ODF 1.2. Still, I am very curious about the new design decisions you and Patrick made for the ODF 1.3/1.4 styles. Therefore, I spend some time to transform the old description of ODF 1.2 styles from the ODF TC (MoinMoin) Wiki markdown: https://wiki.oasis-open.org/office/How_to_prepare_ODF_specification_documents to the (Media)Wiki markdown dialect of GitHub: https://github.com/oasis-tcs/odf-tc/blob/master/src/test/resources/odf1.3/tools/How_to_prepare_ODF_specification_documents.md and fixed some references. To keep us (and next generations) updated, you might want to document the new ODF 1.3 (or ODF 1.4) styling that you and Patrick are about to establish on the above GitHub URL. Does this sound like a reasonable idea to you, Francis? I m also not certain what is the best way to maintain the documentation in future. Programmers love the idea that documentation can be generated from data or in our case from schemas but that is because they don t care too much about the readability of the documentation, especially if they are already very familiar with the schemas and their implementation. But standards have to reach a high level of quality as human-readable text, especially for non-native-English readers, so the text has to be presented clearly and as simply as possible. The use of typographic features such as lists, tables, math formulae and other stylistic distinctions is an important part of ensuring maximum readability by new implementers who are unfamiliar with ODF and for whom English is not their native language. So, while it would be possible to embed ODF or HTML in the schema, making it possible to generate good-quality documentation, simpler methods such as using Markdown would not work, because they lack sufficient typographic features to ensure maximum readability of the results. But if we re going to be embedding ODF in the schema, we might as well draft that ODF in an ODF editor, since doing so as raw XML in an XML schema editor makes no sense at all. So, I think this has to be a two-way process: text embedded in data has to be generated first from documents, so that documentation can later be generated from text embedded in data. With any type of automation at some point there is likely be a law of diminishing returns that comes into play. I m not saying we shoudn t automate, but we should bear in mind that total automation of everything may not be worth the effort. For some tasks editors are cheaper to employ than programmers! ð Perhaps we are crosstalking a bit. A well-written specification that is easy to understand is still the highest goal to me and technical editors - like you - are best suited for such a task . Aside from this, is there anything else that may improve the quality of a software specification? Is there any other measurement of quality? Let me give it a try: The purpose of the ODF specification is likely being the blueprint for software developers implementing ODF applications. Software developers - like everyone - have little time and are not keenly reading the full ODF specification. Instead, they will try to save time and will read instead only those parts being absolutely necessary for them. Like Alfred & Rich asked for an ODF 1.3 feature DIFF for their development department at Microsoft. Therefore, the less time an ODF application implementor requires to create (or adjust) their ODF application, the better the ODF specification . Test documents and conformance tests provided with the ODF specification will raise the overall quality of the specification , as developers do not have to write their own test documents and tests again and save time again (Alfred & Rich also asked for ODF 1.3 test documents). Now there comes our first trick: ODF developers might save additional programming time if required data from the specification can be overtaken automatically in their software process . This is now already possible and easy for repeating information (pattern) that can be provided as a machine-readable data-set, like our upcoming list of default values being extracted from the specification. This machine-readable information could/should be used by ODF programmers to generate parts of the source code fo the ODF application. Therefore, the more we provide as machine-readable information, the easier it gets for ODF application developers in the future . Our next trick is: instead of extracting the machine-readable data from the specification, we put the extracted data at the beginning of the standardization process and generate the human-readable part from it. By this we can be sure, we have not incidentally added duplicated, contradicting data. You might ask yourself, how much data can be provided as machine-readable data? Or the other way around, what information has to be explained by humans? I am uncertain myself, but it seems like a very good idea to strive for it and a long-term design goal to question every part of the spec if it can be generated and if not, what information is missing. What currently missing in the ODF specification in general, is the clear distinction between the semantic parts of the document (known to the common user), like a paragraph, image, table, cell and its states (e.g. empty cell) and their correlating XML representation. This seems like reasonable major editor's task we might want to focus on in the future and a technical writer like you could be of tremendous help in fulfilling this. Kind regards, Svante From: office@lists.oasis-open.org < office@lists.oasis-open.org > On Behalf Of Svante Schubert Sent: 16 July 2020 19:10 To: Francis Cave < francis@franciscave.com > Cc: office@lists.oasis-open.org Subject: Re: [office] Review of style use in ODF 1.3 specifications Hello Francis, when I was searching for further information on Daniel Carreras ODF 1.2 Formulas Test Suite Generator, I was stumbling over the ODF TC Wiki: https://wiki.oasis-open.org/office/FrontPage Most interesting is the page explaining the styling of the specification: https://wiki.oasis-open.org/office/How_to_prepare_ODF_specification_documents Perhaps this might help you in your styles task! I have gathered all XSLT files mentioned in the ODF Toolkit: https://github.com/tdf/odftoolkit/tree/master/xslt-runner/src/test/resources/xslt If you would not have started your work, yet, I would even consider going back to ODF 1.2 styling, create a mapping between ODF 1.3 and ODF 1.2 styles and replace the ODF 1.3 styles with ODF 1.2 via ODFDOM (Java). Doing some tests that no automatic styles are being used, concatenation consecutive spans with the same style, etc. I wonder how in the future OASIS will come up with new styling wishes in the future, perhaps we will discuss this together. Had a long phone call with Jos (former ODF-TC co-chair) last week and he was suggesting the following: https://designingwithlibreoffice.com/ We should keep in the back of our mind that we should strive for a generation of the specification from data - as we are already partly doing it. And should avoid manual tweakings at all costs and should gather scripts of cleaning-up, transforming our existing specification. Best regards, Svante Am Mo., 6. Juli 2020 um 16:19 Uhr schrieb Francis Cave < francis@franciscave.com >: Hi Svante Regarding your suggestions: I have commented on OFFICE-4079, indicating how most of this issue can be resolved. I can raise a new JIRA issue, if that is appropriate, for the editorial tasks I think need to be carried out for ODF 1.4, but I ve not raised a JIRA issue before and maybe someone with more experience could guide me through this the first time. ð My review is preliminary because a detailed reading of the specification may reveal additional styling and formatting issues that I haven t spotted so far, e.g. where direct formatting is overriding named styles (I haven t checked direct formatting overrides). I attach a spreadsheet that contains a list of the named styles that are used in the drafts of Parts 2, 3 and 4 that I have reviewed (in case there are any oddities in this spreadsheet, I created it in Google Drive to share with Patrick, and have downloaded a copy just now). Well, I m not sure about this. My hope is that this task only has to be done once and never again! ð In that case the effort in fully automating the task may not be worthwhile. Global search-and-replace in LibreOffice may be quicker for changing paragraph styles, and global search-and-replace in Oxygen may be quicker for changing character and list styles. Kind regards, Francis From: office@lists.oasis-open.org < office@lists.oasis-open.org > On Behalf Of Svante Schubert Sent: 06 July 2020 14:12 To: Francis Cave < francis@franciscave.com > Cc: office@lists.oasis-open.org Subject: Re: [office] Review of style use in ODF 1.3 specifications Hi Francis, Thanks for the update! Allow me three follow-up questions & suggestions: How about adding those editing subtasks to JIRA, perhaps those to be fixed for ODF 1.3 CS02 becoming part of OFFICE-4079 and those for later as a new ODF 1.4 editorial issue. What makes your review preliminary? What is missing? Could you point the documents you base your experiences from JIRA (and/or put your latest working draft to GitHub)? How about adding the automated tooling for changing the styles as part of the ODF-TC repo - these search & replace tasks should be done by automation. Thanks for your help! Talks to you soon! Svante Am So., 5. Juli 2020 um 23:52 Uhr schrieb Francis Cave < francis@franciscave.com >: My action under item 5 of the TC meeting on June 29 was to report in my review of use of styles in the ODF 1.3 specifications. I have performed a preliminary review of the use of paragraph, character and list styles in Parts 2, 3 and 4 of the specifications, considering all drafts issued between July 2018 and January 2020 (CSD02). All three Parts exhibit similar problems, of which the main cases are: Two or more styles being used for the same purpose within a draft, e.g. the paragraph styles Text Body and Default Style both being used for body text. New styles being introduced in later drafts, e.g. the conditional paragraph style Appendix Heading being replaced by the non-conditional paragraph style AppendixHeading1 in CSD02 only. Styles being dropped in later drafts, e.g. the paragraph style Default Value , applied to paragraphs that contain default attribute values, was somehow removed from Part 3 in WD13-03 onwards. Many styles whose purpose is unclear and which appear to overlap other styles, e.g. in Part 3 there are four character styles Attribute Value , Attribute Value Fragment , Attribute Value Instance and Attribute Value Param . Another example: Part 4 contains list styles Example Numbering , Numbering 1 and Numbering 5 (what happened to Numbering 2 , 3 and 4 ?). Poor naming of styles, e.g. the character style Furmula Sub [sic] in Part 3, and inconsistent use of title case in style names. Lack of stability in style definitions, which seem to change, especially in CSD01 and CSD02, e.g. changes to space above and below paragraphs, font sizes, background colors, etc. My proposal is that the first Working Draft of ODF 1.4 should be based upon a template in which the named styles are well-defined in terms of their naming conventions, their definitions and their planned usage. For this to be achieved, the editors should ensure that: A well-defined style schema is prepared, detailing the names, properties and intended usage of all paragraph, character and list styles. There is a single text template to be used as a basis for drafting all Parts of ODF 1.4 and future editions, in which all styles conform to the style schema. When ODF 1.3 is issued as a Candidate OASIS Standard, a version of the text of all four Parts is created in which all styles follow the style schema. The text so created is imported into the new template to generate a clean working draft of ODF 1.4. In order to create a well-defined style schema, the editors will need to complete the current review of styles in ODF 1.3, deciding which styles are needed, what properties they should have and how they should be used. I anticipate that this process, ending with the issue of style schema, template and first working draft of ODF 1.4, will take a further two or three weeks. In order to support work on extracting default attribute values from the Part 3 specification, and to improve the HTML generated from the ODT file, I have already prepared an informal draft of Part 3, based upon CSD02, in which the style definitions are reset to what they were in early working drafts (which corresponded better to the styles used in ODF 1.2) and the paragraph style Default Value is re-applied to paragraphs in which default attribute values are specified. Francis


  • 7.  RE: [office] New styles & possible future high-level design goals for editors - Re: [office] Review of style use in ODF 1.3 specifications

    Posted 07-19-2020 23:32
    Hi Svante   I have checked the style conventions documented in https://wiki.oasis-open.org/office/How_to_prepare_ODF_specification_documents  and I am not proposing any changes in these styles for ODF 1.4.   I haven t been able to make progress on Part 4 Formula, but I will make sure that the paragraph styles Rationale and Offset Note are kept.   I don t think we re fundamentally disagreeing about the value of machine-readable documentation. Where it is possible to make the information machine-interpretable without compromising human readability we should do this. But we should also bear in mind that in future ISO editions of ODF will probably have to conform more closely to ISO house style, and (wearing my SC 34 Chairman s hat) I already anticipate significant trouble ahead attempting to reconcile the need to make our ISO standards machine-interpretable with the demands of ISO editors. ISO keywords are just the start   Kind regards,   Francis     From: office@lists.oasis-open.org <office@lists.oasis-open.org> On Behalf Of Svante Schubert Sent: 17 July 2020 16:40 To: Francis Cave <francis@franciscave.com> Cc: office@lists.oasis-open.org Subject: [office] New styles & possible future high-level design goals for editors - Re: [office] Review of style use in ODF 1.3 specifications   Hi Francis,   Am Do., 16. Juli 2020 um 22:31 Uhr schrieb Francis Cave < francis@franciscave.com >: Hi Svante   I have been working on the styling of Parts 2 Packaging and 3 Schema, with a view to creating fairly soon a clean styling of an initial working draft of ODF 1.4. However, I do not expect that the documents I m working on will definitely be used for the first working draft of ODF 1.4. They are, in a sense, experimental, helping me to understand how and why these documents are styled the way that they are. In the preparation of ODF 1.3 Patrick and I were mainly concerned with text content, not with styling, although obviously we tried to be consistent.   I m not sure that reverting to the styling of ODF 1.2 will be much help. My impression (which will have to be confirmed by more detailed analysis) is that the styling of ODF 1.2 is at least as inconsistent as the styling of ODF 1.3, because I believe that most of the inconsistencies that I have discovered are in text that did not change between ODF 1.2 and ODF 1.3. ODF 1.2 is full of editorial mistakes, which is why Patrick and I took so much time last year going through the text and finding and proposing fixes for hundreds of textual errors, so there are certainly lots of styling errors too.   If there is an updated "clean" styling version available soon, there is certainly no reason to go back to ODF 1.2. Still, I am very curious about the new design decisions you and Patrick made for the ODF 1.3/1.4 styles.  Therefore, I spend some time to transform the old description of ODF 1.2 styles from the ODF TC (MoinMoin) Wiki markdown: https://wiki.oasis-open.org/office/How_to_prepare_ODF_specification_documents   to the (Media)Wiki markdown dialect of GitHub: https://github.com/oasis-tcs/odf-tc/blob/master/src/test/resources/odf1.3/tools/How_to_prepare_ODF_specification_documents.md    and fixed some references. To keep us (and next generations) updated, you might want to document the new ODF 1.3 (or ODF 1.4) styling that you and Patrick are about to establish on the above GitHub URL. Does this sound like a reasonable idea to you, Francis?   I m also not certain what is the best way to maintain the documentation in future. Programmers love the idea that documentation can be generated from data or in our case from schemas but that is because they don t care too much about the readability of the documentation, especially if they are already very familiar with the schemas and their implementation. But standards have to reach a high level of quality as human-readable text, especially for non-native-English readers, so the text has to be presented clearly and as simply as possible. The use of typographic features such as lists, tables, math formulae and other stylistic distinctions is an important part of ensuring maximum readability by new implementers who are unfamiliar with ODF and for whom English is not their native language. So, while it would be possible to embed ODF or HTML in the schema, making it possible to generate good-quality documentation, simpler methods such as using Markdown would not work, because they lack sufficient typographic features to ensure maximum readability of the results. But if we re going to be embedding ODF in the schema, we might as well draft that ODF in an ODF editor, since doing so as raw XML in an XML schema editor makes no sense at all. So, I think this has to be a two-way process: text embedded in data has to be generated first from documents, so that documentation can later be generated from text embedded in data.    With any type of automation at some point there is likely be a law of diminishing returns that comes into play. I m not saying we shoudn t automate, but we should bear in mind that total automation of everything may not be worth the effort. For some tasks editors are cheaper to employ than programmers!


  • 8.  Re: [office] New styles & possible future high-level design goals for editors - Re: [office] Review of style use in ODF 1.3 specifications

    Posted 07-20-2020 09:37
    Hello Francis, Thank you for pointing out ISO as another system outside the ODF TC that we are dependent on and should keep an eye on. Our TC deliverables should indeed harmonize not only with any upcoming OASIS styling guidelines but also with those requirements from ISO. Still, I am very optimistic to cover both as the more we are striving to automate our delivery processes (via GitHub using Maven) the more we are able to adapt more easily. In theory, we would be even able to deliver two versions for the different addressee. We should try to go get the range of requirements of OASIS & ISO as soon as possible. I might add also my knowledge and impression of ISO to this discussion: From what I heard and see, ISO, CEN/CENELEC and the National Standardisation Bodies (as BSI, ANSI or DIN) are very connected. They sharing for instance the same backend infrastructure (likely worldwide). After decades of using the same standard software for their backend, ISO has recently started in some ISO groups to test a new system. From what I heard of DIN, their idea/hope in using machine-readable specification is not only to sell PDF as usual but increase their income by adding data as a service. For the maintenance of machine-readable data, ISO is evaluating https://www.fontoxml.com/ as XML content editor using tags such as https://www.niso-sts.org/Samples.html Unfortunately, I was not able to provide feedback to the decision-makers, but from my perspective, the approach is questionable, not only because it seems similar to the Custom XML feature Word once used before it was dropped due to a patent problem. In any case, we should be able to generate an ISO (& OASIS) related version that suits their requirements as soon they are publicly available. Regarding our likely future design goal for our specifications in adding semantic and separating the XML definition from it, I might point out this design to be a very good way to modularize/separate the complexity of the spec. Especially, as often an ODF core-application developer just receives the data from the "filter developer" who imported the XML into the run-time-model of the application. At run-time, there is usually no longer an XML representation existent, in contrary to browsers who can always rely on a DOM model at run-time. Therefore, a separation between XML and its high-level semantic will ease the use cases of the specification of our developer user groups. For this reason, we might consider extending our styling set for a semantic layer/perspective: Like semantic entities (paragraph, table, image, cell, etc.) and their properties (e.g. bold, italic,..) and perhaps even values or states (e.g. 'empty cell'). Hope you are at the beginning of a great week! Svante Am Mo., 20. Juli 2020 um 01:32 Uhr schrieb Francis Cave < francis@franciscave.com >: Hi Svante I have checked the style conventions documented in https://wiki.oasis-open.org/office/How_to_prepare_ODF_specification_documents and I am not proposing any changes in these styles for ODF 1.4. I haven t been able to make progress on Part 4 Formula, but I will make sure that the paragraph styles Rationale and Offset Note are kept. I don t think we re fundamentally disagreeing about the value of machine-readable documentation. Where it is possible to make the information machine-interpretable without compromising human readability we should do this. But we should also bear in mind that in future ISO editions of ODF will probably have to conform more closely to ISO house style, and (wearing my SC 34 Chairman s hat) I already anticipate significant trouble ahead attempting to reconcile the need to make our ISO standards machine-interpretable with the demands of ISO editors. ISO keywords are just the start Kind regards, Francis From: office@lists.oasis-open.org < office@lists.oasis-open.org > On Behalf Of Svante Schubert Sent: 17 July 2020 16:40 To: Francis Cave < francis@franciscave.com > Cc: office@lists.oasis-open.org Subject: [office] New styles & possible future high-level design goals for editors - Re: [office] Review of style use in ODF 1.3 specifications Hi Francis, Am Do., 16. Juli 2020 um 22:31 Uhr schrieb Francis Cave < francis@franciscave.com >: Hi Svante I have been working on the styling of Parts 2 Packaging and 3 Schema, with a view to creating fairly soon a clean styling of an initial working draft of ODF 1.4. However, I do not expect that the documents I m working on will definitely be used for the first working draft of ODF 1.4. They are, in a sense, experimental, helping me to understand how and why these documents are styled the way that they are. In the preparation of ODF 1.3 Patrick and I were mainly concerned with text content, not with styling, although obviously we tried to be consistent. I m not sure that reverting to the styling of ODF 1.2 will be much help. My impression (which will have to be confirmed by more detailed analysis) is that the styling of ODF 1.2 is at least as inconsistent as the styling of ODF 1.3, because I believe that most of the inconsistencies that I have discovered are in text that did not change between ODF 1.2 and ODF 1.3. ODF 1.2 is full of editorial mistakes, which is why Patrick and I took so much time last year going through the text and finding and proposing fixes for hundreds of textual errors, so there are certainly lots of styling errors too. If there is an updated "clean" styling version available soon, there is certainly no reason to go back to ODF 1.2. Still, I am very curious about the new design decisions you and Patrick made for the ODF 1.3/1.4 styles. Therefore, I spend some time to transform the old description of ODF 1.2 styles from the ODF TC (MoinMoin) Wiki markdown: https://wiki.oasis-open.org/office/How_to_prepare_ODF_specification_documents to the (Media)Wiki markdown dialect of GitHub: https://github.com/oasis-tcs/odf-tc/blob/master/src/test/resources/odf1.3/tools/How_to_prepare_ODF_specification_documents.md and fixed some references. To keep us (and next generations) updated, you might want to document the new ODF 1.3 (or ODF 1.4) styling that you and Patrick are about to establish on the above GitHub URL. Does this sound like a reasonable idea to you, Francis? I m also not certain what is the best way to maintain the documentation in future. Programmers love the idea that documentation can be generated from data or in our case from schemas but that is because they don t care too much about the readability of the documentation, especially if they are already very familiar with the schemas and their implementation. But standards have to reach a high level of quality as human-readable text, especially for non-native-English readers, so the text has to be presented clearly and as simply as possible. The use of typographic features such as lists, tables, math formulae and other stylistic distinctions is an important part of ensuring maximum readability by new implementers who are unfamiliar with ODF and for whom English is not their native language. So, while it would be possible to embed ODF or HTML in the schema, making it possible to generate good-quality documentation, simpler methods such as using Markdown would not work, because they lack sufficient typographic features to ensure maximum readability of the results. But if we re going to be embedding ODF in the schema, we might as well draft that ODF in an ODF editor, since doing so as raw XML in an XML schema editor makes no sense at all. So, I think this has to be a two-way process: text embedded in data has to be generated first from documents, so that documentation can later be generated from text embedded in data. With any type of automation at some point there is likely be a law of diminishing returns that comes into play. I m not saying we shoudn t automate, but we should bear in mind that total automation of everything may not be worth the effort. For some tasks editors are cheaper to employ than programmers! ð Perhaps we are crosstalking a bit. A well-written specification that is easy to understand is still the highest goal to me and technical editors - like you - are best suited for such a task . Aside from this, is there anything else that may improve the quality of a software specification? Is there any other measurement of quality? Let me give it a try: The purpose of the ODF specification is likely being the blueprint for software developers implementing ODF applications. Software developers - like everyone - have little time and are not keenly reading the full ODF specification. Instead, they will try to save time and will read instead only those parts being absolutely necessary for them. Like Alfred & Rich asked for an ODF 1.3 feature DIFF for their development department at Microsoft. Therefore, the less time an ODF application implementor requires to create (or adjust) their ODF application, the better the ODF specification . Test documents and conformance tests provided with the ODF specification will raise the overall quality of the specification , as developers do not have to write their own test documents and tests again and save time again (Alfred & Rich also asked for ODF 1.3 test documents). Now there comes our first trick: ODF developers might save additional programming time if required data from the specification can be overtaken automatically in their software process . This is now already possible and easy for repeating information (pattern) that can be provided as a machine-readable data-set, like our upcoming list of default values being extracted from the specification. This machine-readable information could/should be used by ODF programmers to generate parts of the source code fo the ODF application. Therefore, the more we provide as machine-readable information, the easier it gets for ODF application developers in the future . Our next trick is: instead of extracting the machine-readable data from the specification, we put the extracted data at the beginning of the standardization process and generate the human-readable part from it. By this we can be sure, we have not incidentally added duplicated, contradicting data. You might ask yourself, how much data can be provided as machine-readable data? Or the other way around, what information has to be explained by humans? I am uncertain myself, but it seems like a very good idea to strive for it and a long-term design goal to question every part of the spec if it can be generated and if not, what information is missing. What currently missing in the ODF specification in general, is the clear distinction between the semantic parts of the document (known to the common user), like a paragraph, image, table, cell and its states (e.g. empty cell) and their correlating XML representation. This seems like reasonable major editor's task we might want to focus on in the future and a technical writer like you could be of tremendous help in fulfilling this. Kind regards, Svante From: office@lists.oasis-open.org < office@lists.oasis-open.org > On Behalf Of Svante Schubert Sent: 16 July 2020 19:10 To: Francis Cave < francis@franciscave.com > Cc: office@lists.oasis-open.org Subject: Re: [office] Review of style use in ODF 1.3 specifications Hello Francis, when I was searching for further information on Daniel Carreras ODF 1.2 Formulas Test Suite Generator, I was stumbling over the ODF TC Wiki: https://wiki.oasis-open.org/office/FrontPage Most interesting is the page explaining the styling of the specification: https://wiki.oasis-open.org/office/How_to_prepare_ODF_specification_documents Perhaps this might help you in your styles task! I have gathered all XSLT files mentioned in the ODF Toolkit: https://github.com/tdf/odftoolkit/tree/master/xslt-runner/src/test/resources/xslt If you would not have started your work, yet, I would even consider going back to ODF 1.2 styling, create a mapping between ODF 1.3 and ODF 1.2 styles and replace the ODF 1.3 styles with ODF 1.2 via ODFDOM (Java). Doing some tests that no automatic styles are being used, concatenation consecutive spans with the same style, etc. I wonder how in the future OASIS will come up with new styling wishes in the future, perhaps we will discuss this together. Had a long phone call with Jos (former ODF-TC co-chair) last week and he was suggesting the following: https://designingwithlibreoffice.com/ We should keep in the back of our mind that we should strive for a generation of the specification from data - as we are already partly doing it. And should avoid manual tweakings at all costs and should gather scripts of cleaning-up, transforming our existing specification. Best regards, Svante Am Mo., 6. Juli 2020 um 16:19 Uhr schrieb Francis Cave < francis@franciscave.com >: Hi Svante Regarding your suggestions: I have commented on OFFICE-4079, indicating how most of this issue can be resolved. I can raise a new JIRA issue, if that is appropriate, for the editorial tasks I think need to be carried out for ODF 1.4, but I ve not raised a JIRA issue before and maybe someone with more experience could guide me through this the first time. ð My review is preliminary because a detailed reading of the specification may reveal additional styling and formatting issues that I haven t spotted so far, e.g. where direct formatting is overriding named styles (I haven t checked direct formatting overrides). I attach a spreadsheet that contains a list of the named styles that are used in the drafts of Parts 2, 3 and 4 that I have reviewed (in case there are any oddities in this spreadsheet, I created it in Google Drive to share with Patrick, and have downloaded a copy just now). Well, I m not sure about this. My hope is that this task only has to be done once and never again! ð In that case the effort in fully automating the task may not be worthwhile. Global search-and-replace in LibreOffice may be quicker for changing paragraph styles, and global search-and-replace in Oxygen may be quicker for changing character and list styles. Kind regards, Francis From: office@lists.oasis-open.org < office@lists.oasis-open.org > On Behalf Of Svante Schubert Sent: 06 July 2020 14:12 To: Francis Cave < francis@franciscave.com > Cc: office@lists.oasis-open.org Subject: Re: [office] Review of style use in ODF 1.3 specifications Hi Francis, Thanks for the update! Allow me three follow-up questions & suggestions: How about adding those editing subtasks to JIRA, perhaps those to be fixed for ODF 1.3 CS02 becoming part of OFFICE-4079 and those for later as a new ODF 1.4 editorial issue. What makes your review preliminary? What is missing? Could you point the documents you base your experiences from JIRA (and/or put your latest working draft to GitHub)? How about adding the automated tooling for changing the styles as part of the ODF-TC repo - these search & replace tasks should be done by automation. Thanks for your help! Talks to you soon! Svante Am So., 5. Juli 2020 um 23:52 Uhr schrieb Francis Cave < francis@franciscave.com >: My action under item 5 of the TC meeting on June 29 was to report in my review of use of styles in the ODF 1.3 specifications. I have performed a preliminary review of the use of paragraph, character and list styles in Parts 2, 3 and 4 of the specifications, considering all drafts issued between July 2018 and January 2020 (CSD02). All three Parts exhibit similar problems, of which the main cases are: Two or more styles being used for the same purpose within a draft, e.g. the paragraph styles Text Body and Default Style both being used for body text. New styles being introduced in later drafts, e.g. the conditional paragraph style Appendix Heading being replaced by the non-conditional paragraph style AppendixHeading1 in CSD02 only. Styles being dropped in later drafts, e.g. the paragraph style Default Value , applied to paragraphs that contain default attribute values, was somehow removed from Part 3 in WD13-03 onwards. Many styles whose purpose is unclear and which appear to overlap other styles, e.g. in Part 3 there are four character styles Attribute Value , Attribute Value Fragment , Attribute Value Instance and Attribute Value Param . Another example: Part 4 contains list styles Example Numbering , Numbering 1 and Numbering 5 (what happened to Numbering 2 , 3 and 4 ?). Poor naming of styles, e.g. the character style Furmula Sub [sic] in Part 3, and inconsistent use of title case in style names. Lack of stability in style definitions, which seem to change, especially in CSD01 and CSD02, e.g. changes to space above and below paragraphs, font sizes, background colors, etc. My proposal is that the first Working Draft of ODF 1.4 should be based upon a template in which the named styles are well-defined in terms of their naming conventions, their definitions and their planned usage. For this to be achieved, the editors should ensure that: A well-defined style schema is prepared, detailing the names, properties and intended usage of all paragraph, character and list styles. There is a single text template to be used as a basis for drafting all Parts of ODF 1.4 and future editions, in which all styles conform to the style schema. When ODF 1.3 is issued as a Candidate OASIS Standard, a version of the text of all four Parts is created in which all styles follow the style schema. The text so created is imported into the new template to generate a clean working draft of ODF 1.4. In order to create a well-defined style schema, the editors will need to complete the current review of styles in ODF 1.3, deciding which styles are needed, what properties they should have and how they should be used. I anticipate that this process, ending with the issue of style schema, template and first working draft of ODF 1.4, will take a further two or three weeks. In order to support work on extracting default attribute values from the Part 3 specification, and to improve the HTML generated from the ODT file, I have already prepared an informal draft of Part 3, based upon CSD02, in which the style definitions are reset to what they were in early working drafts (which corresponded better to the styles used in ODF 1.2) and the paragraph style Default Value is re-applied to paragraphs in which default attribute values are specified. Francis