Export html

[jefferyshivers]

What this mainly does:

Exports html with a header and body.

The user can set the name (or really path to) their CSS file (scholarly.annotate.export.html.css) so that it is automatically linked in the header. Within the body, an "annotations" div encapsulates all the individual annotations. Then they each are held in an "annotation" div, and within that another div of the respective type (critical-remark, etc) which holds divs for each prop. This structure is a little redundant for a simple project with little CSS, but it leaves open the opportunity to alter styles for different annotation types, which I think will be a pretty awesome level of flexibility to have when this all comes together.

The props are set with

\setOption scholarly.annotate.export.html.props
  #`(type grob-location grob-type message [...])

and the labels are set with scholarly.annotate.export.html.labels.

But what it also does:

Changes the write-output-file procedure to ask for a type symbol argument, which is one of html, scheme, latex or plaintext. By default, as before, the module exports the files as <name>.annotations.<default type extension> with the extensions being "html", "inp", "scm" and "log". But the following option lets the user specify an exact output name, or otherwise the aforementioned default:

\setOption
  #`((html . "index.html")
     (latex . default)
     (scheme . default)
     (plaintext . default))

[jefferyshivers]

Ah, I meant to add that it also looks for the html-id = "..." prop and adds that to each "annotation" div if set.

The output of all this is in usage-examples/index.html. Plaintext and LaTeX still export fine as well.

[uliska]

This looks exciting, great to see that your continuing interest spawns new productivity. I hope to be able to look into it this evening.

Based on the description I think there's one additional option to wish (sorry if I should have overlooked it): export the annotations div only, i.e. not a full document. Probably it should also be configurable to produce id= or class=. At least these are the things I found necessary in Frescobaldi's colored source export.

This export option will be a great foundation for creating a GUI annotation viever/editor (in Frescobaldi)!

[uliska]

One could add json to the list

[uliska]

I think we need the option

\registerOption scholarly.annotate.export.html.full-document ##t

here. Of course it also has to be processed somewhere ...

[uliska]

This is a resulting file, isn't it?
If so it shouldn't be included in the commit but rather ~.html be added to the .gitignore file.

[jefferyshivers]

Probably it should also be configurable to produce id= or class=.

Can you clarify what you mean by this? I'll implement it, just not sure what exactly it is.

Thanks for the feedback! 9db4a68 9384bf7 and dc73d39 do the other things.

[uliska]

(Disclaimer: note this is still from only looking at the web interface)

We can't know in what contexts users may want to use the exported HTML - which is why we also want to provide the option to export a full document or only the content div.

For the same reason I suggest that the enclosing div can look either of the following:

<div id="annotations">
<div id="<confiburable-name>">
<div class="annotations">
<div class="<configurable-name>">

Users might want to have multiple such divs in a document (so id might be inappropriate), and users might not want to stick to the preset name.

[jefferyshivers]

We can't know in what contexts users may want to use the exported HTML - which is why we also want to provide the option to export a full document or only the content div.

For the same reason I suggest that the enclosing div can look either of the following:
[...]

Okay thanks for the clarification - so you mean this only for the (currently named) "annotations" div, correct? I agree this should be as flexible as possible, without it being too messy / confusing (of course the alternative is it being too rigid / inflexible..).

Perhaps (and this is assuming we mean just the overall annotations div):

\registerOption scholarly.annotate.export.html.annotations-div-tags
    #`((class . "annotations")
       (id . #f))

Feel free to suggest a better name than annotations-div-tags of course.

Users might want to have multiple such divs in a document (so id might be inappropriate)

Yes, I had that in mind which is why I defaulted to class with a generic "annotations" so that id would be free for custom ID's when documents contain multiple annotations lists.

And now, if we implement this option to name an ID (which should have already been there, I just forgot about it) with the (now committed) option to export that annotations div without header/body stuff, the user can append / manipulate multiple lists together. Maybe Frescobaldi's future annotations viewer can even have a way to simply import multiple documents (containing annotations divs) into the browser?

[jefferyshivers]

How about, an option for referencing/including CSS:

\setOption scholarly.annotate.export.html.with-css ##f         % doesn't link / include any CSS
\setOption scholarly.annotate.export.html.with-css #`header    % prints CSS to header
\setOption scholarly.annotate.export.html.with-css #`linked    % prints a link to the CSS in header

Of course the latter two will only be employed if the html is exported with the header and not just the annotations div.

---

The following option, an updated version of the similar one already in place, for which CSS to use:

• the default packaged CSS which comes included in the repository,

\setOption scholarly.annotate.export.html.use-css #`default

or a new one generated at the time of compilation based on other options (yet to be implemented)

\setOption scholarly.annotate.export.html.use-css #`generate

or one that the user will provide:

\setOption scholarly.annotate.export.html.use-css #`external

---

And finally, this option to set the name of the CSS document which goes into naming the generated CSS and/or what CSS to link to in the header.

% Note: I'm aware this may not actually be the correct quasiquote/string punctuation
\setOption scholarly.annotate.export.html.css-name #`"my-special-css"

[uliska]

OK, I'll first comment on the previous comments and then go and look at the code ...

in fact, the whole "annotations" (or whatever it gets called) div should be configurable as a "ul" (or alternatively ordered list) as well - or even default as that.

I think this is completely true. <ul>/<ol> is semantically what we actually create, and if I'm not mistaken they provide everything a <div> provides with regard to style. So I think <ul> should be the default and <ul> and <div> the selectable exceptions. Based on your previous suggestion:

\registerOption scholarly.annotate.export.html.annotations-div-tags
    #`((type  . "ul")
       (class . "annotations")
       (id    . #f))

the ability to actually print the labels for each prop next to the values

+1

How about, an option for referencing/including CSS:

These are very clear ideas, to which I only add some suggestions:

\setOption scholarly.annotate.export.html.with-css #"my-styles.css" could implicilty set the use-css option to #'external (well, not set to but handle it like that and ignore the use-css option), making the configuration somewhat shorter.

And I suggest to add the following to the wish list (although it is not necessary to implement it right away): \setOption scholarly.annotate.export.html.with-css #'inline, which will generate inline style tags for all elements individually. This leads to very cluttered output but allows to simply paste the generated code into any HTML document without any infrastructure required.

Finally we need (i think) the option to let the user provide a CSS template to use for #'inline or #'header. Or is that what you use use-css` for?

I have this tiny little window between jobs right now to do this, so full speed ahead!

Great!

(Not that I expect you to dedicate the same amount of time, of course).

Actually, I can't. I have a complicated and tightly scheduled commission right now where I have to prove that LilyPond is and that I am capable of tackling a very specific challenge, and additionally the GSoC aspirants require some time dedicated ...

Thanks for being available to work on this.

Thanks for getting back to this. I really think this will be an exciting addition and announcement. Would be great if someone would start on a GUI for this in Frescobaldi. We'll see what GSoC brings ...

[uliska]

OK, you see that I've added a number of commits modifying (and hopefully streamlining) the code in export-html.ily.

I think you have to continue implementing the options we discussed in this thread, but from running the example files I have two questions:

Do you know why there is no location info in the output, shouldn't this be collected automatically?

And do you have any idea why the index.html isn't listed in Fresocbaldi's "Generated Files" list, while the .inp and the .log files are?

[jefferyshivers]

And do you have any idea why the index.html isn't listed in Fresocbaldi's "Generated Files" list, while the .inp and the .log files are?

It appears that the first segment of the filename must match the (first segment, all segments?) of the original.

Changing the generated name to annotate.index.html for example fixes that. But of course that's not a realistic solution. See: frescobaldi/frescobaldi#912

[jefferyshivers]

Do you know why there is no location info in the output, shouldn't this be collected automatically?

Do you mean grob location (Measure n, beat n)?

There isn't automatically printed because this frees the user to, say, have type occur before grob-location in the printed props list, or however else. No reason to hard code that.

\setOption scholarly.annotate.export.html.props #`(type grob-location message)