Eclipse Community Forums: Eclipse SmartHome » ZWave thing descriptions, and HABmin label conventions...

Search

Help

Login

Home » Archived » Eclipse SmartHome » ZWave thing descriptions, and HABmin label conventions...

Show: Today's Messages :: Show Polls :: Message Navigator

Switch to threaded view of this topic

Create a new topic

Submit Reply

ZWave thing descriptions, and HABmin label conventions... [message #1702073]

Sat, 18 July 2015 17:45

Chris Jackson is currently offline

Friend

Messages: 256
Registered: December 2013

Senior Member

Kai/Dennis,
It might be worth you taking a look at what I've written for the ZWave thing description - this is now mostly implemented and working (still a few things to add, but it's mostly there and the binding is running ok).

The description is here, but what really I'd like to point out is the section on label conventions. I am making use of HTML in the descriptions to help improve readability of long descriptions that are often provided in zwave (and probably other systems) for configuration information. This allows HTML, and images to be added into the descriptions.

I know this might not be supported by the PaperUI - at least not yet - but I think it's a useful feature to make the system more user friendly and I assume there's no reason that PaperUI couldn't also support this...

Comments welcome Smile

Smile

Chris

Report message to a moderator

Re: ZWave thing descriptions, and HABmin label conventions... [message #1702218 is a reply to message #1702073]

Mon, 20 July 2015 17:23

Kai Kreuzer is currently offline

Friend

Messages: 673
Registered: December 2011

Senior Member

Hi Chris,

This looks pretty nice!
The "expandable" description is a good idea. We were also already talking about formatting options in the descriptions (mainly for the things itself) and possible images, but since we would like to also generate static documentation from it (see the plan being mentioned in https://www.eclipse.org/smarthome/documentation/development/bindings/docs.html), we were rather thinking about Markdown as a suitable format. It should be fairly easy to consume this in UIs as well through some library like e.g. https://github.com/evilstreak/markdown-js. What do you think about this option?
Where do you expect the image files to be located (in ESH-INF?) and how do you serve them to the UI? I guess this is also something that we would need to define.

Regards,
Kai

Report message to a moderator

Re: ZWave thing descriptions, and HABmin label conventions... [message #1702222 is a reply to message #1702218]

Mon, 20 July 2015 18:05

Chris Jackson is currently offline

Friend

Messages: 256
Registered: December 2013

Senior Member

Hi Kai,
As currently defined/tested, the images are stored directly in the XML as part of the HTML descriptions (just inline base64 encoded). I guess they could be served up from somewhere else in the bundle, but I've not thought through the implications of this. Embedding images in this way would not work for markdown of course. Of course this embedding has some downsides - it probably takes some additional space (base64), it's possibly less maintainable (although that's arguable since a single file is potentially easier), but on the other hand, this should be mostly small, static images and the embedding does make things very simple to serve...

Personally I prefer HTML over MD as it's a bit more rich, and (probably) more universal. I'm not against MD though, but there's certainly things that can't be done in MD... Also, the current ZWave descriptions in OH1 are already using HTML in many cases so it makes them easier to convert...

Why do you prefer MD?

Cheers
Chris

Report message to a moderator

Re: ZWave thing descriptions, and HABmin label conventions... [message #1702426 is a reply to message #1702222]

Wed, 22 July 2015 09:33

Kai Kreuzer is currently offline

Friend

Messages: 673
Registered: December 2011

Senior Member

Chris Jackson wrote on Mon, 20 July 2015 20:05

the embedding does make things very simple to serve...

I didn't even know yet that this is at all possible Smile

Smile

But I think maintaining this is not too nice; having separate image resources within the bundle would probably be easier from a developer perspective.

Quote:

Why do you prefer MD?

Well, the whole online documentation of ESH (like https://www.eclipse.org/smarthome/documentation/features/bindings/hue/readme.html) is based on MD and Jekyll is used to create HTML from it. Embedding any "custom" HTML snippets in there simply won't work for the layout.
Also note that the information should not be tight to HTML apps, but also native apps should be able to handle it. For Markdown, you could e.g. nicely integrate it in an Android app with https://github.com/Uncodin/bypass/blob/master/platform/android/README.md, without the need to embed a WebView in the native app.

Regards,
Kai

Report message to a moderator

Re: ZWave thing descriptions, and HABmin label conventions... [message #1702492 is a reply to message #1702426]

Wed, 22 July 2015 17:09

Chris Jackson is currently offline

Friend

Messages: 256
Registered: December 2013

Senior Member

Kai Kreuzer wrote on Wed, 22 July 2015 10:33

But I think maintaining this is not too nice; having separate image resources within the bundle would probably be easier from a developer perspective.

I agree it has some disadvantages, but when there are maybe a thousand images to maintain, having separate resources will also have its challenges. It is in fact very easy to paste in the files - there are websites that do the conversion to text, and for static files such as these, it's actually quite easy.

However, if you really want MD, then this is all irrelevant, since it isn't possible. As I said, I'm not against MD, but we would need to work out how to serve up the resources in the bundles...

Report message to a moderator

Re: ZWave thing descriptions, and HABmin label conventions... [message #1702621 is a reply to message #1702492]

Thu, 23 July 2015 14:45

Kai Kreuzer is currently offline

Friend

Messages: 673
Registered: December 2011

Senior Member

I see your point about the embedded images, but for the reasons mentioned above, I think HTML is not really an option and we should go for MD.

Report message to a moderator

Re: ZWave thing descriptions, and HABmin label conventions... [message #1702634 is a reply to message #1702621]

Thu, 23 July 2015 16:05

Chris Jackson is currently offline

Friend

Messages: 256
Registered: December 2013

Senior Member

That's fine by me - someone just needs to decide how/where to put the files so they can be served up into the MD. Is that possible without the binding supporting a servlet interface?

Report message to a moderator

Re: ZWave thing descriptions, and HABmin label conventions... [message #1702639 is a reply to message #1702634]

Thu, 23 July 2015 16:42

Chris Jackson is currently offline

Friend

Messages: 256
Registered: December 2013

Senior Member

Hmmm - one word of warning... XML isn't so picky about whitespace - however, in markdown, it is relevant. Depending on implementations we might loose formatting when parsing MD through XML.

For example, putting four spaces at the front of a line in MD has meaning to the MD parser - I suspect that some XML parsers may eliminate this so we will likely need to escape the MD by using CDATA. I also just did a check in Eclipse, and the Eclipse formatter will reformat MD (ie change the whitespace around) unless CDATA is used. It might be best to recommend escaping the MD to avoid strange effects?

Report message to a moderator

Re: ZWave thing descriptions, and HABmin label conventions... [message #1702788 is a reply to message #1702639]

Fri, 24 July 2015 14:42

Chris Jackson is currently offline

Friend

Messages: 256
Registered: December 2013

Senior Member

I fear markdown won't work well Sad

Sad

As above, for markdown to work, we need whitespace and line feeds to be maintained, and this doesn't (currently) appear to be the case. If I have the following XML

				<description>
<![CDATA[Enable/Disable operation of dimmer or roller shutter devices associated to group 1.

Available only when using mono-stable inputs (buttons) - Hold button 1 or double-tap for operation.]]>
				</description>

I get the following in the json

description: "Enable/Disable operation of dimmer or roller shutter devices associated to group 1. Available only when using mono-stable inputs (buttons) - Hold button 1 or double-tap for operation."

So I've lost all the whitespace, and critically the line breaks that I wanted to maintain...

I guess that this is something to do with the xStream reader, but I didn't think it would remove whitespace within CDATA so I'm not 100% sure about that. In any case, I suspect that MD within XML is going to be quite problematic and prone to not working in some implementations.

There is the option to use other versions of MD (eg GFM) which supports the use of some HTML tags so we could (for example) use <br> but I fear once we start moving away from a simple/standard markdown to another non-standard flavour, you're probably just about as well off to use HTML. Even this may not work if we can't maintain line feeds since MD looks for many of its formatters at the beginning of a line... Additionally, the IETF are looking at standardising MD, and from what I can tell html tags aren't supported (although that was only a quick look).

Any thoughts...

Report message to a moderator

Re: ZWave thing descriptions, and HABmin label conventions... [message #1702839 is a reply to message #1702788]

Sat, 25 July 2015 15:59

Chris Jackson is currently offline

Friend

Messages: 256
Registered: December 2013

Senior Member

Your concern above was we shouldn't limit the text to HTML browsers and that Android couldn't render HTML without a webview. That doesn't seem to be the case - there's the HTML class that converts simple HTML into a text view so is just as easy to use as MD, but without the problems associated with embedding in XML.

Without trying it, it looks like the HTML class is built for this purpose (ie rendering of simple marked up text). Here's a list of tags that seem to be supported.

I also don't think that Jekyll makes any difference here since this is a different issue. Jekyll is being used for the documentation where the help text is being embedded into the thing XML descriptions or configuration descriptions so I don't think the two have the same source.

It seems to me that using HTML would be a lot more reliable for the simple markup that we're talking about when embedding within XML... Since the zwave database already does this, I'd be keen to retain it rather than have to convert all the strings that are already written in HTML...

Report message to a moderator

Re: ZWave thing descriptions, and HABmin label conventions... [message #1702885 is a reply to message #1702839]

Mon, 27 July 2015 08:35

Kai Kreuzer is currently offline

Friend

Messages: 673
Registered: December 2011

Senior Member

Quote:

I guess that this is something to do with the xStream reader, but I didn't think it would remove whitespace within CDATA so I'm not 100% sure about that.

Without having analyzed it, I would guess that it is not the XML parser but the JSON serializer, which removes the line breaks and extra spaces. How does JSON actually handle line breaks in content? I think it probably would be escaped somehow?

Quote:

Jekyll is being used for the documentation where the help text is being embedded into the thing XML descriptions or configuration descriptions so I don't think the two have the same source.

Not sure if I understand what you are saying here. Aren't we talking about documentation that is embedded in the thing XML descriptions (incl. their config descs)?

Report message to a moderator

Re: ZWave thing descriptions, and HABmin label conventions... [message #1702892 is a reply to message #1702885]

Mon, 27 July 2015 09:23

Chris Jackson is currently offline

Friend

Messages: 256
Registered: December 2013

Senior Member

Kai Kreuzer wrote on Mon, 27 July 2015 09:35

Without having analyzed it, I would guess that it is not the XML parser but the JSON serializer, which removes the line breaks and extra spaces. How does JSON actually handle line breaks in content? I think it probably would be escaped somehow?

You might be right, or it might be a combination of things. I wouldn't think that the json serialiser would remove multiple spaces (I might be wrong, but it would seem very strange to not be able to send two spaces together in a json string!). Json might remove the CR/LF - this possibly could be escaped.
From what I could see, we were loosing extra spaces as well as line feeds - both are necessary for MD to work, so it might be partly the json loosing the LF, but if something else (XML) is also loosing the extra spaces, then we're still in trouble.

Kai Kreuzer wrote on Mon, 27 July 2015 09:35

Not sure if I understand what you are saying here. Aren't we talking about documentation that is embedded in the thing XML descriptions (incl. their config descs)?

I was assuming that you weren't planning on using the config descriptions for producing documentation, but rather the README.MD (and other similar) files? Or are you also planning on somehow parsing all the config descriptions, and the options etc as well within Jekyll?

Report message to a moderator

Re: ZWave thing descriptions, and HABmin label conventions... [message #1702896 is a reply to message #1702892]

Mon, 27 July 2015 09:43

Kai Kreuzer is currently offline

Friend

Messages: 673
Registered: December 2011

Senior Member

Well, as written at https://www.eclipse.org/smarthome/documentation/development/bindings/docs.html, the idea is to generate parts of the README.MD from the files in the ESH-INF folder; and yes, I would not see why the config descriptions should be excluded from it. Even if they were, it would be a bit weird to ask people for HTML documentation within config descriptions and for MD documentation within things/channels, so we should decide for one or the other.

Report message to a moderator

Re: ZWave thing descriptions, and HABmin label conventions... [message #1702898 is a reply to message #1702896]

Mon, 27 July 2015 09:57

Chris Jackson is currently offline

Friend

Messages: 256
Registered: December 2013

Senior Member

Quote:

so we should decide for one or the other

While I don't disagree, there is a middle ground...

What 'version' of Markdown do you support? Looking at the readme files, they include a lot of 'extra' markdown features that aren't part of the 'standard' - it looks like it's possibly GFM?

Some of these Markdown variants (including GFM) supports limited use of HTML tags - things like line breaks, lists, bold, italics - all the simple things that we're likely to want in a simple config description. So, an option might be to define a small subset of HTML that is also supported by (some/many) markdown interpreters - effectively a subset of each, so we're compatible with both? If you look at the HTML supported by the Android HTML class, it's probably also supported in GFM, and it's probably about all we need for config descriptions?

There are a LOT of markdown interpreters on the web - given there's no standard (yet), and lots of different flavours, it does mean there's the potential for incompatibilities...

Report message to a moderator

Re: ZWave thing descriptions, and HABmin label conventions... [message #1703057 is a reply to message #1702898]

Tue, 28 July 2015 11:44

Kai Kreuzer is currently offline

Friend

Messages: 673
Registered: December 2011

Senior Member

Well, the main constraint is that stuff should work with Jekyll and I am not sure if this allows embedded HTML as it needs to fit that into its own templates and add class attributes etc. to it.
I think I better leave the further discussion to Dennis as he is a much better Jekyll expert than I am...

But I agree, if some simple HTML subset is ok for Jekyll, this could indeed be a good compromise.

Report message to a moderator

Re: ZWave thing descriptions, and HABmin label conventions... [message #1703537 is a reply to message #1703057]

Sun, 02 August 2015 20:58

Dennis Nobel is currently offline

Friend

Messages: 166
Registered: September 2014

Senior Member

We use GFM for Jekyll (see https://github.com/eclipse/smarthome/blob/master/docs/_config.yml#L17). As this is the github style, it should be the a well known and wide-spread flavor. But I´m not sure if the kramdown parser supports embedded HTML. We have to test it out.

But generally I´m not a big fan of putting HTML into Markdown (or putting embedded XML into the thing description XML), because it opens a door for a lot of stuff, which is maybe not wanted in UIs. And it looks a bit dirty. Does the schema really allows it?

We did never clearly define what the description should hold and how long it should be or what is the correct data format. But at least I never had in mind to put a lot of sentences including images and structural elements.

Report message to a moderator

Re: ZWave thing descriptions, and HABmin label conventions... [message #1703540 is a reply to message #1703537]

Sun, 02 August 2015 21:14

Chris Jackson is currently offline

Friend

Messages: 256
Registered: December 2013

Senior Member

Quote:

Does the schema really allows it?

As above, it seems quite problematic since MD requires the structure of the data to be maintained, and I'm not sure that this is possible.

Quote:

But at least I never had in mind to put a lot of sentences including images and structural elements.

I strongly suggest that this is supported - it will be a major mess if the structure of descriptions etc is not maintained. Where you have many options, you need to describe them, and without lists, and font enhancements, it will just be a mess. This is supported already in the zwave binding, and if we need to remove all the structure, it won't be particularly usable.

We need to find a way to support this - I fear MD doesn't work (based on my tests, but I've not spent more than an hour or two trying) and basic HTML seems a reasonable way forward, but if you have another approach then I'm more than happy...

For now at least, the ZWave binding will have HTML included in the descriptions simply because many database files are already formatted in this way and I'm automatically converting the data over...

Cheers
Chris

Report message to a moderator

Re: ZWave thing descriptions, and HABmin label conventions... [message #1703571 is a reply to message #1703540]

Mon, 03 August 2015 08:40

John Cocula is currently offline

Friend

Messages: 21
Registered: June 2015

Junior Member

I think it would be valuable to set out the goal that all envisioned clients must support embedding a defined subset of HTML for rich text rendering, and then testing that goal against the base toolsets for various clients to make sure it's reasonable (I believe it is). MD is nice when you are starting from a text file and don't want to do the HTML encoding by hand when you're writing docs, but as Chris said, the hoops you have to jump through to have it delivered and rendered properly in a wide range of clients are much more problematic than starting with a simple HTML subset. Pushing raw MD to browsers and apps instead of HTML involves more hoops to jump through in comparison, places a higher burden on the client, and risks losing rich text value in the cases where clients can't render MD for display (but can render HTML already).

Report message to a moderator

Re: ZWave thing descriptions, and HABmin label conventions... [message #1703575 is a reply to message #1703571]

Mon, 03 August 2015 10:04

Chris Jackson is currently offline

Friend

Messages: 256
Registered: December 2013

Senior Member

I think MD or HTML can be rendered just as easily (often MD gets converted to HTML anyway) - so long as only 'basic' HTML elements are used (lists, bold, italics, titles, underline...). The big issue that I see is that MD needs to maintain whitespace, line feeds, etc - if you don't do this, it's not MD any more - it's just a mess... Currently, the system doesn't do this, so MD can not be used as it currently stands...

Report message to a moderator

Re: ZWave thing descriptions, and HABmin label conventions... [message #1703686 is a reply to message #1703575]

Tue, 04 August 2015 09:30

John Cocula is currently offline

Friend

Messages: 21
Registered: June 2015

Junior Member

Chris, do you mean that various mobile clients should be expected to render a specific variation of Markdown as easily as HTML? Once it's delivered to mobile clients intact without loss of whitespace, etc., should mobile client developers be expected to format it correctly?

Report message to a moderator

Re: ZWave thing descriptions, and HABmin label conventions... [message #1703691 is a reply to message #1703686]

Tue, 04 August 2015 09:54

Chris Jackson is currently offline

Friend

Messages: 256
Registered: December 2013

Senior Member

Well, if MD is chosen, then yes Smile

Smile

I don't think this should be a problem (or is it?).

Generally, there are libraries out there that do this, in the same way as there are libraries out there to render HTML. For example, for Android, there is a class (HTML) that converts basic HTML into a format that can be displayed in the view (without having to add a full webview!). I believe there's a similar class that will do the same thing for MD, so roughly speaking, there's not a lot of difference I think. There are a number of libraries that convert from MD to HTML using a relatively simple regex to convert MD tags to HTML tags, so if you can do HTML, you can do MD.

Again, I'm only talking about 'simple' HTML - basic font enhancements, formatting and lists, which is what the HTML class in Android supports and should be all that's needed for help text and descriptions in the XML files.

Report message to a moderator

Re: ZWave thing descriptions, and HABmin label conventions... [message #1703692 is a reply to message #1703691]

Tue, 04 August 2015 09:56

Chris Jackson is currently offline

Friend

Messages: 256
Registered: December 2013

Senior Member

Oh - and I should have added, that my preference is still for HTML (which is what I currently use in the zwave binding), but my answer above is such that I don't think it really matters too much if we could solve the transport problems - which I suspect might be difficult.

Report message to a moderator

Re: ZWave thing descriptions, and HABmin label conventions... [message #1703702 is a reply to message #1703692]

Tue, 04 August 2015 10:26

John Cocula is currently offline

Friend

Messages: 21
Registered: June 2015

Junior Member

Thanks for the replies, Chris.

My opinion, for what it's worth, is that sending raw MD to a client for rendering instead of an HTML subset will lead to extra complexity and loss of capability (like base64 images for example) in the client, much of which could be overcome (depending on which tools exist for the client in question), but which doesn't "feel" like a worthwhile tradeoff. At build time, Jekyll can handle interleaved MD/HTML to produce HTML for client rendering, which ought to be more easily accomplished in any foreseeable client implementation.

Report message to a moderator

Re: ZWave thing descriptions, and HABmin label conventions... [message #1703713 is a reply to message #1703702]

Tue, 04 August 2015 11:28

Chris Jackson is currently offline

Friend

Messages: 256
Registered: December 2013

Senior Member

Quote:

At build time, Jekyll can handle interleaved MD/HTML to produce HTML for client rendering

I know next to nothing about Jekyll, but if you're sure this is the case, then as per the discussion earlier in this thread, we (ie me and Kai) agreed that a subset of HTML would be an appropriate way forward.

As above, my preference is strongly to use HTML to avoid problems. I don't think the statements like "it doesn't look as nice as MD" are really that relevant given that this is embedded in an XML document - it looks horrible anyway due to the XML! It's the same point I made about the maintenance of base64 embedded images - I think the maintenance issues are outweighed by the ease of serving given these are static files...

However, while I would like to include images (a lot of ZWave manuals are supported by images to ease the explanations), I can see an argument to keep this out and rely simply on a simple subset of HTML to provide text support. It's not my preference, but it's possible...

Report message to a moderator

Re: ZWave thing descriptions, and HABmin label conventions... [message #1703732 is a reply to message #1703575]

Tue, 04 August 2015 13:20

Kai Kreuzer is currently offline

Friend

Messages: 673
Registered: December 2011

Senior Member

Nothing to add from my side. IF Jekyll supports mixing MD with HTML, a small subset of HTML tags would be ok for me. What set do you exactly have in mind?
<b>, <br>, <em>, <h1>, <h2>, <h3>, <h4>, <h5>, <h6>, <i>, <p>, <small>, <strong>, <sub>, <sup>, <ul>, <ol>, <li>?

Report message to a moderator

Re: ZWave thing descriptions, and HABmin label conventions... [message #1703737 is a reply to message #1703732]

Tue, 04 August 2015 13:48

Chris Jackson is currently offline

Friend

Messages: 256
Registered: December 2013

Senior Member

Hi Kai,
Yes - that looks like about the list I had in mind. I think that this ought to be enough to provide reasonably rich help/descriptions...

Chris

Report message to a moderator

Re: ZWave thing descriptions, and HABmin label conventions... [message #1704087 is a reply to message #1703737]

Fri, 07 August 2015 09:12

Dennis Nobel is currently offline

Friend

Messages: 166
Registered: September 2014

Senior Member

Hi,

for me XML is also OK, but we need to solve a few issues:

1) the schema does not support it. We need to modify the schema to allow mixed content (http://www.w3schools.com/schema/schema_complex_mixed.asp). Or did you had in mind to quote the XML elements with the description element?
2) as far as I understood the parser does not support it at the moment. So it needs to be adapted. It will also make a difference if we use mixed content or quoted XML. What do we expect the description variable in the Java model should hold? Just a String containing the XML lements?
3) We need to make sure that it also works with the i18n concept. So it must be possible to define XML in the properties file, too. But this should not be a problem I guess. But it also depends what is the decision on 1) and 2)

Regards

Dennis

Report message to a moderator

Re: ZWave thing descriptions, and HABmin label conventions... [message #1704090 is a reply to message #1704087]

Fri, 07 August 2015 09:23

Chris Jackson is currently offline

Friend

Messages: 256
Registered: December 2013

Senior Member

Dennis Nobel wrote on Fri, 07 August 2015 10:12

for me XML is also OK, but we need to solve a few issues:

You mean HTML right?

Quote:

1) the schema does not support it.

HTML needs to be escaped with the CDATA escape sequence and it works fine. Or are you suggesting not using the escape - then this will be a lot more work Sad

Sad

Quote:

2) as far as I understood the parser does not support it at the moment.

It is working fine now if you use the CDATA escape. I would propose to use this - otherwise we make a LOT more work for ourselves!

Quote:

Just a String containing the XML lements?

I'm wondering if I'm getting confused - you keep saying XML so maybe I'm not understanding what you mean? I'm assuming you mean HTML elements?

Quote:

3) We need to make sure that it also works with the i18n concept. So it must be possible to define XML in the properties file, too.

I don't see why you can't put HTML in the i18 files. This would work a lot better than MD since the i18 files are (I believe) not well structured. MD could not work with the i18n at all since if I remember correctly the i18n strings need to be on a single line.

Chris

Report message to a moderator

Re: ZWave thing descriptions, and HABmin label conventions... [message #1704092 is a reply to message #1704090]

Fri, 07 August 2015 09:37

Dennis Nobel is currently offline

Friend

Messages: 166
Registered: September 2014

Senior Member

OK, if we use CDATA (which is the quote solution) then it´s easy. First thought that we want to use mixed content. I guess in the property files we can just put the concrete HTML elements without the CDATA.

Is this already working with parser at the moment? So that the only thing left to do is the documentation?

Report message to a moderator

Re: ZWave thing descriptions, and HABmin label conventions... [message #1704095 is a reply to message #1704092]

Fri, 07 August 2015 09:49

Chris Jackson is currently offline

Friend

Messages: 256
Registered: December 2013

Senior Member

Dennis Nobel wrote on Fri, 07 August 2015 10:37

Is this already working with parser at the moment? So that the only thing left to do is the documentation?

Yes - this is what I'm already doing in zwave and habmin - no changes necessary.

Report message to a moderator

Re: ZWave thing descriptions, and HABmin label conventions... [message #1704104 is a reply to message #1704095]

Fri, 07 August 2015 10:45

Dennis Nobel is currently offline

Friend

Messages: 166
Registered: September 2014

Senior Member

Ok perfect, sorry for confusion Smile

Smile

If you want you could contribute a small documentation update and you can also create an issue, that the Paper UI should support embedded HTML in description texts: https://github.com/openhab/smarthome.paperui/issues.

Report message to a moderator

Re: ZWave thing descriptions, and HABmin label conventions... [message #1704208 is a reply to message #1704104]

Sat, 08 August 2015 20:58

Chris Jackson is currently offline

Friend

Messages: 256
Registered: December 2013

Senior Member

Bug raised and PR submitted for the documentation updates Smile

Smile

Oops - I've just realised that I raised the bug against the ESH bugzilla - rather than the OH2 Github that I've realised you referenced above. Sorry - I'd thought that it was covered under ESH?

Report message to a moderator

Re: ZWave thing descriptions, and HABmin label conventions... [message #1704210 is a reply to message #1704208]

Sat, 08 August 2015 21:05

Kai Kreuzer is currently offline

Friend

Messages: 673
Registered: December 2011

Senior Member

No, the Paper UI is not (yet) at Eclipse, but the plan is to move it (see https://github.com/openhab/smarthome.paperui/issues/3).
So for the moment, we have to track bugs on Github for it!

Report message to a moderator

Re: ZWave thing descriptions, and HABmin label conventions... [message #1710934 is a reply to message #1704210]

Sun, 11 October 2015 12:12

Markus Rathgeb is currently offline

Friend

Messages: 105
Registered: August 2014

Senior Member

maggu2810@jabber.ccc.de

Just want to revisit the topic about the CDATA section. Also reading the cites here https://bugzilla.mozilla.org/show_bug.cgi?id=226786. Is it allowed that the new lines / whitespaces are removed? I think it shouldn't, or am I wrong?
If it should not removed, we have to ensure that they are not removed.

I used markdown at different stuff with different parsers and always run in trouble, that all the results looks different. Have to note, that I do not know, what are standard markdown and what are extensions of the parsers.
So we should at least document a link to a markdown spec and the HTML features we would like to support.

What is the current status?

Report message to a moderator

Re: ZWave thing descriptions, and HABmin label conventions... [message #1710941 is a reply to message #1710934]

Sun, 11 October 2015 14:50

Chris Jackson is currently offline

Friend

Messages: 256
Registered: December 2013

Senior Member

As per the discussion in this thread, we agreed to use a limited set of HTML - this avoids issues with whitespace. I updated the ESH docs a few months back to reflect this agreement, and to document the permitted HTML tags...

IMHO markdown will not work reliably inside XML, and therefore HTML should be used...

Report message to a moderator

Re: ZWave thing descriptions, and HABmin label conventions... [message #1710942 is a reply to message #1710941]

Sun, 11 October 2015 14:58

Markus Rathgeb is currently offline

Friend

Messages: 105
Registered: August 2014

Senior Member

maggu2810@jabber.ccc.de

I have read, that Markdown and a HTML subset is used. But if whitespaces should be preserved using the CDATA section of XMLs (but I am not 100% sure about) and this is not done, it is a bug (regardless if we need that whitespaces ATM or not).

Report message to a moderator

Re: ZWave thing descriptions, and HABmin label conventions... [message #1710944 is a reply to message #1710942]

Sun, 11 October 2015 15:03

Chris Jackson is currently offline

Friend

Messages: 256
Registered: December 2013

Senior Member

I would not use markdown since it will not work reliably. HABmin doesn't support it, and currently PaperUI doesn't either (I don't know if Denis is planning this). I don't believe that markdown can work properly since the formatting needs to be maintained 100%, and I don't think that this can be guaranteed once inside XML.

If we stick to HTML, there should be no problem.

Report message to a moderator

Re: ZWave thing descriptions, and HABmin label conventions... [message #1710945 is a reply to message #1710944]

Sun, 11 October 2015 15:28

Markus Rathgeb is currently offline

Friend

Messages: 105
Registered: August 2014

Senior Member

maggu2810@jabber.ccc.de

@Chris
I don't talk about HTML and Markdown. If we stick to HTML than that this will work for this use case.

I think about ESH as a Framework that parts could be used by different developers, companies etc. We do not know how the software is used be other ones. If we are using XML we have to handle CDATA correctly. Regardless if we could accept wrong handling in our use cases ATM.

Report message to a moderator

Re: ZWave thing descriptions, and HABmin label conventions... [message #1710949 is a reply to message #1710945]

Sun, 11 October 2015 18:08

Kai Kreuzer is currently offline

Friend

Messages: 673
Registered: December 2011

Senior Member

Markus, which problem with CDATA are you referring to exactly? https://bugzilla.mozilla.org/show_bug.cgi?id=226786 is not a valid link...

Report message to a moderator

Re: ZWave thing descriptions, and HABmin label conventions... [message #1710953 is a reply to message #1702788]

Sun, 11 October 2015 18:51

Markus Rathgeb is currently offline

Friend

Messages: 105
Registered: August 2014

Senior Member

maggu2810@jabber.ccc.de

I have read this read today from the beginning.

Chris Jackson wrote on Fri, 24 July 2015 14:42

So I've lost all the whitespace, and critically the line breaks that I wanted to maintain...

I guess that this is something to do with the xStream reader, but I didn't think it would remove whitespace within CDATA so I'm not 100% sure about that.

Kai Kreuzer wrote on Mon, 27 July 2015 08:35

Without having analyzed it, I would guess that it is not the XML parser but the JSON serializer, which removes the line breaks and extra spaces.

So, two options:

the XML parser does remote whitespaces in the CDATA section
the JSON serializer does remove the whitespaces

The removal of the whitespaces has not been identified -- I do not find something in this thread.

I checked if it is allowed to remove whitespaces in a XML CDATA section (because I want to know it). I found a bug entry of a Mozilla product that covers the removal of whitespaces in CDATA section in their product.

I would like to know your opinion if you think whitespaces must not removed, so I have written:
Markus Rathgeb wrote Sun, 11 October 2015 12:12

Just want to revisit the topic about the CDATA section. Also reading the cites here https://bugzilla.mozilla.org/show_bug.cgi?id=226786. Is it allowed that the new lines / whitespaces are removed? I think it shouldn't, or am I wrong?
If it should not removed, we have to ensure that they are not removed.

Perhaps my questions / explanations have been not clear. But I think the link is valid as source for more information, as it contains a reference to the W3C XML specification and another book.

Just want to ensure that the XML parser is working correctly.

Confused

Confused

Report message to a moderator

Re: ZWave thing descriptions, and HABmin label conventions... [message #1710954 is a reply to message #1710953]

Sun, 11 October 2015 18:59

Kai Kreuzer is currently offline

Friend

Messages: 673
Registered: December 2011

Senior Member

Sorry, I clicked the link as it appears in the forum and it has a trailing "." - and hence is indeed invalid. If I manually remove it, I can see the discussion at Mozilla around this. The Mozilla issue seems about displaying the XML, so it is more processing than just parsing the model. I would not expect that anything from CDATA gets lost in our parser.

Report message to a moderator

Switch to threaded view of this topic

Create a new topic

Submit Reply

Previous Topic:	Aliasing supported-bridge-type-refs
Next Topic:	System state

Goto Forum:

-=] Back to Top [=-

[ Syndicate this forum (XML) ] [

]

Current Time: Wed Apr 24 19:15:20 GMT 2024

Powered by FUDForum. Page generated in 0.06421 seconds

.:: Contact :: Home ::.

Powered by: FUDforum 3.0.2.
Copyright ©2001-2010 FUDforum Bulletin Board Software

Back to the top