Support links in <p role="desc"> in script documentation

[josteinaj]

Currently the text is cut off at the first link. E.g.

<p px:role="desc">
    Input HTML. A <a href="http://snaekobbi.github.io/braille-css-spec">braille CSS</a>
    style sheet must be linked from or embedded in the document. See
    <a href="https://code.google.com/p/daisy-pipeline/wiki/ZedAIToPEFDoc#Styling_with_Braille_CSS">examples</a>.
</p>

results in "Input HTML. A".

For clients that support HTML such as the Web UI, it would be useful to allow script descriptions to contain HTML.

[capitancambio]

I'll have a look into it.

[josteinaj]

@capitancambio I'm not sure what the expected output would be in the web api yet though. Would it include all the tags? How would that work with the CLI and the desktop GUI? @bertfrees ?

I'm having a look at using markdown as well (blocked by #102) by doing stuff like this:

<p px:role="desc" xml:space="preserve"><![CDATA[

markdown here
<a href="#">html allowed in markdown if needed</a>
[usually enough with pure markdown though](#)

]]></p>

[bertfrees]

Maybe what I also suggested in https://github.com/daisy/pipeline-webui/issues/47:

[...] could we have a combination of rich descriptions [...] plus simple plain text descriptions for clients that need it? Something like HTML alt vs. longdesc?

[capitancambio]

That depends how far we want to go. i.e. having html for the documentation may be a bit overkill if the target is only having links, what do you think would be useful to support? Headings as well?

[bertfrees]

For options I was mainly thinking about links, yes. That is the most important.

Apart from links I thought about other text-level formatting such as spans with a class, or code elements, etc. Code blocks or example blocks could possibly also be useful. Also (definition) lists (for example to explain values in a dropdown list or something).

I didn't immediately think about headings, because that is more something you would see in longer structured documents, such as a user guide, and the idea is still to use the user interface for short (but rich!) explanations of options, and link from within the script/option descriptions to a more complete user guide on an external page.

[josteinaj]

So how do we allow both simple documentation for the CLI and GUI, as well as rich documentation for the Web UI? There's no "alt" attribute on anything other than <img> afaik, but we could use data-alt or data-shortdesc maybe. Or we could have a separate <p px:role="shortdesc">. Both descriptions could be provided through the web api. Or should the client be able to specify whether or not they want to receive rich documentation or not? We could alternatively solve it by using a convention such as "everything before the first linebreak is the short description", and then leaving it up to the client to extract it.

<p px:role="desc" xml:space="preserve"><![CDATA[
This is the short description.

This is the more extensive documentation with html or markdown or whatever.
]]</p>

wdyt?

[josteinaj]

With #103, using markdown should work. By convention, clients not supporting markdown can get a plain text description with a regex like s/\s*([^\n]*).*?/$1/. @bertfrees @capitancambio wdyt?

[bertfrees]

Something like <p px:role="shortdesc"> is what I had in mind. But maybe your other suggestion is even better. The web UI could render long descriptions so that you only see the first line initially (folded) and the rest can be expanded (similar to what Github does with long commit messages). Other user interfaces can decide to only ever show the first line.

The only potential problem I can see is that you can not choose to make an alternate description that is "equivalent" to the rich description but without markup, because the short and long description add up. And if you want a long description without markup it needs to be on one line. But neither of these are really show stoppers.

The nice thing about Markdown is that if we would like, we could make it perfectly readable with simple clients, for example by simply stripping hyperlinks and HTML tags with some simple regexes. With a bit more effort we can even handle links properly, e.g. by making them into footnotes (or even by using man pages on Linux which support links).

[josteinaj]

The web UI could render long descriptions so that you only see the first line initially (folded)

Good idea.

if you want a long description without markup it needs to be on one line

We could allow multi-line short descriptions by parsing it as a markdown paragraph; i.e. split at the first double-linebreak.

Should I start working on implementing markdown support in the web ui using this method?

[bertfrees]

As far as I'm concerned, yes. I like the approach.

Let's give the others some time to respond maybe: @capitancambio @marisademeglio can you guys live with this?

[capitancambio]

let's do this!

cheers,

Javi

[josteinaj]

@capitancambio @bertfrees ok to merge #103 and close #102 ?

[bertfrees]

lgtm

[capitancambio]

I'd leave 102

cheers,

Javi

[josteinaj]

Ok, I merged #103. @capitancambio Why leave #102 open?

[capitancambio]

Oh! it's done in 103, sorry I said nothing then

[josteinaj]

no problem :)

[bertfrees]

@josteinaj I believe this was fixed, right?

[josteinaj]

Yes, I just checked, we use the markdown link syntax in the descriptions for the braille scripts, and it works in the webui: [title](URL)