On Mon, May 9, 2016 at 10:39 AM, Kris.re <Kris.re@...> wrote:

Sam:

They are definitely supposed to be nested. If you are seeing one like this than either the original template's spacing was equally flat (I could see it for one or two, but not many), or the correction pass I made to remove the redundant list items wasn't quite correct. There were about 3-4 types of failures that I thought I was able to automatically correct, but obviously I didn't look quite deep enough. If you spot these, feel free to label them with a 'bug' label and I will address them in batch. I can roll back the git history and extract the correctly nested version, or at least part of it, or convert it by hand or something.

Philippe:

The initial proposal tried to minimize the use of XML tags at the cost of making whitespace significant. After some discussion, this seemed (besides being a bit of a messy solution) to not meet our needs, and so I revised it so that whitespace was NOT significant, which required more structural tags to identify paragraphs and the like.

Regarding "mixed format and structure", if you're referring to the <b> tag, it is not a format tag but was intended to be "b for bullet". Many of the tags are likely getting renamed and this is probably one of them. The original choice was geared towards having as little visual space taken up by tags as possible, but as you can see we've moved past the point where that's a useful compromise here. If you're referring to <p>, <br/>, <list> or <li>, these are indeed structural tags, though the line is a bit fuzzy because it's often easiest to think about them in formatting terms. We might think of "<br/>" as a new line, which is presentation, as opposed to a structural break between two sections of text, or "<p>" as two new lines as opposed to a grouping of text into a paragraph, for example. Their primary use IS for presentation: we do need to render HTML files as one of our outputs, so we need enough information about the *structure* of the document to *format* it usefully.

> But I think I lost track of the value and purpose of this editing in the first place... can someone refresh me?
Our purpose right now is not primarily editing, though I welcome Sam's contributions on this count, since otherwise it'll be me doing this work ;) The primary work right now is verifying the selection of "matchable sections" of text, which were done partly by an automated process, and partly by myself without full legal understanding and context of these licenses.

> I am questioning the use of XML in first place, which may be a format that is barely OK for saving data files, but is quite terrible for editing IMHO.
I have to agree in most cases, but luckily for us, editing is not something we should have to do a lot of and when we do it will be pretty targeted. The bulk of the effort is the initial construction of the XML file, which can be eased by way of tooling. It does happen that XML is perfect for our particular use case, in my opinion, since what we need to do is mark up some source text somewhat arbitrarily to add information about it. That's something that a data-only format like JSON just doesn't have the capability to elegantly express.

> At least why not use plain HTML if you need to mix format and structure?
> You could then use some of the decent HTML WYSIWYG editing tools available and not have to spend more time on the form than the substance?
I don't know about you, but in the past when I've used such tools, the output HTML is far from minimal and often times a mess. Different tools will produce different HTML, which is a problem when working in a shared space (git repository). A WYSIWYG editor doesn't necessarily have the tools to represent the information we are working with, either: replaceable text, you could perhaps hack as a hyperlink but that would be kind of nasty... and we still have other information to bind, such as the name of the variable to store the match in. Our lists are sometimes ordered, sometimes unordered; when they're ordered, they are often formatted various ways. Adjusting the format to be correct (letters, numbers, roman numerals, whatever) is doable to some extent with css, but not in a way a WYSIWYG editor would necessarily support (what do you do about "2.a)"?) How do you represent sections of text that should be optional?

I like the idea of using an existing such editor naively, but when it comes down to the details we'd essentially be hacking or working around almost every part of the structure of the files except, maybe, list formatting.

I do think that in the future some work to make actually editing the files and creating them easier should be done, and I'll probably be volunteering for that, but I'd like to wrap up by bringing back to the first point: the current effort is not primarily intended to be focused on editing massive swathes of XML, and certainly not creating whole files. After we've vetted the structure of the documents from a legal perspective with regards to matching, there is a lot of programmatic work we can do without worry, so I wouldn't get too wrapped up in the details of the names of tags or stuff like that just yet.

Kris

-----Original Message-----
From: spdx-legal-bounces@... [mailto:spdx-legal-bounces@...] On Behalf Of Philippe Ombredanne
Sent: Monday, May 09, 2016 09:55
To: Sam Ellis <Sam.Ellis@...>
Cc: SPDX-legal (spdx-legal@...) <spdx-legal@...>
Subject: Re: Nested lists in SPDX XML files.

On Mon, May 9, 2016 at 9:25 AM, Sam Ellis <Sam.Ellis@...> wrote:
> Hi,
>
> When reviewing the SPDX XML files, I see many licenses that contain
> nested lists such as:
>
> 1) some text…
>    a) some text…
>
> And these are converted to XML like this:
>
> <list>
>   <li>
>   <b>1)</b><p>some text…</p>
>   </li>
> </list>
> <list>
>   <li>
>   <b>a)</b><p>some text…</p>
>   </li>
> </list>
>
> Note that the XML above places the bullets sequentially rather than
> being nested. I would like to check, does the XML syntax support
> nesting, and if so, should we be using it to represent cases such as this?
>
> To make it clearer, this is how the nested equivalent of the above
> might look, with the a) list inside the 1) list:
>
> <list>
>   <li>
>   <b>1)</b><p>some text…</p>
>   </li>
>   <list>
>     <li>
>     <b>a)</b><p>some text…</p>
>    </li>
>   </list>
> </list>
>
> My view is that by representing nested lists sequentially then we are
> losing some of the structure of the original text. On the other hand,
> if the main purpose of the lists is to allow for identification of
> bullets then the sequential representation is just fine for this.

I have a lot of respect for what you are embarking in:
I would not dare editing by hand 100 of such XML files: I find this rather confusing and error prone.
And I am a programmer...

But I think I lost track of the value and purpose of this editing in the first place... can someone refresh me?

Now, if there is a purpose, you raise a good point in this post (and your previous post about XML entities escaping).
Why is this format mixing structure and formatting together, in a pseudo-HTML format?
Is this meant to become the reference text for SPDX licenses?

I am questioning the use of XML in first place, which may be a format that is barely OK for saving data files, but is quite terrible for editing IMHO.

At least why not use plain HTML if you need to mix format and structure?
You could then use some of the decent HTML WYSIWYG editing tools available and not have to spend more time on the form than the substance?
--
Cordially
Philippe Ombredanne
_______________________________________________
Spdx-legal mailing list
Spdx-legal@...
https://lists.spdx.org/mailman/listinfo/spdx-legal
_______________________________________________
Spdx-legal mailing list
Spdx-legal@...
https://lists.spdx.org/mailman/listinfo/spdx-legal