OASIS DocBook TC2

I'm following up on my action item to continue the discussion of the content model of legalnotice to support some kind of section. I have attached the sample files that Larry sent out 23 October 2018. We were debating whether we should allow section within legalnotice or whether we should add a new legalsection element only for legalnotice. I'll try and summarize the discussion so far. The first question I want to ask is whether we are allowing legalnotice to appear outside of info. That would make such a legalnotice into literal content that would always be rendered in the output, as opposed to metadata in info that may or may not be rendered. I believed we discussed this possibility, for example putting several legalnotices in an appendix, but I'm not sure what we decided. That decision would seem to affect how we structure legalnotice, especially if it contains sections. So do we intend to allow legalnotice as regular content outside of info? If we use section within legalnotice, I don't think we resolved whether we would alter the content model when it is used inside legalnotice. That seems to be something we need to decide as it affects the arguments for and against. For example, if we change the content model of section inside legalsection, then you could not cut and paste sections in and out of legalsection without getting validation errors. Also, users of a content-aware editor would experience restrictions in their element selection that they might not understand. If we don't change the model of section inside legalnotice, then both of these arguments no longer apply. So, do we need to change the content model of section inside legalnotice, and if so, how? -- Bob Stayton Sagehill Enterprises bobs@sagehill.net Attachment: legalnotice-experiments-2.zip Description: Zip compressed data

I think there are times where we would want the legalnotice content as metadata, and also times when the notice needs to be included in the publication. Based on this, I think we do need to allow legalnotice outside of info.
 
For legalsection, I would think we would want to strip out the technical inlines like:
programlisting programlistingco
   
screen screenco screenshot synopsis cmdsynopsis funcsynopsis
   
classsynopsis fieldsynopsis constructorsynopsis
   
destructorsynopsis methodsynopsis
 
I'd even be willing to cut more out of the model, as this content should be pretty cut and dried legalese

Thanks for bringing this up, Bob.
 
I agree with Scott about allowing legalnotice outside of info I think the nature of legal notices has changed a good deal with the proliferation of software products (and, for that matter, hardware products)
that include multiple components, frequently from different sources, integrated into a single solution.  This is particularly important with open source software, which frequently requires presenting the license as part of the requirements to use the software.
 
I was thinking that the content of a section-like thing inside a legalnotice would be essentially the same as a the current legalnotice, with the addition of whatever the section element is called.  Leganotice
does not currently exclude all technical inlines (program listing elements and elements associated with screens are included) but I thought it would make sense to retain the current content model.  Since the content would be different from a normal section,
I would lean towards it being a different element, since I think there are usability issues with elements that change the legal content based on ancestry of the element.  I think presenting it as this is a legal section so it can have whatever you had in
the original legal notice, but broken up into a more reasonable structure makes sense and will be easy to explain.  I have seen a number of legal notices that include screens, so I feel that preserving the current model is reasonable (I think I remember one
with a code fragment but I may be imagining that or confusing it with a README I see a lot of both README and license information since I work on tools to analyzer open source software that is included in HPE products).
 
Thanks for chiming in, Scott.  Good comments.
 
Regards,
Larry Rowland
 


From: docbook-tc@lists.oasis-open.org [mailto:docbook-tc@lists.oasis-open.org]
On Behalf Of Scott Hudson
Sent: Thursday, December 6, 2018 4:03 PM
To: Bob Stayton <bobs@sagehill.net>; DocBook Technical Committee <docbook-tc@lists.oasis-open.org>
Subject: Re: [docbook-tc] legalsection versus section in legalnotice


 
I think there are times where we would want the legalnotice content as metadata, and also times when the notice needs to be included in the publication. Based on this, I think we do need to allow legalnotice outside of info.
 
For legalsection, I would think we would want to strip out the technical inlines like:
programlisting programlistingco
   
screen screenco screenshot synopsis cmdsynopsis funcsynopsis
   
classsynopsis fieldsynopsis constructorsynopsis
   
destructorsynopsis methodsynopsis
 
I'd even be willing to cut more out of the model, as this content should be pretty cut and dried legalese

Thanks for your quick responses. If we are going to allow legalnotice outside of info, then we have do settle what class of element it will be so we can determine how it fits into other content models. Most of our elements can be classified as hierarchical, block, or inline. The current legalnotice would be considered a block element and could appear anywhere within a section alongside tables and paras and figures. If a new legalnotice contains sections, doesn't that make it a kind of section itself? That is, could you put a legalnotice in the middle of a section, add subsections to it, and continue with block content after the legalnotice closing tag? We don't allow block content after a regular section. Perhaps if it is going to be in content, then we should just call it legalsection, and allow it as another flavor of section wherever section is allowed? It could contain nested legalsections as needed. Bob Stayton Sagehill Enterprises bobs@sagehill.net On 12/6/2018 3:28 PM, Rowland, Larry wrote: Thanks for bringing this up, Bob. I agree with Scott about allowing legalnotice outside of info I think the nature of legal notices has changed a good deal with the proliferation of software products (and, for that matter, hardware products) that include multiple components, frequently from different sources, integrated into a single solution. This is particularly important with open source software, which frequently requires presenting the license as part of the requirements to use the software. I was thinking that the content of a section-like thing inside a legalnotice would be essentially the same as a the current legalnotice, with the addition of whatever the section element is called. Leganotice does not currently exclude all technical inlines (program listing elements and elements associated with screens are included) but I thought it would make sense to retain the current content model. Since the content would be different from a normal section, I would lean towards it being a different element, since I think there are usability issues with elements that change the legal content based on ancestry of the element. I think presenting it as this is a legal section so it can have whatever you had in the original legal notice, but broken up into a more reasonable structure makes sense and will be easy to explain. I have seen a number of legal notices that include screens, so I feel that preserving the current model is reasonable (I think I remember one with a code fragment but I may be imagining that or confusing it with a README I see a lot of both README and license information since I work on tools to analyzer open source software that is included in HPE products). Thanks for chiming in, Scott. Good comments. Regards, Larry Rowland From: docbook-tc@lists.oasis-open.org [ mailto:docbook-tc@lists.oasis-open.org ] On Behalf Of Scott Hudson Sent: Thursday, December 6, 2018 4:03 PM To: Bob Stayton <bobs@sagehill.net> ; DocBook Technical Committee <docbook-tc@lists.oasis-open.org> Subject: Re: [docbook-tc] legalsection versus section in legalnotice I think there are times where we would want the legalnotice content as metadata, and also times when the notice needs to be included in the publication. Based on this, I think we do need to allow legalnotice outside of info. For legalsection, I would think we would want to strip out the technical inlines like: programlisting programlistingco screen screenco screenshot synopsis cmdsynopsis funcsynopsis classsynopsis fieldsynopsis constructorsynopsis destructorsynopsis methodsynopsis I'd even be willing to cut more out of the model, as this content should be pretty cut and dried legalese ð I'd also be ok with just allowing section directly for the reuse opportunities and minimal impact to user expectations. --Scott From: < docbook-tc@lists.oasis-open.org > on behalf of Bob Stayton < bobs@sagehill.net > Date: Thursday, December 6, 2018 at 1:24 PM To: DocBook Technical Committee < docbook-tc@lists.oasis-open.org > Subject: [docbook-tc] legalsection versus section in legalnotice This email contains an attachment from a external source This email contains an attachment which could be a possible security concern. Attachments can potentially contain computer viruses or malicious content. Do not open this attachment if you do not trust the source of this email. I'm following up on my action item to continue the discussion of the content model of legalnotice to support some kind of section. I have attached the sample files that Larry sent out 23 October 2018. We were debating whether we should allow section within legalnotice or whether we should add a new legalsection element only for legalnotice. I'll try and summarize the discussion so far. The first question I want to ask is whether we are allowing legalnotice to appear outside of info. That would make such a legalnotice into literal content that would always be rendered in the output, as opposed to metadata in info that may or may not be rendered. I believed we discussed this possibility, for example putting several legalnotices in an appendix, but I'm not sure what we decided. That decision would seem to affect how we structure legalnotice, especially if it contains sections. So do we intend to allow legalnotice as regular content outside of info? If we use section within legalnotice, I don't think we resolved whether we would alter the content model when it is used inside legalnotice. That seems to be something we need to decide as it affects the arguments for and against. For example, if we change the content model of section inside legalsection, then you could not cut and paste sections in and out of legalsection without getting validation errors. Also, users of a content-aware editor would experience restrictions in their element selection that they might not understand. If we don't change the model of section inside legalnotice, then both of these arguments no longer apply. So, do we need to change the content model of section inside legalnotice, and if so, how? -- Bob Stayton Sagehill Enterprises bobs@sagehill.net